- The ZODB Wiki tutorial was updated to take into account changes to the ...

Chris McDonough

2010-11-04 b3b7132a8c2964bf3638f0be23dcf87dca737877

- The ZODB Wiki tutorial was updated to take into account changes to the
  ``pyramid_zodb`` paster template.

 CHANGES.txt

@@ -96,6 +96,9 @@
  moving declarative configuration (ZCML) explanations to a separate
  narrative chapter ``declarative.rst``.

- The ZODB Wiki tutorial was updated to take into account changes to the
  ``pyramid_zodb`` paster template.

Backwards Incompatibilities (with BFG 1.3.X)
--------------------------------------------


 docs/tutorials/wiki/authorization.rst

@@ -51,7 +51,7 @@
~~~~~~~~~~~~~~~~~~~~~~

Add a ``security.py`` module within your package (in the same
directory as ``run.py``, ``views.py``, etc) with the following
directory as ``__init__.py``, ``views.py``, etc) with the following
content:

.. literalinclude:: src/authorization/tutorial/security.py

 docs/tutorials/wiki/basiclayout.rst

@@ -11,12 +11,53 @@
`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/
<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/>`_.

``__init__.py``
---------------
App Startup with ``__init__.py``
--------------------------------

A directory on disk can be turned into a Python :term:`package` by
containing an ``__init__.py`` file.  Even if empty, this marks a
directory as a Python package.
A directory on disk can be turned into a Python :term:`package` by containing
an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
package.  Our application uses ``__init__.py`` as both a package marker, as
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
``__init__.py``:

   .. literalinclude:: src/basiclayout/tutorial/__init__.py
      :linenos:
      :language: py

#. *Lines 1-2*.  Perform some dependency imports.

