diff options
| -rw-r--r-- | CHANGES.txt | 4 | ||||
| -rw-r--r-- | docs/glossary.rst | 3 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/latexindex.rst | 2 | ||||
| -rw-r--r-- | docs/tutorials/catalog/index.rst | 127 | ||||
| -rw-r--r-- | docs/tutorials/zeo/index.rst | 238 |
6 files changed, 5 insertions, 371 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 607114d84..82c1d2d33 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -14,6 +14,10 @@ Documentation ``registerAdapter``, ``registerSubscriber``, ``registerRoute``, and ``registerSettings``. +- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" + tutorials out of core documentation and into the Pyramid Tutorials site + (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/). + Bug Fixes --------- diff --git a/docs/glossary.rst b/docs/glossary.rst index 6c8d6a8f5..f1a50a0af 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -461,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 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/tutorials/catalog/index.rst b/docs/tutorials/catalog/index.rst deleted file mode 100644 index bef4b71c5..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 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. - >>> 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/zeo/index.rst b/docs/tutorials/zeo/index.rst deleted file mode 100644 index ccdeb876e..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 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. - >>> root - <sess.models.MyModel object None at 0x16438f0> - >>> root.foo = 'bar' - >>> import transaction - >>> transaction.commit() - - |