diff options
Diffstat (limited to 'docs')
23 files changed, 94 insertions, 485 deletions
diff --git a/docs/api/registry.rst b/docs/api/registry.rst index 5f61b1122..4d327370a 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -9,6 +9,8 @@ .. attribute:: settings - The :term:`deployment settings` object. See :ref:`deployment_settings` - for information. + The dictionary-like :term:`deployment settings` object. See + :ref:`deployment_settings` for information. This object is often + accessed as ``request.registry.settings`` or + ``config.registry.settings`` in a typical Pyramid application. diff --git a/docs/api/testing.rst b/docs/api/testing.rst index fdcdadee8..f388dc263 100644 --- a/docs/api/testing.rst +++ b/docs/api/testing.rst @@ -5,26 +5,6 @@ .. automodule:: pyramid.testing - .. autofunction:: registerDummySecurityPolicy - - .. autofunction:: registerResources - - .. autofunction:: registerEventListener - - .. autofunction:: registerTemplateRenderer - - .. autofunction:: registerView - - .. autofunction:: registerUtility - - .. autofunction:: registerAdapter - - .. autofunction:: registerSubscriber - - .. autofunction:: registerRoute - - .. autofunction:: registerSettings - .. autofunction:: setUp .. autofunction:: tearDown diff --git a/docs/glossary.rst b/docs/glossary.rst index c8f1a2f12..0aef7672b 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -24,12 +24,13 @@ Glossary information about response objects. Repoze - "Repoze" is essentially a "brand" of software developed by - `Agendaless Consulting <http://agendaless.com>`_ and a set of - contributors. The term has no special intrinsic meaning. The - project's `website <http://repoze.org>`_ has more information. - The software developed "under the brand" is available in a - `Subversion repository <http://svn.repoze.org>`_. + "Repoze" is essentially a "brand" of software developed by `Agendaless + Consulting <http://agendaless.com>`_ and a set of contributors. The + term has no special intrinsic meaning. The project's `website + <http://repoze.org>`_ has more information. The software developed + "under the brand" is available in a `Subversion repository + <http://svn.repoze.org>`_. Pyramid was originally known as + :mod:`repoze.bfg`. setuptools `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ @@ -311,7 +312,8 @@ Glossary `A full-featured Python web framework <http://djangoproject.com>`_. Pylons - `A lightweight Python web framework <http://pylonshq.com>`_. + `A lightweight Python web framework <http://pylonshq.com>`_ and a + predecessor of Pyramid. ZODB `Zope Object Database <http://zodb.org>`_, a @@ -459,8 +461,7 @@ Glossary An indexing and search facility (fielded and full-text) based on `zope.index <http://pypi.python.org/pypi/zope.index>`_. See `the documentation <http://docs.repoze.org/catalog>`_ for more - information. A tutorial for its usage in :app:`Pyramid` - exists in :ref:`catalog_tutorial`. + information. repoze.who `Authentication middleware <http://docs.repoze.org/who>`_ for @@ -498,7 +499,7 @@ Glossary all URL-to-view code mappings. SQLAlchemy - `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object + `SQLAlchemy <http://www.sqlalchemy.org/>`_ is an object relational mapper used in tutorials within this documentation. JSON @@ -618,16 +619,15 @@ Glossary information. thread local - A thread-local variable is one which is essentially a global - variable in terms of how it is accessed and treated, however, - each `thread - <http://en.wikipedia.org/wiki/Thread_(computer_science)>` used by - the application may have a different value for this same "global" - variable. :app:`Pyramid` uses a small number of thread local - variables, as described in :ref:`threadlocals_chapter`. See also - the `threading.local documentation - <http://docs.python.org/library/threading.html#threading.local>` - for more information. + A thread-local variable is one which is essentially a global variable + in terms of how it is accessed and treated, however, each `thread + <http://en.wikipedia.org/wiki/Thread_(computer_science)>`_ used by the + application may have a different value for this same "global" variable. + :app:`Pyramid` uses a small number of thread local variables, as + described in :ref:`threadlocals_chapter`. See also the `threading.local + documentation + <http://docs.python.org/library/threading.html#threading.local>`_ for + more information. multidict An ordered dictionary that can have multiple values for each @@ -644,11 +644,11 @@ Glossary and Chris McDonough. See also http://agendaless.com . Jython - A `Python implementation <http://www.jython.org/>` written for + A `Python implementation <http://www.jython.org/>`_ written for the Java Virtual Machine. Python - The `programming language <http://python.org>` in which + The `programming language <http://python.org>`_ in which :app:`Pyramid` is written. CPython @@ -863,8 +863,7 @@ Glossary pyramid_handlers An add-on package which allows :app:`Pyramid` users to create classes that are analogues of Pylons 1 "controllers". See - `http://docs.pylonsproject.org/projects/pyramid_handlers/dev/ - <http://docs.pylonsproject.org/projects/pyramid_handlers/dev/>`_. + http://docs.pylonsproject.org/projects/pyramid_handlers/dev/ . pyramid_jinja2 :term:`Jinja2` templating system bindings for Pyramid, documented at @@ -881,9 +880,9 @@ Glossary information. Pyramid Cookbook - An `additional documentation resource - <http://docs.pylonsproject.org/projects/pyramid_cookbook/dev/index.html>`_ - for Pyramid which presents topical, practical usages of Pyramid. + An additional documentation resource for Pyramid which presents topical, + practical usages of Pyramid available via + http://docs.pylonsproject.org/ . distutils The standard system for packaging and distributing Python packages. See diff --git a/docs/index.rst b/docs/index.rst index 8717542f1..d55daccfe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -81,8 +81,6 @@ applications to various platforms. tutorials/bfg/index.rst tutorials/gae/index.rst tutorials/modwsgi/index.rst - tutorials/zeo/index.rst - tutorials/catalog/index.rst Reference Material ================== diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 077283228..53034d059 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -69,8 +69,6 @@ Tutorials tutorials/wiki2/index.rst tutorials/gae/index.rst tutorials/modwsgi/index.rst - tutorials/zeo/index.rst - tutorials/catalog/index.rst .. _api_reference: diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ea7134a3e..f5adad905 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -7,13 +7,6 @@ In this chapter, we will walk through the creation of a tiny :app:`Pyramid` application. After we're finished creating the application, we'll explain in more detail how it works. -.. note:: - - If you're a "theory-first" kind of person, you might choose to read - :ref:`urldispatch_chapter` and :ref:`views_chapter` before diving into - the code that follows, but it's not necessary if -- like many programmers - -- you're willing to "go with the flow". - .. _helloworld_imperative: Hello World, Goodbye World diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 6aef2fd6b..364dad97f 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -6,8 +6,7 @@ Much Ado About Traversal .. note:: This chapter was adapted, with permission, from a blog post by `Rob Miller <http://blog.nonsequitarian.org/>`_, originally published at - `http://blog.nonsequitarian.org/2010/much-ado-about-traversal/ - <http://blog.nonsequitarian.org/2010/much-ado-about-traversal/>`_. + http://blog.nonsequitarian.org/2010/much-ado-about-traversal/ . Traversal is an alternative to :term:`URL dispatch` which allows :app:`Pyramid` applications to map URLs to code. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index c076c67ac..7e2730e97 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -137,16 +137,11 @@ project we name ``MyProject``: name during ``paster create`` by adding the project name to the command line, e.g. ``paster create -t pyramid_starter MyProject``. -.. note:: You may encounter an error when using ``paster create`` - if a dependent Python package is not installed. This will - result in a traceback ending in: - - .. code-block:: text - - pkg_resources.DistributionNotFound: <package name> - - Simply run ``bin/easy_install``, with the missing package - name from the error message, to work around this issue. +.. note:: You may encounter an error when using ``paster create`` if a + dependent Python package is not installed. This will result in a traceback + ending in ``pkg_resources.DistributionNotFound: <package name>``. + Simply run ``bin/easy_install``, with the missing package name from the + error message to work around this issue. As a result of invoking the ``paster create`` command, a project is created in a directory named ``MyProject``. That directory is a :term:`project` @@ -325,37 +320,34 @@ unconditionally. [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ development.ini MyProject -.. warning:: +You should always use a section name argument that refers to the actual +``app`` section within the Paste configuration file that points at your +:app:`Pyramid` application *without any middleware wrapping*. In particular, +a section name is inappropriate as the second argument to ``pshell`` if the +configuration section it names is a ``pipeline`` rather than an ``app``. For +example, if you have the following ``.ini`` file content: + +.. code-block:: ini + :linenos: + + [app:MyProject] + use = egg:MyProject + reload_templates = true + debug_authorization = false + debug_notfound = false + debug_templates = true + default_locale_name = en + + [pipeline:main] + pipeline = + egg:WebError#evalerror + MyProject - You should always use a section name argument that refers to the actual - ``app`` section within the Paste configuration file that points at your - :app:`Pyramid` application *without any middleware wrapping*. In - particular, a section name is inappropriate as the second argument to - ``pshell`` if the configuration section it names is a ``pipeline`` rather - than an ``app``. For example, if you have the following ``.ini`` file - content: - - .. code-block:: guess - :linenos: - - [app:MyProject] - use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en - - [pipeline:main] - pipeline = - egg:WebError#evalerror - MyProject - - Use ``MyProject`` instead of ``main`` as the section name argument to - ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell - development.ini MyProject``). If you use ``main`` instead, an error will - occur. Use the most specific reference to your application within the - ``.ini`` file possible as the section name argument. +Use ``MyProject`` instead of ``main`` as the section name argument to +``pshell`` against the above ``.ini`` file (e.g. ``paster pshell +development.ini MyProject``). If you use ``main`` instead, an error will +occur. Use the most specific reference to your application within the +``.ini`` file possible as the section name argument. Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -511,8 +503,8 @@ describe, run, and test your application. ``setup.py``. #. ``MANIFEST.in`` is a :term:`distutils` "manifest" file, naming which files - should be included in a source distribution of the package when ``python - setup.py sdist`` is run. + should be included in a source distribution of the package when ``python + setup.py sdist`` is run. #. ``setup.py`` is the file you'll use to test and distribute your application. It is a standard :term:`setuptools` ``setup.py`` file. @@ -532,8 +524,10 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: +.. latexbroken? + .. literalinclude:: MyProject/development.ini - :language: guess + :language: ini :linenos: This file contains several "sections" including ``[app:MyProject]``, diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f4655727c..e2c43b17e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -82,7 +82,7 @@ Here's a high-level time-ordered overview of what happens when you press Our generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini - :language: guess + :language: ini :linenos: In this case, the ``myproject.__init__:main`` function referred to by the diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d6d9a4e3e..d37e9722b 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -744,8 +744,8 @@ look like: <body> <h1 class="title">Welcome to <code>${project}</code>, an application generated by the <a - href="http://docs.pylonsproject.org/projects/pyramid/dev/">pyramid</a> web - application framework.</h1> + href="http://docs.pylonsproject.org/projects/pyramid/dev/" + >pyramid</a> web application framework.</h1> </body> </html> diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 2de8d4ec1..626d2db2c 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -1019,8 +1019,10 @@ route configuration looks like so: .. code-block:: python :linenos: - config.add_route('noslash', 'no_slash', view='myproject.views.no_slash') - config.add_route('hasslash', 'has_slash/', view='myproject.views.has_slash') + config.add_route('noslash', 'no_slash', + view='myproject.views.no_slash') + config.add_route('hasslash', 'has_slash/', + view='myproject.views.has_slash') If a request enters the application with the ``PATH_INFO`` value of ``/has_slash/``, the second route will match. If a request enters the diff --git a/docs/tutorials/catalog/index.rst b/docs/tutorials/catalog/index.rst deleted file mode 100644 index e4e5bd720..000000000 --- a/docs/tutorials/catalog/index.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _catalog_tutorial: - -Using :mod:`repoze.catalog` Within :app:`Pyramid` -================================================= - -:mod:`repoze.catalog` is a ZODB-based system that can be used to index -Python objects. It also offers a query interface for retrieving -previously indexed data. Those whom are used to Zope's "ZCatalog" -implementation will feel at home using :mod:`repoze.catalog`. - -This tutorial assumes that you want a Zope-like setup. For example, -it assumes you want to use a persistent ZODB object as your -:term:`root` object, and that the :mod:`repoze.catalog` catalog will -be an attribute of this root object. It is further assumed that you -want the application to be based on :term:`traversal`. - -#. Follow the :ref:`zodb_with_zeo` tutorial to get a system set up - with ZODB and ZEO. When you are finished, come back here. - -#. Install the :mod:`repoze.catalog` software within your application's - environment: - - .. code-block:: text - - $ easy_install repoze.catalog - -#. Change your ZODB application's ``models.py`` file to look like the - below: - - .. code-block:: python - :linenos: - - from repoze.folder import Folder - from repoze.catalog.catalog import Catalog - from repoze.catalog.document import DocumentMap - from repoze.catalog.indexes.field import CatalogFieldIndex - - def get_title(object, default): - title = getattr(object, 'title', '') - if isinstance(title, basestring): - # lowercase for alphabetic sorting - title = title.lower() - return title - - class Document(Folder): - def __init__(self, title): - self.title = title - Folder.__init__(self) - - class Site(Folder): - def __init__(self): - self.catalog = Catalog() - self.catalog.document_map = DocumentMap() - self.update_indexes() - Folder.__init__(self) - - def update_indexes(self): - indexes = { - 'title': CatalogFieldIndex(get_title), - } - - catalog = self.catalog - - # add indexes - for name, index in indexes.iteritems(): - if name not in catalog: - catalog[name] = index - - # remove indexes - for name in catalog.keys(): - if name not in indexes: - del catalog[name] - - def appmaker(root): - if not 'site' in root: - root['site'] = Site() - transaction.commit() - return root['site'] - -#. We'll demonstrate how you might interact with a catalog from code - by manipulating the database directly using the ``pshell`` - command in a terminal window: - - .. code-block:: text - - [chrism@snowpro sess]$ ../bin/paster --plugin=pyramid pshell \ - development.ini myapp - Python 2.5.4 (r254:67916, Sep 4 2009, 02:12:16) - [GCC 4.2.1 (Apple Inc. build 5646)] on darwin - Type "help" for more information. "root" is the Pyramid app root object. - >>> from pyramid.traversal import resource_path - >>> from myapp.models import Document - >>> root['name'] = Document('title') - >>> doc = root['name'] - >>> docid = root.catalog.document_map.add(resource_path(doc)) - >>> root.catalog.index_doc(docid, doc) - >>> import transaction - >>> transaction.commit() - >>> root.catalog.search(title='title') - (1, IFSet([-787959756])) - -As you need them, add other indexes required by your application to -the catalog by modifying the ``update_indexes`` method of the ``Site`` -object. Whenever an index is added or removed, invoke the -``update_indexes`` method of the site (the root object) from a script -or from within a ``pshell`` session to update the set of indexes -used by your application. - -In :term:`view` code, you should be able to get a hold of he root -object via the :func:`pyramid.traversal.find_root` API. The -``catalog`` attribute of that root object will represent the catalog -previously added. - -Read the :mod:`repoze.catalog` `documentation -<http://docs.repoze.org/catalog>`_ for further information about other -types of indexes to add, using the document map, and how to issue -queries using the catalog query API. - -.. note:: - - The :mod:`repoze.folder` implementation sends events that can be - intercepted by a :term:`subscriber` when objects are added and - removed from a folder. It is often useful to hook these events for - the purpose of mutating the catalog when a new documentlike object - is added or removed. See the `repoze.folder documentation - <http://docs.repoze.org/folder>`_ for more information about the - events it sends. diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index c6d5d891d..5da7f32c7 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -102,7 +102,8 @@ commands and files. # play badly with C extensions. WSGIApplicationGroup %{GLOBAL} WSGIPassAuthorization On - WSGIDaemonProcess pyramid user=chrism group=staff processes=1 threads=4 \ + WSGIDaemonProcess pyramid user=chrism group=staff processes=1 \ + threads=4 \ python-path=/Users/chrism/modwsgi/env/lib/python2.6/site-packages WSGIScriptAlias /myapp /Users/chrism/modwsgi/env/pyramid.wsgi diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt index 62b9cad7e..f9da6c414 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt @@ -55,7 +55,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt index eaf7123d7..64e592ea9 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt @@ -51,7 +51,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt index 62f75da21..d207a0c23 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt @@ -58,7 +58,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki/src/basiclayout/development.ini b/docs/tutorials/wiki/src/basiclayout/development.ini index 054720aa2..fcd444cf6 100644 --- a/docs/tutorials/wiki/src/basiclayout/development.ini +++ b/docs/tutorials/wiki/src/basiclayout/development.ini @@ -46,6 +46,6 @@ level = NOTSET formatter = generic [formatter_generic] -format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s +format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s # End logging configuration diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt index 9e6149188..6dbb0edde 100644 --- a/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt +++ b/docs/tutorials/wiki/src/views/tutorial/templates/edit.pt @@ -51,7 +51,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/view.pt b/docs/tutorials/wiki/src/views/tutorial/templates/view.pt index 9b0713330..537ae3a15 100644 --- a/docs/tutorials/wiki/src/views/tutorial/templates/view.pt +++ b/docs/tutorials/wiki/src/views/tutorial/templates/view.pt @@ -54,7 +54,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt index eaf7123d7..64e592ea9 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt +++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/login.pt @@ -51,7 +51,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt index 470917436..5a69818c1 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt +++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/view.pt @@ -58,7 +58,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt index 2e3a75324..3f2039cb6 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt +++ b/docs/tutorials/wiki2/src/views/tutorial/templates/edit.pt @@ -51,7 +51,8 @@ </div> </div> <div id="footer"> - <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div> + <div class="footer" + >© Copyright 2008-2011, Agendaless Consulting.</div> </div> </body> </html> diff --git a/docs/tutorials/zeo/index.rst b/docs/tutorials/zeo/index.rst deleted file mode 100644 index b47c6c477..000000000 --- a/docs/tutorials/zeo/index.rst +++ /dev/null @@ -1,238 +0,0 @@ -.. _zodb_with_zeo: - -Using ZODB with ZEO -=================== - -:term:`ZODB` is a Python object persistence mechanism. :term:`ZODB` -works well as a storage mechanism for :app:`Pyramid` applications, -especially in applications that use :term:`traversal`. - -:term:`ZEO` is an extension to ZODB which allows more than one process -to simultaneously communicate with a ZODB storage. Making a ZODB -database accessible to more than one process means that you can debug -your application objects at the same time that a :app:`Pyramid` -server that accesses the database is running, and will also allow your -application to run under multiprocess configurations, such as those -exposed by :term:`mod_wsgi`. - -The easiest way to get started with ZODB in a :app:`Pyramid` application is -to use the ZODB ``pyramid_zodb`` paster template. See -:ref:`additional_paster_templates` for more information about using this -template. However, the Paster template does not set up a ZEO-capable -application. This chapter shows you how to do that "from scratch". - -Installing Dependencies ------------------------ - -#. Edit your :app:`Pyramid` application's ``setup.py`` file, adding - the following packages to the ``install_requires`` of the - application: - - - ``repoze.folder`` - - - ``repoze.retry`` - - - ``repoze.tm2`` - - - ``repoze.zodbconn`` - - For example, the relevant portion of your application's - ``setup.py`` file might look like so when you're finished adding - the dependencies. - - .. code-block:: python - :linenos: - - setup( - # ... other elements left out for brevity - install_requires=[ - 'pyramid', - 'repoze.folder', - 'repoze.retry', - 'repoze.tm2', - 'repoze.zodbconn', - ], - # ... other elements left out for brevity - ) - -#. Rerun your application's ``setup.py`` file (e.g. using ``python - setup.py develop``) to get these packages installed. A number of - packages will be installed, including ``ZODB``. For the purposes - of this tutorial, we'll assume that your "application" is actually - just the result of the ``pyramid_starter`` Paster template. - -Configuration -------------- - -#. Edit your application's Paste ``development.ini`` file. - - If you already have an ``app`` section in the ``.ini`` file named - ``main``, rename this section to ``myapp`` (e.g. ``app:main`` -> - ``app:myapp``). Add a key to it named ``zodb_uri``, e.g. - - .. code-block:: ini - - [app:myapp] - use = egg:myapp#app - zodb_uri = zeo://%(here)s/zeo.sock - reload_templates = true - debug_authorization = false - debug_notfound = false - - If a ``pipeline`` named ``main`` does not already exist in the - paste ``.ini`` file , add a ``pipeline`` section named ``main``. - Put the names ``connector``, ``egg:repoze.retry#retry``, and - ``egg:repoze.tm2#tm`` to the top of the pipeline. - - .. code-block:: ini - - [pipeline:main] - pipeline = - egg:repoze.retry#retry - egg:repoze.tm2#tm - myapp - - When you're finished, your ``.ini`` file might look like so: - - .. code-block:: ini - - [DEFAULT] - debug = true - - [app:myapp] - use = egg:myapp#app - zodb_uri = zeo://%(here)s/zeo.sock - reload_templates = true - debug_authorization = false - debug_notfound = false - - [pipeline:main] - pipeline = - egg:repoze.retry#retry - egg:repoze.tm2#tm - myapp - - [server:main] - use = egg:Paste#http - host = 0.0.0.0 - port = 6543 - - See :ref:`MyProject_ini` for more information about project Paste - ``.ini`` files. - -#. Add a ``zeo.conf`` file to your package with the following - contents: - - .. code-block:: text - - %define INSTANCE . - - <zeo> - address $INSTANCE/zeo.sock - read-only false - invalidation-queue-size 100 - pid-filename $INSTANCE/zeo.pid - </zeo> - - <blobstorage 1> - <filestorage> - path $INSTANCE/myapp.db - </filestorage> - blob-dir $INSTANCE/blobs - </blobstorage> - -#. For the purposes of this tutorial we'll assume that you want your - :app:`Pyramid` application's :term:`root` object to be a - "folderish" object. To achieve this, change your application's - ``models.py`` file to look like the below: - - .. code-block:: python - - from repoze.folder import Folder - - class MyModel(Folder): - pass - - def appmaker(root): - if not 'myapp' in root: - root['myapp'] = MyModel() - transaction.commit() - return root['myapp'] - -#. Change your application's ``__init__.py`` to look something like the - below: - - .. code-block:: python - - from pyramid.config import Configurator - from repoze.zodbconn.finder import PersistentApplicationFinder - from myapp.models import appmaker - import transaction - - def app(global_config, **settings): - """ This function returns a ``pyramid`` WSGI - application. - - It is usually called by the PasteDeploy framework during - ``paster serve``""" - # paster app config callback - zodb_uri = settings['zodb_uri'] - finder = PersistentApplicationFinder(zodb_uri, appmaker) - def get_root(request): - return finder(request.environ) - config = Configurator(root_factory=get_root, settings=settings) - # .. other configuration statements .. - return config.make_wsgi_app() - -Running -------- - -#. Start the ZEO server in a terminal with the current directory set - to the package directory: - - .. code-block:: text - - ../bin/runzeo -C zeo.conf - - You should see something like this, as a result: - - .. code-block:: text - :linenos: - - [chrism@snowpro myapp]$ ../bin/runzeo -C zeo.conf - ------ - 2009-09-19T13:48:41 INFO ZEO.runzeo (9910) created PID file './zeo.pid' - # ... more output ... - 2009-09-19T13:48:41 INFO ZEO.zrpc (9910) listening on ./zeo.sock - -#. While the ZEO server is running, start the application server: - - .. code-block:: text - :linenos: - - [chrism@snowpro myapp]$ ../bin/paster serve myapp.ini - Starting server in PID 10177. - serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 - -#. The root object is now a "folderish" ZODB object. Nothing else - about the application has changed. - -#. You can manipulate the database directly (even when the - application's HTTP server is running) by using the ``pshell`` - command in a third terminal window: - - .. code-block:: text - :linenos: - - [chrism@snowpro sess]$ ../bin/paster --plugin=pyramid pshell \ - myapp.ini myapp - Python 2.5.4 (r254:67916, Sep 4 2009, 02:12:16) - [GCC 4.2.1 (Apple Inc. build 5646)] on darwin - Type "help" for more information. "root" is the Pyramid app root object. - >>> root - <sess.models.MyModel object None at 0x16438f0> - >>> root.foo = 'bar' - >>> import transaction - >>> transaction.commit() - - |