#. *Line 12*. Get the ZODB configuration from the ``development.ini``
   file's ``[app:main]`` section represented by the ``settings``
   dictionary passed to our ``app`` function.  This will be a URI
   (something like ``file:///path/to/Data.fs``).

#. *Line 15*. We create a "finder" object using the
   ``PersistentApplicationFinder`` helper class, passing it the ZODB
   URI and the "appmaker" we've imported from ``models.py``.

#. *Lines 16 - 17*.  We create a :term:`root factory` which uses the
   finder to return a ZODB root object.

#. *Line 18*.  We construct a :term:`Configurator` with a :term:`root
   factory` and the settings keywords parsed by PasteDeploy.  The root
   factory is named ``get_root``.

#. *Lines 19-21*.  Begin configuration using the ``begin`` method of
   the :meth:`pyramid.configuration.Configurator` class, load the
   ``configure.zcml`` file from our package using the
   :meth:`pyramid.configuration.Configurator.load_zcml` method, and
   end configuration using the
   :meth:`pyramid.configuration.Configurator.end` method.

#. *Line 22*.  Use the
   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method
   to return a :term:`WSGI` application.

Configuration With ``configure.zcml``
--------------------------------------
@@ -91,47 +132,4 @@
   application root.  If not, we make an instance, store it, and
   commit the transaction.  We then return the application root
   object.

App Startup with ``run.py``
---------------------------

When you run the application using the ``paster`` command using the
``tutorial.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 ``run.py``:

   .. literalinclude:: src/basiclayout/tutorial/run.py
      :linenos:
      :language: py

#. *Lines 1-2*.  Perform some dependency imports.

#. *Line 12*. Get the ZODB configuration from the ``tutorial.ini``
   file's ``[app:main]`` section represented by the ``settings``
   dictionary passed to our ``app`` function.  This will be a URI
   (something like ``file:///path/to/Data.fs``).

#. *Line 15*. We create a "finder" object using the
   ``PersistentApplicationFinder`` helper class, passing it the ZODB
   URI and the "appmaker" we've imported from ``models.py``.

#. *Lines 16 - 17*.  We create a :term:`root factory` which uses the
   finder to return a ZODB root object.

#. *Line 18*.  We construct a :term:`Configurator` with a :term:`root
   factory` and the settings keywords parsed by PasteDeploy.  The root
   factory is named ``get_root``.

#. *Lines 19-21*.  Begin configuration using the ``begin`` method of
   the :meth:`pyramid.configuration.Configurator` class, load the
   ``configure.zcml`` file from our package using the
   :meth:`pyramid.configuration.Configurator.load_zcml` method, and
   end configuration using the
   :meth:`pyramid.configuration.Configurator.end` method.

#. *Line 22*.  Use the
   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method
   to return a :term:`WSGI` application.


 docs/tutorials/wiki/definingmodels.rst

@@ -75,7 +75,7 @@
---------------

We're using a mini-framework callable named
``PersistentApplicationFinder`` in our application (see ``run.py``).
``PersistentApplicationFinder`` in our application (see ``__init__.py``).
A ``PersistentApplicationFinder`` accepts a ZODB URL as well as an
"appmaker" callback.  This callback typically lives in the
``models.py`` file.

 docs/tutorials/wiki/definingviews.rst

@@ -342,20 +342,20 @@
   :linenos:
   :language: xml

Examining ``tutorial.ini``
==========================
Examining ``development.ini``
=============================

Let's take a look at our ``tutorial.ini`` file.  The contents of the
Let's take a look at our ``development.ini`` file.  The contents of the
file are as follows:

.. literalinclude:: src/models/tutorial.ini
.. literalinclude:: src/models/development.ini
   :linenos:
   :language: ini

The WSGI Pipeline
-----------------

Within ``tutorial.ini``, note the existence of a ``[pipeline:main]``
Within ``development.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
@@ -377,10 +377,10 @@
``egg:Paste#evalerror`` middleware which displays debuggable errors in
the browser while you're developing (not recommended for deployment).
Let's insert evalerror into the pipeline right below
"egg:repoze.zodbconn#closer", making our resulting ``tutorial.ini``
"egg:repoze.zodbconn#closer", making our resulting ``development.ini``
file look like so:

.. literalinclude:: src/views/tutorial.ini
.. literalinclude:: src/views/development.ini
   :linenos:
   :language: ini


 docs/tutorials/wiki/installation.rst

@@ -244,11 +244,19 @@
Decisions the ``pyramid_zodb`` Template Has Made For You
========================================================

Creating a project using the ``pyramid_zodb`` template makes the
assumption that you are willing to use :term:`ZODB` as persistent
storage and :term:`traversal` to map URLs to code.  :mod:`pyramid`
supports any persistent storage mechanism (e.g. a SQL database or
filesystem files, etc).  It also supports an additional mechanism to
map URLs to code (:term:`URL dispatch`).  However, for the purposes of
this tutorial, we'll only be using traversal and ZODB.
Creating a project using the ``pyramid_zodb`` template makes the following
assumptions:

- you are willing to use :term:`ZODB` as persistent storage

- you are willing to use :term:`traversal` to map URLs to code.

- you want to use :term:`ZCML` to perform configuration.

.. note::

   :mod:`pyramid` supports any persistent storage mechanism (e.g. a SQL
   database or filesystem files, etc).  :mod:`pyramid` also supports an
   additional mechanism to map URLs to code (:term:`URL dispatch`).  However,
   for the purposes of this tutorial, we'll only be using traversal and ZODB.


 docs/tutorials/wiki/src/authorization/development.ini

 docs/tutorials/wiki/src/authorization/setup.py

@@ -37,7 +37,7 @@
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      app = tutorial.run:app
      app = tutorial:app
      """
      )


 docs/tutorials/wiki/src/authorization/tutorial/__init__.py

@@ -1,2 +1,22 @@
# A package
from pyramid.configuration import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder

from tutorial.models import appmaker

def app(global_config, **settings):
    """ This function returns a WSGI application.
    
    It is usually called by the PasteDeploy framework during 
    ``paster serve``.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")
    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.begin()
    config.load_zcml('configure.zcml')
    config.end()
    return config.make_wsgi_app()

 docs/tutorials/wiki/src/authorization/tutorial/run.py

File was deleted

 docs/tutorials/wiki/src/basiclayout/development.ini

 docs/tutorials/wiki/src/basiclayout/setup.py

@@ -37,6 +37,6 @@
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      app = tutorial.run:app
      app = tutorial:app
      """
      )

 docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py

@@ -1,2 +1,23 @@
# A package
from pyramid.configuration import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder

from tutorial.models import appmaker

def app(global_config, **settings):
    """ This function returns a WSGI application.
    
    It is usually called by the PasteDeploy framework during 
    ``paster serve``.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")
    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.begin()
    config.load_zcml('configure.zcml')
    config.end()
    return config.make_wsgi_app()


 docs/tutorials/wiki/src/basiclayout/tutorial/run.py

File was deleted

 docs/tutorials/wiki/src/models/development.ini

 docs/tutorials/wiki/src/models/setup.py

@@ -37,6 +37,6 @@
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      app = tutorial.run:app
      app = tutorial:app
      """
      )

 docs/tutorials/wiki/src/models/tutorial/__init__.py

@@ -1,2 +1,23 @@
# A package
from pyramid.configuration import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder

from tutorial.models import appmaker

def app(global_config, **settings):
    """ This function returns a WSGI application.
    
    It is usually called by the PasteDeploy framework during 
    ``paster serve``.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")
    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.begin()
    config.load_zcml('configure.zcml')
    config.end()
    return config.make_wsgi_app()


 docs/tutorials/wiki/src/models/tutorial/run.py

File was deleted

 docs/tutorials/wiki/src/viewdecorators/development.ini

 docs/tutorials/wiki/src/viewdecorators/setup.py

@@ -37,6 +37,6 @@
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      app = tutorial.run:app
      app = tutorial:app
      """
      )

 docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py

@@ -1,2 +1,23 @@
# A package
from pyramid.configuration import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder

from tutorial.models import appmaker

def app(global_config, **settings):
    """ This function returns a WSGI application.
    
    It is usually called by the PasteDeploy framework during 
    ``paster serve``.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")
    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.begin()
    config.load_zcml('configure.zcml')
    config.end()
    return config.make_wsgi_app()


 docs/tutorials/wiki/src/viewdecorators/tutorial/run.py

File was deleted

 docs/tutorials/wiki/src/views/development.ini

 docs/tutorials/wiki/src/views/setup.py

@@ -37,6 +37,6 @@
      test_suite="tutorial",
      entry_points = """\
      [paste.app_factory]
      app = tutorial.run:app
      app = tutorial:app
      """
      )

 docs/tutorials/wiki/src/views/tutorial/__init__.py

@@ -1,2 +1,23 @@
# A package
from pyramid.configuration import Configurator
from repoze.zodbconn.finder import PersistentApplicationFinder

from tutorial.models import appmaker

def app(global_config, **settings):
    """ This function returns a WSGI application.
    
    It is usually called by the PasteDeploy framework during 
    ``paster serve``.
    """
    zodb_uri = settings.get('zodb_uri')
    if zodb_uri is None:
        raise ValueError("No 'zodb_uri' in application configuration.")
    finder = PersistentApplicationFinder(zodb_uri, appmaker)
    def get_root(request):
        return finder(request.environ)
    config = Configurator(root_factory=get_root, settings=settings)
    config.begin()
    config.load_zcml('configure.zcml')
    config.end()
    return config.make_wsgi_app()


 docs/tutorials/wiki/src/views/tutorial/run.py

File was deleted