diff options
32 files changed, 235 insertions, 528 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index c2922f591..82c1d2d33 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -7,6 +7,23 @@ Documentation - Fixed bug in ZODB Wiki tutorial (missing dependency on ``docutils`` in "models" step within ``setup.py``). +- Removed API documentation for ``pyramid.testing`` APIs named + ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, + ``registerEventListener``, ``registerTemplateRenderer``, + ``registerDummyRenderer``, ``registerView``, ``registerUtility``, + ``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 +--------- + +- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit + deprecation warnings. + 1.0b3 (2011-01-28) ================== @@ -9,6 +9,11 @@ Before Release - https://github.com/Pylons/pyramid/issues#issue/67 (fixing would make it possible to render a static site from a static dir). +- Change "Cleaning up After a Request" in the urldispatch chapter to + use ``request.add_response_callback``. + +- ``repoze.retry`` in ZODB template. + Should-Have ----------- @@ -59,9 +64,6 @@ Should-Have - translationdir ZCML directive use of ``path_spec`` should maybe die. -- Change "Cleaning up After a Request" in the urldispatch chapter to - use ``request.add_response_callback``. - - Provide a response_set_cookie method on the request for rendered responses that can be used as input to response.set_cookie? 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() - - diff --git a/pyramid/config.py b/pyramid/config.py index f24e0d1f5..68b9ca449 100644 --- a/pyramid/config.py +++ b/pyramid/config.py @@ -892,11 +892,12 @@ class Configurator(object): def get_settings(self): """ - Return a 'settings' object for the current application. A - 'settings' object is a dictionary-like object that contains - key/value pairs based on the dictionary passed as the ``settings`` - argument to the :class:`pyramid.config.Configurator` - constructor or the :func:`pyramid.router.make_app` API. + Return a :term:`deployment settings` object for the current + application. A deployment settings object is a dictionary-like + object that contains key/value pairs based on the dictionary passed + as the ``settings`` argument to the + :class:`pyramid.config.Configurator` constructor or the + :func:`pyramid.router.make_app` API. .. note:: For backwards compatibility, dictionary keys can also be looked up as attributes of the settings object. @@ -907,10 +908,10 @@ class Configurator(object): return self.registry.settings def make_wsgi_app(self): - """ Returns a :app:`Pyramid` WSGI application representing - the current configuration state and sends a - :class:`pyramid.events.ApplicationCreated` - event to all listeners.""" + """ Commits any pending configuration statements, sends a + :class:`pyramid.events.ApplicationCreated` event to all listeners, + and returns a :app:`Pyramid` WSGI application representing the + committed configuration state.""" self.commit() from pyramid.router import Router # avoid circdep app = Router(self.registry) diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index 62dd0b5a6..d462545a2 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -618,6 +618,7 @@ class IRendererInfo(Interface): type = Attribute('The renderer type name') registry = Attribute('The "current" application registry when the ' 'renderer was created') - settings = Attribute('The ISettings dictionary related to the current app') + settings = Attribute('The deployment settings dictionary related ' + 'to the current application') diff --git a/pyramid/security.py b/pyramid/security.py index 51c0802d5..4da42a966 100644 --- a/pyramid/security.py +++ b/pyramid/security.py @@ -144,7 +144,7 @@ def remember(request, principal, **kw): implied by the data passed as ``principal`` and ``*kw`` using the current :term:`authentication policy`. Common usage might look like so within the body of a view function (``response`` is - assumed to be an :term:`WebOb` -style :term:`response` object + assumed to be a :term:`WebOb` -style :term:`response` object computed previously by the view code):: from pyramid.security import remember diff --git a/pyramid/settings.py b/pyramid/settings.py index e33a8e086..9d1bb6acb 100644 --- a/pyramid/settings.py +++ b/pyramid/settings.py @@ -85,7 +85,7 @@ def get_settings(): performs the same duty. .. warning:: This method is deprecated as of Pyramid 1.0. Use - ``pyramid.threadlocals.get_current_registry().settings`` instead or use ' + ``pyramid.threadlocals.get_current_registry().settings`` instead or use the ``settings`` attribute of the registry available from the request (``request.registry.settings``). """ diff --git a/pyramid/testing.py b/pyramid/testing.py index f159d47f8..096b260b2 100644 --- a/pyramid/testing.py +++ b/pyramid/testing.py @@ -2,6 +2,7 @@ import copy import os from zope.configuration.xmlconfig import _clearContext +from zope.deprecation import deprecated from zope.interface import implements from zope.interface import Interface @@ -64,6 +65,12 @@ def registerDummySecurityPolicy(userid=None, groupids=(), permissive=True): config.commit() return result +deprecated('registerDummySecurityPolicy', + 'The testing.registerDummySecurityPolicy API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_securitypolicy ' + 'method in your unit and integration tests. ') + def registerResources(resources): """ Registers a dictionary of :term:`resource` objects that can be resolved via the :func:`pyramid.traversal.find_resource` API. @@ -90,8 +97,20 @@ def registerResources(resources): config.commit() return result +deprecated('registerResources', + 'The testing.registerResources API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_resources ' + 'method in your unit and integration tests. ') + registerModels = registerResources +deprecated('registerModels', + 'The testing.registerModels API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_resources ' + 'method in your unit and integration tests. ') + def registerEventListener(event_iface=None): """ Registers an :term:`event` listener (aka :term:`subscriber`) listening for events of the type ``event_iface``. This method @@ -120,6 +139,12 @@ def registerEventListener(event_iface=None): config.commit() return result +deprecated('registerEventListener', + 'The testing.registerEventListener API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_add_subscriber ' + 'method in your unit and integration tests. ') + def registerTemplateRenderer(path, renderer=None): """ Register a template renderer at ``path`` (usually a relative filename ala ``templates/foo.pt``) and return the renderer object. @@ -132,7 +157,7 @@ def registerTemplateRenderer(path, renderer=None): .. warning:: This API is deprecated as of :app:`Pyramid` 1.0. Instead use the - :meth:`pyramid.config.Configurator.testing_add_template` + :meth:`pyramid.config.Configurator.testing_add_renderer` method in your unit and integration tests. """ @@ -142,10 +167,22 @@ def registerTemplateRenderer(path, renderer=None): config.commit() return result +deprecated('registerTemplateRenderer', + 'The testing.registerTemplateRenderer API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_add_renderer ' + 'method in your unit and integration tests. ') + # registerDummyRenderer is a deprecated alias that should never be removed # (too much usage in the wild) registerDummyRenderer = registerTemplateRenderer +deprecated('registerDummyRenderer', + 'The testing.registerDummyRenderer API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.testing_add_renderer ' + 'method in your unit and integration tests. ') + def registerView(name, result='', view=None, for_=(Interface, Interface), permission=None): """ Registers a :app:`Pyramid` :term:`view callable` under the @@ -187,6 +224,12 @@ def registerView(name, result='', view=None, for_=(Interface, Interface), _secure.__permitted__ = permitted return registerAdapter(_secure, for_, ISecuredView, name) +deprecated('registerView', + 'The registerView API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.add_view ' + 'method in your unit and integration tests. ') + def registerUtility(impl, iface=Interface, name=''): """ Register a ZCA utility component. @@ -210,6 +253,13 @@ def registerUtility(impl, iface=Interface, name=''): reg.registerUtility(impl, iface, name=name) return impl +deprecated('registerUtility', + 'The registerUtility API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.registry.registerUtility method (via ' + 'e.g. "config.registry.registerUtility(..)" ' + 'method in your unit and integration tests. ') + def registerAdapter(impl, for_=Interface, provides=Interface, name=''): """ Register a ZCA adapter component. @@ -242,6 +292,13 @@ def registerAdapter(impl, for_=Interface, provides=Interface, name=''): reg.registerAdapter(impl, for_, provides, name=name) return impl +deprecated('registerAdapter', + 'The registerAdapter API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.registry.registerAdapter method (via ' + 'e.g. "config.registry.registerAdapter(..)" ' + 'method in your unit and integration tests. ') + def registerSubscriber(subscriber, iface=Interface): """ Register a ZCA subscriber component. @@ -268,6 +325,12 @@ def registerSubscriber(subscriber, iface=Interface): config.commit() return result +deprecated('registerSubscriber', + 'The testing.registerSubscriber API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.add_subscriber ' + 'method in your unit and integration tests. ') + def registerRoute(pattern, name, factory=None): """ Register a new :term:`route` using a pattern (e.g. ``:pagename``), a name (e.g. ``home``), and an optional root @@ -291,6 +354,12 @@ def registerRoute(pattern, name, factory=None): config.commit() return result +deprecated('registerRoute', + 'The testing.registerRoute API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.add_route ' + 'method in your unit and integration tests. ') + def registerSettings(dictarg=None, **kw): """Register one or more 'setting' key/value pairs. A setting is a single key/value pair in the dictionary-ish object returned from @@ -317,6 +386,12 @@ def registerSettings(dictarg=None, **kw): config = Configurator(registry=registry) config.add_settings(dictarg, **kw) +deprecated('registerSettings', + 'The testing.registerSettings API is deprecated as of ' + 'Pyramid 1.0. Instead use the' + 'pyramid.config.Configurator.add_settings ' + 'method in your unit and integration tests. ') + class DummyRootFactory(object): __parent__ = None __name__ = None @@ -360,12 +435,11 @@ class DummySecurityPolicy(object): class DummyTemplateRenderer(object): """ An instance of this class is returned from - :func:`pyramid.testing.registerTemplateRenderer`. It has a + :meth:`pyramid.config.Configurator.testing_add_renderer`. It has a helper function (``assert_``) that makes it possible to make an assertion which compares data passed to the renderer by the view function against expected key/value pairs. """ - def __init__(self, string_response=''): self._received = {} self._string_response = string_response @@ -622,21 +696,17 @@ def setUp(registry=None, request=None, hook_zca=True, autocommit=True, Use this function in the ``setUp`` method of a unittest test case which directly or indirectly uses: - - any of the ``register*`` functions in :mod:`pyramid.testing` - (such as :func:`pyramid.testing.registerResources`) - - any method of the :class:`pyramid.config.Configurator` object returned by this function. - the :func:`pyramid.threadlocal.get_current_registry` or :func:`pyramid.threadlocal.get_current_request` functions. - If you use the ``testing.register*`` APIs, or the - ``get_current_*`` functions (or call :app:`Pyramid` code that - uses these functions) without calling ``setUp``, - :func:`pyramid.threadlocal.get_current_registry` will return a - *global* :term:`application registry`, which may cause unit tests - to not be isolated with respect to registrations they perform. + If you use the ``get_current_*`` functions (or call :app:`Pyramid` code + that uses these functions) without calling ``setUp``, + :func:`pyramid.threadlocal.get_current_registry` will return a *global* + :term:`application registry`, which may cause unit tests to not be + isolated with respect to registrations they perform. If the ``registry`` argument is ``None``, a new empty :term:`application registry` will be created (an instance of the @@ -744,7 +814,7 @@ def cleanUp(*arg, **kw): class DummyRendererFactory(object): """ Registered by - ``pyramid.config.Configurator.testing_add_renderer`` as + :meth:`pyramid.config.Configurator.testing_add_renderer` as a dummy renderer factory. The indecision about what to use as a key (a spec vs. a relative name) is caused by test suites in the wild believing they can register either. The ``factory`` argument diff --git a/pyramid/tests/test_renderers.py b/pyramid/tests/test_renderers.py index 8711c25e0..3edeb0f4c 100644 --- a/pyramid/tests/test_renderers.py +++ b/pyramid/tests/test_renderers.py @@ -17,7 +17,8 @@ class TestTemplateRendererFactory(unittest.TestCase): def test_abspath_notfound(self): from pyramid.interfaces import ITemplateRenderer abspath = '/wont/exist' - testing.registerUtility({}, ITemplateRenderer, name=abspath) + self.config.registry.registerUtility( + {}, ITemplateRenderer, name=abspath) info = DummyRendererInfo({ 'name':abspath, 'package':None, @@ -32,7 +33,8 @@ class TestTemplateRendererFactory(unittest.TestCase): import os abspath = os.path.abspath(__file__) renderer = {} - testing.registerUtility(renderer, ITemplateRenderer, name=abspath) + self.config.registry.registerUtility( + renderer, ITemplateRenderer, name=abspath) info = DummyRendererInfo({ 'name':abspath, 'package':None, @@ -48,7 +50,8 @@ class TestTemplateRendererFactory(unittest.TestCase): import os abspath = os.path.abspath(__file__) renderer = {} - testing.registerUtility(renderer, ITemplateRenderer, name=abspath) + self.config.registry.registerUtility( + renderer, ITemplateRenderer, name=abspath) info = DummyRendererInfo({ 'name':abspath, 'package':None, @@ -62,7 +65,8 @@ class TestTemplateRendererFactory(unittest.TestCase): def test_relpath_path_registered(self): renderer = {} from pyramid.interfaces import ITemplateRenderer - testing.registerUtility(renderer, ITemplateRenderer, name='foo/bar') + self.config.registry.registerUtility( + renderer, ITemplateRenderer, name='foo/bar') spec = 'foo/bar' info = DummyRendererInfo({ 'name':spec, @@ -79,8 +83,9 @@ class TestTemplateRendererFactory(unittest.TestCase): from pyramid.interfaces import ITemplateRenderer import pyramid.tests spec = 'bar/baz' - testing.registerUtility(renderer, ITemplateRenderer, - name='pyramid.tests:bar/baz') + self.config.registry.registerUtility( + renderer, ITemplateRenderer, + name='pyramid.tests:bar/baz') info = DummyRendererInfo({ 'name':spec, 'package':pyramid.tests, @@ -116,7 +121,8 @@ class TestTemplateRendererFactory(unittest.TestCase): 'type':'type', }) renderer = {} - testing.registerUtility(renderer, ITemplateRenderer, name=spec) + self.config.registry.registerUtility( + renderer, ITemplateRenderer, name=spec) result = self._callFUT(info, None) self.failUnless(result is renderer) @@ -148,7 +154,7 @@ class TestTemplateRendererFactory(unittest.TestCase): from pyramid.interfaces import ISettings from pyramid.interfaces import ITemplateRenderer settings = {'reload_assets':True} - testing.registerUtility(settings, ISettings) + self.config.registry.registerUtility(settings, ISettings) renderer = {} factory = DummyFactory(renderer) spec = 'test_renderers.py' @@ -208,7 +214,8 @@ class TestRendererFromName(unittest.TestCase): fixture = os.path.join(here, 'fixtures/minimal.pt') def factory(info, **kw): return info - testing.registerUtility(factory, IRendererFactory, name='.pt') + self.config.registry.registerUtility( + factory, IRendererFactory, name='.pt') result = self._callFUT(fixture) self.assertEqual(result.registry, registry) self.assertEqual(result.type, '.pt') @@ -227,7 +234,8 @@ class TestRendererFromName(unittest.TestCase): fixture = os.path.join(here, 'fixtures/minimal.pt') def factory(info, **kw): return info - testing.registerUtility(factory, IRendererFactory, name='.pt') + self.config.registry.registerUtility( + factory, IRendererFactory, name='.pt') result = self._callFUT(fixture, pyramid) self.assertEqual(result.registry, registry) self.assertEqual(result.type, '.pt') diff --git a/pyramid/view.py b/pyramid/view.py index c3ab1d4b1..935104035 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -130,9 +130,10 @@ def is_response(ob): """ Return ``True`` if ``ob`` implements the interface implied by :ref:`the_response`. ``False`` if not. - .. note:: this isn't a true interface check (in Zope terms), it's a - duck-typing check, as response objects are not obligated to - actually implement a Zope interface.""" + .. note:: This isn't a true interface or subclass check. Instead, it's a + duck-typing check, as response objects are not obligated to be of a + particular class or provide any particular Zope interface.""" + # response objects aren't obligated to implement a Zope interface, # so we do it the hard way if ( hasattr(ob, 'app_iter') and hasattr(ob, 'headerlist') and @@ -318,8 +319,6 @@ class view_config(object): non-class callable. See :ref:`class_as_view` for more information. - .. warning:: Using a class as a view is a new feature in 0.8.1+. - The ``view_config`` decorator can also be used against a class method:: |