diff options
27 files changed, 84 insertions, 964 deletions
diff --git a/docs/conf.py b/docs/conf.py index 799ec7820..ee852aa51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -90,39 +90,9 @@ intersphinx_mapping = { 'zcml': ('http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest', None), - 'pyramid': ( - 'http://docs.pylonsproject.org/projects/pyramid/en/latest/', - None) } -#intersphinx_mapping = { -# 'python': ( -# 'http://docs.python.org/2', -# None), -# 'sqla': ( -# 'http://docs.sqlalchemy.org/en/latest', -# None), -# 'pyramid': ( -# 'http://docs.pylonsproject.org/projects/pyramid/en/latest/', -# None), -# 'jinja2': ( -# 'http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/', -# None), -# 'toolbar': ( -# 'http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest', -# None), -# 'deform': ( -# 'http://docs.pylonsproject.org/projects/deform/en/latest', -# None), -# 'colander': ( -# 'http://docs.pylonsproject.org/projects/colander/en/latest', -# None), -# 'tutorials': ( -# 'http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', -# None), -#} - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst index 6b9b5fafc..aaebba7ea 100644 --- a/docs/quick_tutorial/authentication.rst +++ b/docs/quick_tutorial/authentication.rst @@ -102,7 +102,7 @@ one step at a time, we provide a system that identifies users and lets them log out. In this example we chose to use the bundled -:ref:`AuthTktAuthenticationPolicy <pyramid:authentication_module>` +:ref:`AuthTktAuthenticationPolicy <authentication_module>` policy. We enabled it in our configuration and provided a ticket-signing secret in our INI file. @@ -130,5 +130,5 @@ Extra Credit onto each request? Use ``import pdb; pdb.set_trace()`` to answer this. -.. seealso:: :ref:`pyramid:security_chapter`, - :ref:`AuthTktAuthenticationPolicy <pyramid:authentication_module>` +.. seealso:: :ref:`security_chapter`, + :ref:`AuthTktAuthenticationPolicy <authentication_module>` diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst index 37b1a0520..9acd3b4a5 100644 --- a/docs/quick_tutorial/authorization.rst +++ b/docs/quick_tutorial/authorization.rst @@ -41,7 +41,7 @@ Steps (env27)$ python setup.py develop #. Start by changing ``authorization/tutorial/__init__.py`` to - specify a root factory to the :term:`pyramid:configurator`: + specify a root factory to the :term:`configurator`: .. literalinclude:: authorization/tutorial/__init__.py :linenos: diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst index e44ef616d..e3ad820ac 100644 --- a/docs/quick_tutorial/hello_world.rst +++ b/docs/quick_tutorial/hello_world.rst @@ -70,19 +70,19 @@ explanation: #. *Line 11*. The ``if __name__ == '__main__':`` is Python's way of saying "Start here when running from the command line". -#. *Lines 12-14*. Use Pyramid's :term:`pyramid:configurator` to connect - :term:`pyramid:view` code to a particular URL - :term:`pyramid:route`. +#. *Lines 12-14*. Use Pyramid's :term:`configurator` to connect + :term:`view` code to a particular URL + :term:`route`. #. *Lines 6-7*. Implement the view code that generates the - :term:`pyramid:response`. + :term:`response`. -#. *Lines 15-17*. Publish a :term:`pyramid:WSGI` app using an HTTP +#. *Lines 15-17*. Publish a :term:`WSGI` app using an HTTP server. -As shown in this example, the :term:`pyramid:configurator` plays a +As shown in this example, the :term:`configurator` plays a central role in Pyramid development. Building an application from -loosely-coupled parts via :ref:`pyramid:configuration_narr` is a +loosely-coupled parts via :ref:`configuration_narr` is a central idea in Pyramid, one that we will revisit regularly in this *Quick Tour*. diff --git a/docs/quick_tutorial/index.rst b/docs/quick_tutorial/index.rst index 9d32f9a81..857364731 100644 --- a/docs/quick_tutorial/index.rst +++ b/docs/quick_tutorial/index.rst @@ -5,7 +5,7 @@ Quick Tutorial for Pyramid ========================== Pyramid is a web framework for Python 2 and 3. This tutorial gives a -Python 2/3-compatible, high-level tour of the major features. +Python 3/2-compatible, high-level tour of the major features. This hands-on tutorial covers "a little about a lot": practical introductions to the most common facilities. Fun, fast-paced, and most diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 85b07812e..66247c92d 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -9,7 +9,7 @@ Background ========== Pyramid has a first-class concept of -:ref:`configuration <pyramid:configuration_narr>` distinct from code. +:ref:`configuration <configuration_narr>` distinct from code. This approach is optional, but its presence makes it distinct from other Python web frameworks. It taps into Python's ``setuptools`` library, which establishes conventions for how Python projects can be @@ -82,7 +82,7 @@ Analysis Our ``development.ini`` file is read by ``pserve`` and serves to bootstrap our application. Processing then proceeds as described in the Pyramid chapter on -:ref:`application startup <pyramid:startup_chapter>`: +:ref:`application startup <startup_chapter>`: - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial`` @@ -132,11 +132,11 @@ Extra Credit it the ``main`` function. Why not? .. seealso:: - :ref:`pyramid:project_narr`, - :ref:`pyramid:scaffolding_chapter`, - :ref:`pyramid:what_is_this_pserve_thing`, - :ref:`pyramid:environment_chapter`, - :ref:`pyramid:paste_chapter` + :ref:`project_narr`, + :ref:`scaffolding_chapter`, + :ref:`what_is_this_pserve_thing`, + :ref:`environment_chapter`, + :ref:`paste_chapter` Extra Credit ============ diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 213de8364..f08db6849 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -96,6 +96,6 @@ Python can't natively JSON encode DateTime objects. There are a number of solutions for this in Pyramid, including extending the JSON renderer with a custom renderer. -.. seealso:: :ref:`pyramid:views_which_use_a_renderer`, - :ref:`pyramid:json_renderer`, and - :ref:`pyramid:adding_and_overriding_renderers` +.. seealso:: :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst index a81b961b0..e68cd536b 100644 --- a/docs/quick_tutorial/logging.rst +++ b/docs/quick_tutorial/logging.rst @@ -74,4 +74,4 @@ visit ``http://localhost:6543`` your console will now show:: Also, if you have configured your Pyramid application to use the ``pyramid_debugtoolbar``, logging statements appear in one of its menus. -.. seealso:: See Also: :ref:`pyramid:logging_chapter` +.. seealso:: See Also: :ref:`logging_chapter` diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst index b01e17a67..4a4b62683 100644 --- a/docs/quick_tutorial/more_view_classes.rst +++ b/docs/quick_tutorial/more_view_classes.rst @@ -20,7 +20,7 @@ So far our views have been simple, free-standing functions. Many times your views are related: different ways to look at or work on the same data or a REST API that handles multiple operations. Grouping these together as a -:ref:`view class <pyramid:class_as_view>` makes sense: +:ref:`view class <class_as_view>` makes sense: - Group views @@ -29,7 +29,7 @@ together as a - Share some state and helpers Pyramid views have -:ref:`view predicates <pyramid:view_configuration_parameters>` that +:ref:`view predicates <view_configuration_parameters>` that help determine which view is matched to a request. These predicates provide many axes of flexibility. @@ -176,5 +176,5 @@ Extra Credit #. There is also a ``request.route_path`` API. How does this differ from ``request.route_url``? -.. seealso:: :ref:`pyramid:class_as_view`, `Weird Stuff You Can Do With +.. seealso:: :ref:`class_as_view`, `Weird Stuff You Can Do With URL Dispatch <http://www.plope.com/weird_pyramid_urldispatch>`_ diff --git a/docs/quick_tutorial/pyramid_setup.rst b/docs/quick_tutorial/pyramid_setup.rst index 5efcc7dc7..187a25adf 100644 --- a/docs/quick_tutorial/pyramid_setup.rst +++ b/docs/quick_tutorial/pyramid_setup.rst @@ -2,26 +2,14 @@ Pyramid Setup ============= -Installing Pyramid is easy and normal from a Python packaging -perspective. Again, *make sure* you have your virtual environment first -in your path using ``source bin/activate``. +We now have a standard starting point for Python. Getting Pyramid +installed is easy: .. code-block:: bash - (env27)$ easy_install pyramid - ....chuggalugga... - (env27ß)$ which pserve + $ easy_install pyramid -You now have Pyramid installed. The second command confirms this by -looking for the Pyramid ``pserve`` command that should be on your -``$PATH`` in the ``bin`` of your virtual environment. +Our virtual environment now has the Pyramid software available to its +Python. -Installing Everything -===================== - -Later parts of the tutorial install more packages. Most likely, -you'd like to go ahead and get much of it now: - -.. code-block:: bash - - (env27)$ easy_install pyramid nose webtest deform sqlalchemy
\ No newline at end of file +.. seealso:: See Also: :ref:`installing_unix` diff --git a/docs/quick_tutorial/python_setup.rst b/docs/quick_tutorial/python_setup.rst index 2d56a0327..5ac32dc97 100644 --- a/docs/quick_tutorial/python_setup.rst +++ b/docs/quick_tutorial/python_setup.rst @@ -2,87 +2,46 @@ Python Setup ============ -First things first: we need our Python environment in ship-shape. -Pyramid encourages standard Python development practices (virtual -environments, packaging tools, logging, etc.) so let's get our working -area in place. - .. note:: - This tutorial is aimed at Python 2.7. It also works with - Python 3.3. - -*This step has most likely been performed already on the CCDC computers.* - -Prequisites -=========== + This tutorial is aimed at Python 3.3. It also works with + Python 2.7. -Modern Python development means two tools to add to the standard -Python installation: packaging and virtual environments. - -Python's tools for installing packages is undergoing rapid change. For -this tutorial, we will install the latest version of -`setuptools <https://pypi.python.org/pypi/setuptools/>`_. This gives us -the ``easy_install`` command-line tool for installing Python packages. -Presuming you have Python on your ``PATH``: +First thing's first: we need our Python environment in ship-shape. +Pyramid encourages standard Python development practices (virtual +environments, packaging tools, logging, etc.) so let's get our working +area in place. For Python 3.3: .. code-block:: bash + $ pyvenv-3.3 env33 + $ source env33/bin/activate $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python -We now have an ``easy_install`` command that we can use to install -``virtualenv``: - -.. code-block:: bash - - $ easy_install virtualenv - -Making a Virtual Environment -============================ - -Developing in isolation helps us ensure what we are learning doesn't -conflict with any packages installed from other work on the machine. -*Virtual environments* let us do just this. - -Presuming you have made a tutorial area at some location (referenced as -``your/tutorial/directory`` below): +If ``wget`` complains with a certificate error, run it with: .. code-block:: bash - $ cd your/tutorial/directory - $ virtualenv env27 - $ source env27/bin/activate - (env27)$ which python2.7 + $ wget --no-check-certificate -Once you do this, your path will be setup to point at the ``bin`` of -your virtual environment. Your prompt will also change, as noted above. +In these steps above we first made a :term:`virtualenv` and then +"activated" it, which adjusted our path to look first in +``env33/bin`` for commands (such as ``python``). We next downloaded +Python's packaging support and installed it, giving us the +``easy_install`` command-line script for adding new packages. Python +2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make +their virtual environment. .. note:: - This tutorial presumes you are working in a command-line shell - which has performed the ``source env27/bin/activate``. If you - close that shell, or open a new one, you will need to re-perform - that command. - -Discussion -========== - -The modern world of Python packaging eschews ``easy_install`` in favor -of ``pip``, a more-recent and maintained packaging tool. Why doesn't -this tutorial use it? - -- ``pip`` is only gradually getting the ability to install Windows - binaries. ``easy_install`` has been able to do this for years. - -- Until recently, ``pip`` has not been able to use "namespace - packages." As the ``pip`` support for this stabilizes, - we can switch to using ``pip``. - -- You have to use ``easy_install`` to get ``pip`` installed, so why not - just stick with ``easy_install``. - -Python 3.3 has a `built-in story for virtual -environments <http://docs.python.org/dev/library/venv.html>`_. This -eliminates the requirement for installing ``virtualenv``. Instead, -Python 3.3 provides the ``pyvenv`` command for creating virtual -environments.
\ No newline at end of file + Why ``easy_install`` and not ``pip``? Pyramid encourages use of + namespace packages which, until recently, ``pip`` didn't permit. + Also, Pyramid has some optional C extensions for performance. With + ``easy_install``, Windows users can get these extensions without + needing a C compiler. + +.. seealso:: See Also: Python 3's :mod:`venv module <python3:venv>`, + the ``setuptools`` `installation + instructions <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_, + `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_, + and Pyramid's :ref:`Before You Install <installing_chapter>`. diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst index 74409711f..7d11cd3c3 100644 --- a/docs/quick_tutorial/request_response.rst +++ b/docs/quick_tutorial/request_response.rst @@ -75,7 +75,7 @@ Analysis In this view class we have two routes and two views, with the first leading to the second by an HTTP redirect. Pyramid can -:ref:`generate redirects <pyramid:http_redirect>` by returning a +:ref:`generate redirects <http_redirect>` by returning a special object from a view or raising a special exception. In this Pyramid view, we get the URL being visited from ``request.url``. @@ -97,5 +97,5 @@ Extra Credit #. Could we also ``raise HTTPFound(location='/plain')`` instead of returning it? If so, what's the difference? -.. seealso:: :ref:`pyramid:webob_chapter`, - :ref:`generate redirects <pyramid:http_redirect>` +.. seealso:: :ref:`webob_chapter`, + :ref:`generate redirects <http_redirect>` diff --git a/docs/quick_tutorial/rest_ajax.rst b/docs/quick_tutorial/rest_ajax.rst deleted file mode 100644 index 69a940818..000000000 --- a/docs/quick_tutorial/rest_ajax.rst +++ /dev/null @@ -1,62 +0,0 @@ -================== -29: REST with Ajax -================== - -Use Ajax operations to talk to a REST interface. - -Objectives -========== - -- Populate a list with JSON data - -- Update contents with client-side forms that post to REST operations - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r rest_ajax_layout rest_ajax; cd rest_ajax - (env27)$ python setup.py develop - -#. Let's first add a Javascript file that implements our browser-side - logic and talks to the REST service: - -#. Introduce ``pyramid_jinja2`` dependency in - ``rest_ajax/tutorial/static/site.js``: - - .. literalinclude:: rest_ajax/tutorial/static/site.js - :language: js - :linenos: - -#. Add a ``<script>`` reference to this at the bottom of - ``rest_ajax/tutorial/templates/layout.jinja2`` - - .. literalinclude:: rest_ajax/tutorial/templates/layout.jinja2 - :language: html - :linenos: - -#. Update ``rest_ajax/tutorial/templates/folder.jinja2`` to include a - modal dialog: - - .. literalinclude:: rest_ajax/tutorial/templates/folder.jinja2 - :language: html - :linenos: - -#. Our views in ``rest_ajax/tutorial/views.py`` need to handle our - REST operations: - - .. literalinclude:: rest_ajax/tutorial/views.py - :linenos: - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser and - add (+ button), edit (click link), and delete (click trash icon) - items in the root folder.
\ No newline at end of file diff --git a/docs/quick_tutorial/rest_ajax_layout.rst b/docs/quick_tutorial/rest_ajax_layout.rst deleted file mode 100644 index 921921b15..000000000 --- a/docs/quick_tutorial/rest_ajax_layout.rst +++ /dev/null @@ -1,50 +0,0 @@ -========================= -28: REST with Ajax Layout -========================= - -Produce a grid-like UI to prepare for async REST operations. - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r rest_bootstrap rest_ajax_layout; cd rest_ajax_layout - (env27)$ python setup.py develop - -#. Get a new menu item for ``Folders`` in - ``rest_ajax_layout/tutorial/templates/layout.jinja2``: - - .. literalinclude:: rest_ajax_layout/tutorial/templates/layout.jinja2 - :language: html - :linenos: - -#. In ``rest_ajax_layout/tutorial/views.py``, add a JSON view and remove - unused previous views: - - .. literalinclude:: rest_ajax_layout/tutorial/views.py - :linenos: - -#. Create a template at - ``rest_ajax_layout/tutorial/templates/folder.jinja2``: - - .. literalinclude:: rest_ajax_layout/tutorial/templates/folder.jinja2 - :language: html - :linenos: - -#. Do some cleanup: - - .. code-block:: bash - - (env27)$ rm tutorial/templates/*.pt - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - diff --git a/docs/quick_tutorial/rest_bootstrap.rst b/docs/quick_tutorial/rest_bootstrap.rst deleted file mode 100644 index 051d931d2..000000000 --- a/docs/quick_tutorial/rest_bootstrap.rst +++ /dev/null @@ -1,88 +0,0 @@ -========================================= -27: Beginning REST with Twitter Bootstrap -========================================= - -Begin making a REST application by adding Twitter Bootstrap, jQuery, -and a common layout. - -Objectives -========== - -- Switch to Jinja2 - -- Make a "layout" that is shared between templates - -- Introduce jQuery and Twitter Bootstrap as well as local static - resources - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r traversal_zodb rest_bootstrap; cd rest_bootstrap - (env27)$ mkdir tutorial/static; mkdir tutorial/templates - -#. Introduce ``pyramid_jinja2`` dependency in - ``rest_bootstrap/setup.py``: - - .. literalinclude:: rest_bootstrap/setup.py - :linenos: - -#. We can now install our project: - - .. code-block:: bash - - (env27)$ python setup.py develop - -#. Modify our ``rest_bootstrap/development.ini`` to include - ``pyramid_jinja2`` configuration: - - .. literalinclude:: rest_bootstrap/development.ini - :language: ini - :linenos: - -#. Our startup code in ``rest_bootstrap/tutorial/__init__.py`` gets - a static view: - - .. literalinclude:: rest_bootstrap/tutorial/__init__.py - :linenos: - -#. Our home view in ``rest_bootstrap/tutorial/views.py`` references - a Jinja2 template: - - .. literalinclude:: rest_bootstrap/tutorial/views.py - :linenos: - -#. Our site template in - ``rest_bootstrap/tutorial/templates/site.jinja2`` - references a master layout: - - .. literalinclude:: rest_bootstrap/tutorial/templates/site.jinja2 - :language: html - :linenos: - -#. Add the master layout template in - ``rest_bootstrap/tutorial/templates/layout.jinja2``: - - .. literalinclude:: rest_bootstrap/tutorial/templates/layout.jinja2 - :language: html - :linenos: - -#. A small amount of stying in - ``rest_bootstrap/tutorial/static/site.css``: - - .. literalinclude:: rest_bootstrap/tutorial/static/site.css - :language: css - :linenos: - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst index 39597d996..33b1edb28 100644 --- a/docs/quick_tutorial/routing.rst +++ b/docs/quick_tutorial/routing.rst @@ -12,7 +12,7 @@ Writing web applications usually means sophisticated URL design. We just saw some Pyramid machinery for requests and views. Let's look at features that help in routing. -Previously we saw the basics of routing URLs to views in Pyramid: +Previously we saw the basics of routing URLs to views in - Your project's "setup" code registers a route name to be used when matching part of the URL @@ -93,7 +93,7 @@ In ``__init__.py`` we see an important change in our route declaration: config.add_route('hello', '/howdy/{first}/{last}') -With this we tell the :term:`pyramid:configurator` that our URL has +With this we tell the :term:`configurator` that our URL has a "replacement pattern". With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to ``first`` and ``smith`` to ``last``. We can then use this data in our view: diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst index 5de5e2958..b50d6d318 100644 --- a/docs/quick_tutorial/sessions.rst +++ b/docs/quick_tutorial/sessions.rst @@ -14,7 +14,7 @@ cart. This is called a :term:`session`. Pyramid has basic built-in support for sessions, with add-ons such as *dogpile.cache* (or your own custom sessioning engine) that provide richer session support. Let's take a look at the -:ref:`built-in sessioning support <pyramid:sessions_chapter>`. +:ref:`built-in sessioning support <sessions_chapter>`. Objectives ========== @@ -93,6 +93,6 @@ Flash messages are a technique where messages can be stored between requests, using sessions, then removed when they finally get displayed. .. seealso:: - :ref:`pyramid:sessions_chapter`, - :ref:`pyramid:flash_messages`, and - :ref:`pyramid:session_module`. + :ref:`sessions_chapter`, + :ref:`flash_messages`, and + :ref:`session_module`. diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst index 03c7d397d..3aaf6168c 100644 --- a/docs/quick_tutorial/static_assets.rst +++ b/docs/quick_tutorial/static_assets.rst @@ -84,6 +84,6 @@ Extra Credit #. There is also a ``request.static_path`` API. How does this differ from ``request.static_url``? -.. seealso:: :ref:`pyramid:assets_chapter`, - :ref:`pyramid:preventing_http_caching`, and - :ref:`pyramid:influencing_http_caching` +.. seealso:: :ref:`assets_chapter`, + :ref:`preventing_http_caching`, and + :ref:`influencing_http_caching` diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index f9393ecf6..ee4542485 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -87,7 +87,7 @@ Analysis Ahh, that looks better. We have a view that is focused on Python code. Our ``@view_config`` decorator specifies a -:term:`pyramid:renderer` that points +:term:`renderer` that points our template file. Our view then simply returns data which is then supplied to our template. Note that we used the same template for both views. @@ -95,6 +95,6 @@ views. Note the effect on testing. We can focus on having a data-oriented contract with our view code. -.. seealso:: :ref:`pyramid:templates_chapter`, - :ref:`pyramid:debugging_templates`, and - :ref:`pyramid:mako_templates` +.. seealso:: :ref:`templates_chapter`, + :ref:`debugging_templates`, and + :ref:`mako_templates` diff --git a/docs/quick_tutorial/traversal_addcontent.rst b/docs/quick_tutorial/traversal_addcontent.rst deleted file mode 100644 index 499e08fbb..000000000 --- a/docs/quick_tutorial/traversal_addcontent.rst +++ /dev/null @@ -1,105 +0,0 @@ -=================================== -25: Adding Resources To Hierarchies -=================================== - -Multiple views per type allowing addition of content anywhere in a -resource tree. - -Background -========== - -We now have multiple kinds-of-things, but only one view per resource -type. We need the ability to add things to containers, -then view/edit resources. - -This introduces the concept of named views. A name is a part of the URL -that appears after the resource identifier. For example:: - - @view_config(context=Folder, name='add_document') - -...means that this URL:: - - http://localhost:6543/some_folder/add_document - -...will match the view being configured. It's as if you have an -object-oriented web, with operations on resources represented by a URL. - -When you omit the ``name=`` (as we did in the previous examples, -you are establishing a "default view" for the context. That is, -a view to be used when no view name is found during traversal. - -Goals -===== - -- Adding and editing content in a resource tree - -- Simple form which POSTs data - -- A view which takes the POST data, creates a resource, and redirects - to the newly-added resource - -- Named views - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r traversal_typeviews traversal_addcontent; cd traversal_addcontent - (env27)$ python setup.py develop - - -#. Our views in ``traversal_addcontent/tutorial/views.py`` need - type-specific registrations: - - .. literalinclude:: traversal_addcontent/tutorial/views.py - :linenos: - -#. One small change in - ``traversal_addcontent/tutorial/templates/document.pt``: - - .. literalinclude:: traversal_addcontent/tutorial/templates/document.pt - :language: html - :linenos: - -#. Need forms added to - ``traversal_addcontent/tutorial/templates/folder.pt``: - - .. literalinclude:: traversal_addcontent/tutorial/templates/folder.pt - :language: html - :linenos: - -#. Forms also needed for - ``traversal_addcontent/tutorial/templates/site.pt``: - - .. literalinclude:: traversal_addcontent/tutorial/templates/site.pt - :language: html - :linenos: - -#. ``$ nosetests`` should report running 4 tests. - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - -Analysis -======== - -Our views now represent a richer system, where form data can be -processed to modify content in the tree. We do this by attaching named -views to resource types, giving them a natural system for -object-oriented operations. - -To enforce uniqueness, we randomly choose a satisfactorily large number. - -Extra Credit -============ - -#. Can ``document_view`` simply return nothing instead of an empty - dictionary? diff --git a/docs/quick_tutorial/traversal_hierarchy.rst b/docs/quick_tutorial/traversal_hierarchy.rst deleted file mode 100644 index 9418b63eb..000000000 --- a/docs/quick_tutorial/traversal_hierarchy.rst +++ /dev/null @@ -1,106 +0,0 @@ -========================= -23: Traversal Hierarchies -========================= - -Objects with subobjects and views, all via URLs. - -Background -========== - -In :doc:`../traversal_siteroot` we took the simplest possible step: a -root object with little need for the stitching-together of a tree known -as traversal. - -In this step we remain simple, but make a basic hierarchy:: - - / - doc1 - doc2 - folder1/ - doc1 - - -Objectives -========== - -- Multi-level nested hierarchy of Python objects - -- Show how ``__name__`` and ``__parent__`` glue the hierarchy together - -- Objects which last between requests - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r traversal_siteroot traversal_hierarchy; cd traversal_hierarchy - (env27)$ python setup.py develop - -#. Provide a richer set of objects in - ``traversal_hierarchy/tutorial/resources.py``: - - .. literalinclude:: traversal_hierarchy/tutorial/resources.py - :linenos: - -#. Have ``traversal_hierarchy/tutorial/views.py`` show information about - the resource tree: - - .. literalinclude:: traversal_hierarchy/tutorial/views.py - :linenos: - -#. Get ``traversal_hierarchy/tutorial/home.pt`` to display this richer - information: - - .. literalinclude:: traversal_hierarchy/tutorial/home.pt - :language: html - :linenos: - -#. Simplified tests in ``traversal_hierarchy/tutorial/tests.py``: - - .. literalinclude:: traversal_hierarchy/tutorial/tests.py - :linenos: - -#. Now run the tests: - - .. code-block:: bash - - - (env27)$ nosetests tutorial - . - ---------------------------------------------------------------------- - Ran 4 tests in 0.141s - - OK - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - -Analysis -======== - -In this example we have to manage our tree by assigning ``__name__`` as -an identifier on each child and ``__parent__`` as a reference to the -parent. - -The template used now shows different information based on the object -URL which you traversed to. - -Extra Credit -============ - -#. In ``resources.py``, we moved the instantiation of ``root`` out to - global scope. Why? - -#. If you go to a resource that doesn't exist, will Pyramid handle it - gracefully? - -#. What happens if you use a ``__name__`` that already exists in the - container? diff --git a/docs/quick_tutorial/traversal_siteroot.rst b/docs/quick_tutorial/traversal_siteroot.rst deleted file mode 100644 index b582d0451..000000000 --- a/docs/quick_tutorial/traversal_siteroot.rst +++ /dev/null @@ -1,153 +0,0 @@ -=================================== -22: Basic Traversal With Site Roots -=================================== - -Model websites as a hierarchy of objects with operations. - -Background -========== - -Web applications have URLs which locate data and make operations on that -data. Pyramid supports two ways of mapping URLs into Python operations: - -- The more-traditional approach of *URL dispatch* aka *routes* - -- The more object-oriented approach of - :ref:`traversal <pyramid:traversal_chapter>` popularized by Zope - -In this section we will introduce traversal bit-by-bit. Along the way, -we will try to show how easy and Pythonic it is to think in terms of -traversal. - -Remember...traversal is easy, powerful, and useful. - -With traversal, you think of your website as a tree of Python objects, -just like a dictionary of dictionaries. For example:: - - http://example.com/company1/aFolder/subFolder/search?term=hello - -...is nothing more than:: - - >>> root['aFolder']['subFolder'].search(x=1) - -To remove some mystery about traversal, we start with the smallest -possible step: an object at the top of our URL space. This object acts -as the "root" and has a view which shows some data on that object. - -Objectives -========== - -- Make a factory for the root object - -- Pass it to the configurator - -- Have a view which displays an attribute on that object - -Steps -===== - -#. We are going to use the view classes step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r view_classes traversal_siteroot; cd traversal_siteroot - (env27)$ python setup.py develop - -#. In ``traversal_siteroot/tutorial/__init__.py`` make a root factory - and remove the ``add_route`` statements from the - :term:`configurator`: - - .. literalinclude:: traversal_siteroot/tutorial/__init__.py - :linenos: - -#. We have ``traversal_siteroot/tutorial/resources.py`` with a class for - the root of our site and a factory that returns it: - - .. literalinclude:: traversal_siteroot/tutorial/resources.py - :linenos: - -#. Our views in ``traversal_siteroot/tutorial/views.py`` are now - quite different...no ``route_name``: - - .. literalinclude:: traversal_siteroot/tutorial/views.py - :linenos: - -#. A template in ``traversal_siteroot/tutorial/home.pt``: - - .. literalinclude:: traversal_siteroot/tutorial/home.pt - :language: html - :linenos: - - -#. Simplified tests in ``traversal_siteroot/tutorial/tests.py``: - - .. literalinclude:: traversal_siteroot/tutorial/tests.py - :linenos: - -#. Now run the tests: - - .. code-block:: bash - - - (env27)$ nosetests tutorial - . - ---------------------------------------------------------------------- - Ran 4 tests in 0.141s - - OK - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - -Analysis -======== - -Our ``__init__.py`` has a small but important change: we create the -configuration with a *root factory*. Our root factory is a simple -function that performs some work and returns the root object in the -:ref:`resource tree <pyramid:the_resource_tree>`. - -In the resource tree, Pyramid can match URLs to objects and subobjects, -finishing in a view as the operation to perform. Traversing through -containers is done using Python's normal ``__getitem__`` dictionary -protocol. - -Pyramid provides services beyond simple Python dictionaries. These -:ref:`location <pyramid:location_aware>` -services need a little bit more protocol than just ``__getitem__``. -Namely, objects need to provide an attribute/callable for -``__name__`` and ``__parent__``. - -In this step, our tree has one object: the root. It is an instance of -``SiteFolder``. Since it is the root, it doesn't need a ``__name__`` -(aka ``id``) nor a ``__parent__`` (reference to the container an object -is in.) - -Our ``home`` view is passed, by Pyramid, the instance of this folder as -``context``. The view can then grab attributes and other data from the -object that is the focus of the URL. - -Now, on to the most visible part: no more routes! Previously we wrote -URL "replacement patterns" which mapped to a route. The route extracted -data from the patterns and made this data available to views that were -mapped to that route. - -Instead, segments in URLs become object identifiers in Python. - -Extra Credit -============ - -#. Is the root factory called once on startup, or on every request? Do - a small change that answers this. What is the impact of the answer - on this? - -.. seealso:: - :ref:`pyramid:traversal_chapter`, - :ref:`pyramid:location_aware`, - :ref:`pyramid:the_resource_tree`, - :ref:`much_ado_about_traversal_chapter` diff --git a/docs/quick_tutorial/traversal_typeviews.rst b/docs/quick_tutorial/traversal_typeviews.rst deleted file mode 100644 index 8a32a2483..000000000 --- a/docs/quick_tutorial/traversal_typeviews.rst +++ /dev/null @@ -1,112 +0,0 @@ -======================= -24: Type-Specific Views -======================= - -Type-specific views by registering a view against a class. - -Background -========== - -In :doc:`../traversal_hierarchy` we had 3 "content types" (SiteFolder, -Folder, and Document.) All, however, used the same view and template. - -Pyramid traversal though lets you bind a view to a particular content -type. This ability to make your URLs "object oriented" is one of the -distinguishing features of traversal and makes crafting a URL space -more natural. Once Pyramid finds the :term:`context` object in the URL -path, developers have a lot of flexibility in view predicates. - -Objectives -========== - -- ``@view_config`` which uses the ``context`` attribute to associate a - particular view with ``context`` instances of a particular class - -- Views and templates which are unique to a particular class (aka type) - -- Patterns in test writing to handle multiple kinds of contexts - -Steps -===== - -#. We are going to use the previous step as our starting point and add a - ``tutorial/templates`` subdirectory: - - .. code-block:: bash - - (env27)$ cd ..; cp -r traversal_hierarchy traversal_typeviews; cd traversal_typeviews - (env27)$ python setup.py develop - (env27)$ mkdir traversal_typeviews/tutorial/templates - -#. Our views in ``traversal_typeviews/tutorial/views.py`` need - type-specific registrations: - - .. literalinclude:: traversal_typeviews/tutorial/views.py - :linenos: - -#. Copy the following into - ``traversal_typeviews/tutorial/templates/document.pt``: - - .. literalinclude:: traversal_typeviews/tutorial/templates/document.pt - :language: html - :linenos: - -#. Copy the following into - ``traversal_typeviews/tutorial/templates/folder.pt``: - - .. literalinclude:: traversal_typeviews/tutorial/templates/folder.pt - :language: html - :linenos: - -#. Copy the following into - ``traversal_typeviews/tutorial/templates/site.pt``: - - .. literalinclude:: traversal_typeviews/tutorial/templates/site.pt - :language: html - :linenos: - -#. More tests needed in ``traversal_typeviews/tutorial/tests.py``: - - .. literalinclude:: traversal_typeviews/tutorial/tests.py - :linenos: - -#. ``$ nosetests`` should report running 4 tests. - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - -Analysis -======== - -We made a ``templates`` subdirectory, just for the purposes of -organization and to match a common project layout style. - -For the most significant change, our ``@view_config`` now matches on a -``context`` view predicate. We can say "use this view for when looking -at *this* kind of thing." The concept of a route as an intermediary -step between URLs and views has been eliminated. - -Extra Credit -============ - -#. Should you calculate the list of children on the Python side, - or access it on the template side by operating on the context? - -#. What if you need different traversal policies? - -#. In Zope, *interfaces* were used to register a view. How do you do - register a Pyramid view against instances that support a particular - interface? When should you? - -#. Let's say you need a more-specific view to be used on a particular - instance of a class, letting a more-general view cover all other - instances. What are some of your options? - -.. seealso:: - :ref:`Traversal Details <pyramid:traversal_chapter>` - :ref:`Hybrid Traversal and URL Dispatch <pyramid:hybrid_chapter>`
\ No newline at end of file diff --git a/docs/quick_tutorial/traversal_zodb.rst b/docs/quick_tutorial/traversal_zodb.rst deleted file mode 100644 index a7f464609..000000000 --- a/docs/quick_tutorial/traversal_zodb.rst +++ /dev/null @@ -1,121 +0,0 @@ -================================== -26: Storing Resources In Databases -================================== - -Store and retrieve resource tree containers and items in a database. - -Background -========== - -We now have a resource tree that can go infinitely deep, -adding items and subcontainers along the way. We obviously need a -database, one that can support hierarchies. ZODB is a transaction-based -Python database that supports transparent persistence. We will modify -our application to work with the ZODB. - -Along the way we will add the use of ``pyramid_tm``, -a system for adding transaction awareness to our code. With this we -don't need to manually manage our transaction begin/commit cycles in -our application code. Instead, transactions are setup transparently on -request/response boundaries, outside our application code. - -Objectives -========== - -- Create a CRUD app that adds records to persistent storage. - -- Setup ``pyramid_tm`` and ``pyramid_zodbconn``. - -- Make our "content" classes inherit from ``Persistent``. - -- Set up a database connection string in our application. - -- Set up a root factory that serves the root from ZODB rather than from - memory. - -Steps -===== - -#. We are going to use the previous step as our starting point: - - .. code-block:: bash - - (env27)$ cd ..; cp -r traversal_addcontent traversal_zodb; cd traversal_zodb - -#. Introduce some new dependencies in ``traversal_zodb/setup.py``: - - .. literalinclude:: traversal_zodb/setup.py - :linenos: - -#. We can now install our project: - - .. code-block:: bash - - (env27)$ python setup.py develop - -#. Modify our ``traversal_zodb/development.ini`` to include some - configuration and give database connection parameters: - - .. literalinclude:: traversal_zodb/development.ini - :language: ini - :linenos: - -#. Our startup code in ``traversal_zodb/tutorial/__init__.py`` gets - some bootstrapping changes: - - .. literalinclude:: traversal_zodb/tutorial/__init__.py - :linenos: - -#. Our views in ``traversal_zodb/tutorial/views.py`` change to create - persistent objects: - - .. literalinclude:: traversal_zodb/tutorial/views.py - :linenos: - -#. As do our resources in ``traversal_zodb/tutorial/resources.py``: - - .. literalinclude:: traversal_zodb/tutorial/resources.py - :linenos: - -#. Run your Pyramid application with: - - .. code-block:: bash - - (env27)$ pserve development.ini --reload - -#. Open ``http://localhost:6543/`` in your browser. - -Analysis -======== - -We install ``pyramid_zodbconn`` to handle database connections to ZODB. This -pulls the ZODB3 package as well. - -To enable ``pyramid_zodbconn``: - -- We activate the package configuration using ``pyramid.includes``. - -- We define a ``zodbconn.uri`` setting with the path to the Data.fs file. - -In the root factory, instead of using our old root object, we now get a -connection to the ZODB and create the object using that. - -Our resources need a couple of small changes. Folders now inherit from -persistent.PersistentMapping and document from persistent.Persistent. Note -that Folder now needs to call super() on the __init__ method, or the -mapping will not initialize properly. - -On the bootstrap, note the use of transaction.commit() to commit the -change. This is because, on first startup, we want a root resource in -place before continuing. - -Extra Credit -============ - -#. Create a view that deletes a document. - -#. Remove the configuration line that includes ``pyramid_tm``. What - happens when you restart the application? Are your changes - persisted across restarts? - -#. What happens if you delete the files named ``Data.fs*``? diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst index cc9dfcc8a..566e09252 100644 --- a/docs/quick_tutorial/unit_testing.rst +++ b/docs/quick_tutorial/unit_testing.rst @@ -114,4 +114,4 @@ Extra Credit #. Why do we import the ``hello_world`` view function *inside* the ``test_hello_world`` method instead of at the top of the module? -.. seealso:: See Also: :ref:`pyramid:testing_chapter` +.. seealso:: See Also: :ref:`testing_chapter` diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst index 0c8976b7f..e06e7f6c0 100644 --- a/docs/quick_tutorial/view_classes.rst +++ b/docs/quick_tutorial/view_classes.rst @@ -12,7 +12,7 @@ So far our views have been simple, free-standing functions. Many times your views are related: different ways to look at or work on the same data or a REST API that handles multiple operations. Grouping these together as a -:ref:`view class <pyramid:class_as_view>` makes sense: +:ref:`view class <class_as_view>` makes sense: - Group views @@ -93,4 +93,4 @@ class. But you can also see the pattern in the tests of instantiating the view class with the dummy request first, then calling the view method being tested. -.. seealso:: :ref:`pyramid:class_as_view` +.. seealso:: :ref:`class_as_view` diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst index ee51cdc0d..f36387027 100644 --- a/docs/quick_tutorial/views.rst +++ b/docs/quick_tutorial/views.rst @@ -99,9 +99,9 @@ and the name of the view, can all be different. More on routes later. Earlier we saw ``config.add_view`` as one way to configure a view. This section introduces ``@view_config``. Pyramid's configuration supports -:term:`pyramid:imperative configuration`, such as the +:term:`imperative configuration`, such as the ``config.add_view`` in the previous example. You can also use -:term:`pyramid:declarative configuration`, in which a Python +:term:`declarative configuration`, in which a Python :term:`python:decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. @@ -114,7 +114,7 @@ Extra Credit #. Why might ``assertIn`` be a better choice in testing the text in responses than ``assertEqual``? -.. seealso:: :ref:`pyramid:views_chapter`, - :ref:`pyramid:view_config_chapter`, and - :ref:`pyramid:debugging_view_configuration` +.. seealso:: :ref:`views_chapter`, + :ref:`view_config_chapter`, and + :ref:`debugging_view_configuration` |