From 2a5ae0346df95e5b4f9a7d8531574dce70abe31f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 22 Dec 2010 22:34:20 -0500 Subject: - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead, it is based on scanning. - Changed the "ZODB + Traversal Wiki Tutorial" based on changes to ``pyramid_zodb`` Paster template. --- docs/tutorials/wiki/basiclayout.rst | 180 ++++++++++++++++++++++++------------ 1 file changed, 123 insertions(+), 57 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index c7c722f70..8e6e89e57 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -21,9 +21,9 @@ well as to contain application configuration code. When you run the application using the ``paster`` command using the ``development.ini`` generated config file, the application configuration -points at an Setuptools *entry point* described as ``egg:tutorial#app``. In -our application, because the application's ``setup.py`` file says so, this -entry point happens to be the ``app`` function within the file named +points at an Setuptools *entry point* described as ``egg:tutorial``. In our +application, because the application's ``setup.py`` file says so, this entry +point happens to be the ``main`` function within the file named ``__init__.py``: .. literalinclude:: src/basiclayout/tutorial/__init__.py @@ -48,55 +48,31 @@ entry point happens to be the ``app`` function within the file named factory` and the settings keywords parsed by PasteDeploy. The root factory is named ``get_root``. -#. *Line 16*. Load the - ``configure.zcml`` file from our package using the - :meth:`pyramid.config.Configurator.load_zcml` method. - -#. *Line 17*. Use the +#. *Line 16*. Register a 'static view' which answers requests which start + with with URL path ``/static`` using the + :meth:`pyramid.config.Configurator.add_static_view method`. This + statement registers a view that will serve up static assets, such as CSS + and image files, for us, in this case, at + ``http://localhost:6543/static/`` and below. The first argument is the + "name" ``static``, which indicates that the URL path prefix of the view + will be ``/static``. the The second argument of this tag is the "path", + which is an :term:`asset specification`, so it finds the resources it + should serve within the ``static`` directory inside the ``tutorial`` + package. + +#. *Line 17*. Perform a :term:`scan`. A scan will find :term:`configuration + decoration`, such as view configuration decorators + (e.g. ``@view_config``) in the source code of the ``tutorial`` package and + will take actions based on these decorators. The argument to + :meth:`~pyramid.config.Configurator.scan` is the package name to scan, + which is ``tutorial``. + +#. *Line 18*. Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. -Configuration With ``configure.zcml`` --------------------------------------- - -The ``pyramid_zodb`` template uses :term:`ZCML` to perform system -configuration. The ZCML file generated by the template looks like the -following: - - .. literalinclude:: src/basiclayout/tutorial/configure.zcml - :linenos: - :language: xml - -#. *Line 1*. The root ```` element. - -#. *Line 4*. Boilerplate, the comment explains. - -#. *Lines 6-10*. Register a ```` that names a ``context`` type - that is a class. ``.views.my_view`` is a *function* we write - (generated by the ``pyramid_zodb`` template) that is given a - ``context`` object and a ``request`` and which returns a - dictionary. The ``renderer`` tag indicates that the - ``templates/mytemplate.pt`` template should be used to turn the - dictionary returned by the view into a response. - ``templates/mytemplate.pt`` is a *relative* path: it names the - ``mytemplate.pt`` file which lives in the ``templates`` - subdirectory of the directory in which this ``configure.zcml`` - lives in. In this case, it means it lives in the ``tutorial`` - package's ``templates`` directory as ``mytemplate.pt`` - - Since this ```` doesn't have a ``name`` attribute, it is the - "default" view for that class. - -#. *Lines 12-15*. Register a ``static`` view which answers requests - which start with ``/static``. This is a view that will serve up - static resources for us, in this case, at - ``http://localhost:6543/static/`` and below. The ``path`` element - of this tag is a relative directory name, so it finds the resources - it should serve within the ``static`` directory inside - the ``tutorial`` package. - -Content Models with ``models.py`` ---------------------------------- +Resources and Models with ``models.py`` +--------------------------------------- :app:`Pyramid` uses the word :term:`resource` to describe objects arranged hierarchically in a :term:`resource tree`. This tree is consulted by @@ -114,14 +90,13 @@ Here is the source for ``models.py``: :linenos: :language: py -#. *Lines 3-4*. The ``MyModel`` class we referred to in the ZCML file - named ``configure.zcml`` is implemented here. Instances of this - class will be capable of being persisted in :term:`ZODB` because - the class inherits from the - :class:`persistent.mapping.PersistentMapping` class. The - ``__parent__`` and ``__name__`` are important parts of the - :term:`traversal` protocol. By default, have these as ``None`` - indicating that this is the :term:`root` object. +#. *Lines 3-4*. The ``MyModel`` :term:`resource` class is implemented here. + Instances of this class will be capable of being persisted in :term:`ZODB` + because the class inherits from the + :class:`persistent.mapping.PersistentMapping` class. The ``__parent__`` + and ``__name__`` are important parts of the :term:`traversal` protocol. + By default, have these as ``None`` indicating that this is the + :term:`root` object. #. *Lines 6-12*. ``appmaker`` is used to return the *application root* object. It is called on *every request* to the @@ -134,3 +109,94 @@ Here is the source for ``models.py``: commit the transaction. We then return the application root object. +Views With ``views.py`` +----------------------- + +Our paster template generated a default ``views.py`` on our behalf. It +contains a single view, which is used to render the page shown when you visit +the URL ``http://localhost:6543/``. + +Here is the source for ``views.py``: + + .. literalinclude:: src/basiclayout/tutorial/views.py + :linenos: + :language: py + +Let's try to understand the components in this module: + +#. *Lines 1-2*. Perform some dependency imports. + +#. *Line 4*. Use the :func:`pyramid.view.view_config` :term:`configuration + decoration` to perform a :term:`view configuration` registration. This + view configuration registration will be activated when the application is + started. It will be activated by virtue of it being found as the result + of a :term:`scan` (when Line 17 of ``__init__.py`` is run). + + The ``@view_config`` decorator accepts a number of keyword arguments. We + use two keyword arguments here: ``context`` and ``renderer``. + + The ``context`` argument signifies that the decorated view callable should + only be run when :term:`traversal` finds the ``tutorial.models.MyModel`` + :term:`resource` to be the :term:`context` of a request. In English, this + means that when the URL ``/`` is visited, because ``MyModel`` is the root + model, this view callable will be invoked. + + The ``renderer`` argument names an :term:`asset specification` of + ``tutorial:templates/mytemplate.pt``. This asset specification points at + a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file + within the ``templates`` directory of the ``tutorial`` package. And + indeed if you look in the ``templates`` directory of this package, you'll + see a ``mytemplate.pt`` template file, which renders the default home page + of the generated project. + + Since this call to ``@view_config`` doesn't pass a ``name`` argument, the + ``my_view`` function which it decorates represents the "default" view + callable used when the context is of the type ``MyModel``. + +#. *Lines 5-6*. We define a :term:`view callable` named ``my_view``, which + we decorated in the step above. This view callable is a *function* we + write generated by the ``pyramid_zodb`` template that is given a + ``request`` and which returns a dictionary. The ``mytemplate.pt`` + :term:`renderer` named by the asset specification in the step above will + convert this dictionary to a :term:`response` on our behalf. + + The function returns the dictionary ``{'project':'tutorial'}``. This + dictionary is used by the template named by the ``mytemplate.pt`` asset + specification to fill in certain values on the page. + +The WSGI Pipeline in ``development.ini`` +---------------------------------------- + +The ``development.ini`` (in the tutorial :term:`project` directory, as +opposed to the tutorial :term:`package` directory) looks like this: + +.. literalinclude:: src/views/development.ini + :linenos: + :language: ini + + +Note the existence of a ``[pipeline:main]`` section which specifies our WSGI +pipeline. This "pipeline" will be served up as our WSGI application. As far +as the WSGI server is concerned the pipeline *is* our application. Simpler +configurations don't use a pipeline: instead they expose a single WSGI +application as "main". Our setup is more complicated, so we use a pipeline +composed of :term:`middleware`. + +The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline. +This is middleware which displays debuggable errors in the browser while +you're developing (not recommended for deployment). + +The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the +pipeline. This is a piece of middleware which closes the ZODB connection +opened by the ``PersistentApplicationFinder`` at the end of the request. + +The ``egg:repoze.tm#tm`` middleware is the last piece of middleware in the +pipeline. This commits a transaction near the end of the request unless +there's an exception raised. + +The final line in the ``[pipeline:main]`` section is ``tutorial``, which +refers to the ``[app:tutorial]`` section above it. The ``[app:tutorial]`` +section is the section which actually defines our application settings. The +values within this section are passed as ``**settings`` to the ``main`` +function we defined in ``__init__.py`` when the server is started via +``paster serve``. -- cgit v1.2.3 From b743bb4da42198f223ec756936dc0c581b08b534 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 23 Dec 2010 20:01:42 -0500 Subject: tutorial accuracy and wording improvements --- docs/tutorials/wiki/basiclayout.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 8e6e89e57..f6e1f800a 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -2,10 +2,9 @@ Basic Layout ============ -The starter files generated by the ``pyramid_zodb`` template are basic, -but they provide a good orientation for the high-level patterns common -to most :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` -based) projects. +The starter files generated by the ``pyramid_zodb`` template are basic, but +they provide a good orientation for the high-level patterns common to most +:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects. The source code for this tutorial stage can be browsed via `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/ @@ -78,11 +77,10 @@ Resources and Models with ``models.py`` hierarchically in a :term:`resource tree`. This tree is consulted by :term:`traversal` to map URLs to code. In this application, the resource tree represents the site structure, but it *also* represents the -:term:`domain model` of the application, because eeach resource is a node +:term:`domain model` of the application, because each resource is a node stored persistently in a :term:`ZODB` database. The ``models.py`` file is where the ``pyramid_zodb`` Paster template put the classes that implement our -resource objects, each of which happens also to be a domain model -object. +resource objects, each of which happens also to be a domain model object. Here is the source for ``models.py``: -- cgit v1.2.3