diff options
Diffstat (limited to 'docs/narr')
| -rw-r--r-- | docs/narr/advconfig.rst | 10 | ||||
| -rw-r--r-- | docs/narr/environment.rst | 16 | ||||
| -rw-r--r-- | docs/narr/extending.rst | 6 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 35 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 46 | ||||
| -rw-r--r-- | docs/narr/i18n.rst | 14 | ||||
| -rw-r--r-- | docs/narr/project.rst | 14 | ||||
| -rw-r--r-- | docs/narr/renderers.rst | 28 | ||||
| -rw-r--r-- | docs/narr/resources.rst | 16 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 30 | ||||
| -rw-r--r-- | docs/narr/viewconfig.rst | 24 | ||||
| -rw-r--r-- | docs/narr/zca.rst | 8 |
12 files changed, 124 insertions, 123 deletions
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 5ee554284..3bd9c2a4e 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -86,9 +86,9 @@ that ends something like this: for action in resolveConflicts(self.actions): File "zope/configuration/config.py", line 1507, in resolveConflicts raise ConfigurationConflictError(conflicts) - zope.configuration.config.ConfigurationConflictError: + zope.configuration.config.ConfigurationConflictError: Conflicting configuration actions - For: ('view', None, '', None, <InterfaceClass pyramid.interfaces.IView>, + For: ('view', None, '', None, <InterfaceClass pyramid.interfaces.IView>, None, None, None, None, None, False, None, None, None) ('app.py', 14, '<module>', 'config.add_view(hello_world)') ('app.py', 17, '<module>', 'config.add_view(hello_world)') @@ -291,7 +291,7 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_route`, :meth:`~pyramid.config.Configurator.add_renderer`, :meth:`~pyramid.config.Configurator.set_request_factory`, -:meth:`~pyramid.config.Configurator.set_renderer_globals_factory` +:meth:`~pyramid.config.Configurator.set_renderer_globals_factory`, :meth:`~pyramid.config.Configurator.set_locale_negotiator` and :meth:`~pyramid.config.Configurator.set_default_permission`. @@ -425,7 +425,7 @@ For example: if __name__ == '__main__': config = Configurator() - config.add_directive('add_newrequest_subscriber', + config.add_directive('add_newrequest_subscriber', add_newrequest_subscriber) Once :meth:`~pyramid.config.Configurator.add_directive` is called, a user can @@ -450,7 +450,7 @@ code in a package named ``pyramid_subscriberhelpers``: :linenos: def includeme(config) - config.add_directive('add_newrequest_subscriber', + config.add_directive('add_newrequest_subscriber', add_newrequest_subscriber) The user of the add-on package ``pyramid_subscriberhelpers`` would then be diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index e15f7810c..3b938c09c 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -13,7 +13,7 @@ single: environment variables single: ini file settings single: PasteDeploy settings - + .. _environment_chapter: Environment Variables and ``.ini`` File Settings @@ -84,7 +84,7 @@ when this value is true. See also :ref:`debug_authorization_section`. | ``PYRAMID_DEBUG_AUTHORIZATION`` | ``debug_authorization`` | | | | | | | -| | | +| | | +---------------------------------+-----------------------------+ Debugging Not Found Errors @@ -259,7 +259,7 @@ List of string filter names that will be applied to all Mako expressions. Mako Import +++++++++++ -String list of Python statements, typically individual “import” lines, which +String list of Python statements, typically individual "import" lines, which will be placed into the module level preamble of all generated Python modules. @@ -330,7 +330,7 @@ settings that do not start with ``debug_*`` such as ``reload_templates``. If you want to turn all ``reload`` settings (every setting that starts -with ``reload_``). on in one fell swoop, you can use +with ``reload_``) on in one fell swoop, you can use ``PYRAMID_RELOAD_ALL=1`` as an environment variable setting or you may use ``reload_all=true`` in the config file. Note that this does not affect settings that do not start with ``reload_*`` such as @@ -341,10 +341,10 @@ affect settings that do not start with ``reload_*`` such as most useful during development, where you may wish to augment or override the more permanent settings in the configuration file. This is useful because many of the reload and debug settings may - have performance or security (i.e., disclosure) implications + have performance or security (i.e., disclosure) implications that make them undesirable in a production environment. -.. index:: +.. index:: single: reload_templates single: reload_assets @@ -442,7 +442,7 @@ Here's how: registry = pyramid.threadlocal.get_current_registry() settings = registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - - + + diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 9c96fd605..f62c7e6bb 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -120,7 +120,7 @@ are declarations made using the :meth:`pyramid.config.Configurator.add_view` method. Assets are files that are accessed by :app:`Pyramid` using the :term:`pkg_resources` API such as static files and templates via a :term:`asset specification`. Other directives and -configurator methods also deal in routes, views, and assets. For example, +configurator methods also deal in routes, views, and assets. For example, the ``add_handler`` directive of the ``pyramid_handlers`` package adds a single route, and some number of views. @@ -163,7 +163,7 @@ views or routes which performs overrides. if __name__ == '__main__': config.scan('someotherpackage') config.commit() - config.add_view('mypackage.views.myview', name='myview' + config.add_view('mypackage.views.myview', name='myview') Once this is done, you should be able to extend or override the application like any other (see :ref:`extending_the_application`). @@ -201,7 +201,7 @@ like this: application (e.g. ``python setup.py develop`` or ``python setup.py install``). -- Change the ``main`` function in the new package's ``__init__py`` to include +- Change the ``main`` function in the new package's ``__init__.py`` to include the original :app:`Pyramid` application's configuration functions via :meth:`pyramid.config.Configurator.include` statements or a :term:`scan`. diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 8e5b93ed4..8426f11fd 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -85,7 +85,7 @@ The default forbidden response has a 403 status code and is very plain, but the view which generates it can be overridden as necessary. The :term:`forbidden view` callable is a view callable like any other. The -:term:`view configuration` which causes it to be a "not found" view consists +:term:`view configuration` which causes it to be a "forbidden" view consists only of naming the :exc:`pyramid.httpexceptions.HTTPForbidden` class as the ``context`` of the view configuration. @@ -183,7 +183,7 @@ Adding Renderer Globals ----------------------- Whenever :app:`Pyramid` handles a request to perform a rendering (after a -view with a ``renderer=`` configuration attribute is invoked, or when the any +view with a ``renderer=`` configuration attribute is invoked, or when any of the methods beginning with ``render`` within the :mod:`pyramid.renderers` module are called), *renderer globals* can be injected into the *system* values sent to the renderer. By default, no renderer globals are injected, @@ -200,7 +200,7 @@ callable object or a :term:`dotted Python name` representing such a callable. :linenos: def renderer_globals_factory(system): - return {'a':1} + return {'a': 1} config = Configurator( renderer_globals_factory=renderer_globals_factory) @@ -221,7 +221,7 @@ already constructed a :term:`configurator` it can also be registered via the from pyramid.config import Configurator def renderer_globals_factory(system): - return {'a':1} + return {'a': 1} config = Configurator() config.set_renderer_globals_factory(renderer_globals_factory) @@ -238,8 +238,8 @@ Using The Before Render Event ----------------------------- Subscribers to the :class:`pyramid.events.BeforeRender` event may introspect -the and modify the set of :term:`renderer globals` before they are passed to -a :term:`renderer`. This event object iself has a dictionary-like interface +and modify the set of :term:`renderer globals` before they are passed to a +:term:`renderer`. This event object iself has a dictionary-like interface that can be used for this purpose. For example: .. code-block:: python @@ -485,7 +485,7 @@ resource by adding a registerAdapter call for from myapp.traversal import URLGenerator from myapp.resources import MyRoot - config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), + config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), IContextURL) In the above example, the ``myapp.traversal.URLGenerator`` class will be used @@ -626,7 +626,7 @@ Using a View Mapper The default calling conventions for view callables are documented in the :ref:`views_chapter` chapter. You can change the way users define view -callbles by employing a :term:`view mapper`. +callables by employing a :term:`view mapper`. A view mapper is an object that accepts a set of keyword arguments and which returns a callable. The returned callable is called with the :term:`view @@ -740,24 +740,22 @@ follows: :linenos: import venusian - from pyramid.threadlocal import get_current_registry from mypackage.interfaces import IMyUtility - + class registerFunction(object): - + def __init__(self, path): self.path = path def register(self, scanner, name, wrapped): registry = scanner.config.registry registry.getUtility(IMyUtility).register( - self.path, wrapped - ) - + self.path, wrapped) + def __call__(self, wrapped): venusian.attach(wrapped, self.register) return wrapped - + This decorator could then be used to register functions throughout your code: @@ -776,16 +774,17 @@ performed, enabling you to set up the utility in advance: from paste.httpserver import serve from pyramid.config import Configurator + from mypackage.interfaces import IMyUtility class UtilityImplementation: - implements(ISomething) + implements(IMyUtility) def __init__(self): self.registrations = {} - def register(self,path,callable_): - self.registrations[path]=callable_ + def register(self, path, callable_): + self.registrations[path] = callable_ if __name__ == '__main__': config = Configurator() diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index f8ed743fb..97adaeafd 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -175,7 +175,7 @@ match is straightforward. When a route is matched: Root factories related to a route were explained previously within :ref:`route_factories`. Both the global root factory and default root factory were explained previously within - :ref:`the_resource_tree`. + :ref:`the_resource_tree`. .. _using_traverse_in_a_route_pattern: @@ -216,7 +216,7 @@ root factory. Once :term:`traversal` has found a :term:`context` resource, have been invoked in a "pure" traversal-based application. Let's assume there is no *global* :term:`root factory` configured in -this application. The *default* :term:`root factory` cannot be traversed: +this application. The *default* :term:`root factory` cannot be traversed: it has no useful ``__getitem__`` method. So we'll need to associate this route configuration with a custom root factory in order to create a useful hybrid application. To that end, let's imagine that @@ -233,8 +233,8 @@ we've created a root factory that looks like so in a module named def __getitem__(self, name): return self.subobjects[name] - root = Traversable( - {'a':Resource({'b':Resource({'c':Resource({})})})} + root = Resource( + {'a': Resource({'b': Resource({'c': Resource({})})})} ) def root_factory(request): @@ -247,20 +247,20 @@ configuration statement: .. code-block:: python :linenos: - config.add_route('home', '{foo}/{bar}/*traverse', + config.add_route('home', '{foo}/{bar}/*traverse', factory='mypackage.routes.root_factory') The ``factory`` above points at the function we've defined. It will return -an instance of the ``Traversable`` class as a root object whenever this route -is matched. Instances of the``Resource`` class can be used for tree -traversal because they have a ``__getitem__`` method that does something -nominally useful. Since traversal uses ``__getitem__`` to walk the resources -of a resource tree, using traversal against the root resource implied by our -route statement is a reasonable thing to do. +an instance of the ``Resource`` class as a root object whenever this route is +matched. Instances of the ``Resource`` class can be used for tree traversal +because they have a ``__getitem__`` method that does something nominally +useful. Since traversal uses ``__getitem__`` to walk the resources of a +resource tree, using traversal against the root resource implied by our route +statement is a reasonable thing to do. .. note:: - We could have also used our ``root_factory`` callable as the + We could have also used our ``root_factory`` function as the ``root_factory`` argument of the :class:`~pyramid.config.Configurator` constructor, instead of associating it with a particular route inside the route's @@ -279,12 +279,12 @@ instance named ``root`` in ``routes.py``. If the URL that matched a route with the pattern ``{foo}/{bar}/*traverse``, is ``http://example.com/one/two/a/b/c``, the traversal path used against the root object will be ``a/b/c``. As a result, -:app:`Pyramid` will attempt to traverse through the edges ``a``, -``b``, and ``c``, beginning at the root object. +:app:`Pyramid` will attempt to traverse through the edges ``'a'``, +``'b'``, and ``'c'``, beginning at the root object. In our above example, this particular set of traversal steps will mean that -the :term:`context` resource of the view would be the ``Traversable`` object -we've named ``c`` in our bogus resource tree and the :term:`view name` +the :term:`context` resource of the view would be the ``Resource`` object +we've named ``'c'`` in our bogus resource tree and the :term:`view name` resulting from traversal will be the empty string; if you need a refresher about why this outcome is presumed, see :ref:`traversal_algorithm`. @@ -297,7 +297,7 @@ invoked after a route matches: .. code-block:: python :linenos: - config.add_route('home', '{foo}/{bar}/*traverse', + config.add_route('home', '{foo}/{bar}/*traverse', factory='mypackage.routes.root_factory') config.add_view('mypackage.views.myview', route_name='home') @@ -327,11 +327,11 @@ when a hybrid route is matched: .. code-block:: python :linenos: - config.add_route('home', '{foo}/{bar}/*traverse', + config.add_route('home', '{foo}/{bar}/*traverse', factory='mypackage.routes.root_factory') - config.add_view('mypackage.views.myview', name='home') - config.add_view('mypackage.views.another_view', name='another', - route_name='home') + config.add_view('mypackage.views.myview', route_name='home') + config.add_view('mypackage.views.another_view', route_name='home', + name='another') The ``add_view`` call for ``mypackage.views.another_view`` above names a different view and, more importantly, a different :term:`view name`. The @@ -373,12 +373,12 @@ Here's a use of the ``traverse`` pattern in a call to :linenos: config.add_route('abc', '/articles/{article}/edit', - traverse='/articles/{article}') + traverse='/{article}') The syntax of the ``traverse`` argument is the same as it is for ``pattern``. -If, as above, the ``pattern`` provided is ``articles/{article}/edit``, +If, as above, the ``pattern`` provided is ``/articles/{article}/edit``, and the ``traverse`` argument provided is ``/{article}``, when a request comes in that causes the route to match in such a way that the ``article`` match value is ``1`` (when the request URI is diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index e928c6efb..c21a19b5b 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -95,7 +95,7 @@ translations of the same msgid, in case they conflict. :linenos: from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, + ts = TranslationString('Add ${number}', mapping={'number':1}, domain='form') The above translation string named a domain of ``form``. A @@ -170,7 +170,7 @@ to: :linenos: from pyramid.i18n import TranslationString as _ - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, + ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, domain='pyramid') You can set up your own translation string factory much like the one @@ -231,7 +231,7 @@ GNU gettext uses three types of files in the translation framework, A ``.pot`` file is created by a program which searches through your project's source code and which picks out every :term:`message - identifier` passed to one of the '``_()`` functions + identifier` passed to one of the ``_()`` functions (eg. :term:`translation string` constructions). The list of all message identifiers is placed into a ``.pot`` file, which serves as a template for creating ``.po`` files. @@ -288,7 +288,7 @@ like so: .. code-block:: text C> cd \my\virtualenv - C> bin\easy_install Babel lingua + C> Scripts\easy_install Babel lingua .. index:: single: Babel; message extractors @@ -535,7 +535,7 @@ translation in a view component of an application might look like so: from pyramid.i18n import get_localizer from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, + ts = TranslationString('Add ${number}', mapping={'number':1}, domain='pyramid') def aview(request): @@ -844,7 +844,7 @@ Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: python :linenos: - + from pyramid.threadlocal import get_current_registry settings = get_current_registry().settings languages = settings['available_languages'].split() @@ -897,7 +897,7 @@ application startup. For example: :linenos: from pyramid.config import Configurator - config.add_translation_dirs('my.application:locale/', + config.add_translation_dirs('my.application:locale/', 'another.application:locale/') A message catalog in a translation directory added via diff --git a/docs/narr/project.rst b/docs/narr/project.rst index c1558266a..631412f42 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -23,7 +23,7 @@ what type of application you're trying to construct. These scaffolds are rendered using the :term:`PasteDeploy` ``paster`` script. .. index:: - single: scaffolds + single: scaffolds single: pyramid_starter scaffold single: pyramid_zodb scaffold single: pyramid_alchemy scaffold @@ -55,7 +55,7 @@ The included scaffolds are these: ``pyramid_zodb`` URL mapping via :term:`traversal` and persistence via :term:`ZODB`. -``pyramid_routesalchemy`` +``pyramid_routesalchemy`` URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy` @@ -281,7 +281,7 @@ name ``MyProject`` as a section name: .. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject - Python 2.4.5 (#1, Aug 29 2008, 12:27:37) + Python 2.4.5 (#1, Aug 29 2008, 12:27:37) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin Type "help" for more information. "root" is the Pyramid app root object, "registry" is the Pyramid registry object. @@ -335,7 +335,7 @@ example, if you have the following ``.ini`` file content: default_locale_name = en [pipeline:main] - pipeline = + pipeline = egg:WebError#evalerror MyProject @@ -606,7 +606,7 @@ for each request. .. note:: - In general, :app:`Pyramid` applications generated from scaffolds + In general, :app:`Pyramid` applications generated from scaffolds should be threading-aware. It is not required that a :app:`Pyramid` application be nonblocking as all application code will run in its own thread, provided by the server you're using. @@ -622,13 +622,13 @@ implementations. Such a section should consists of global parameters that are shared by all the applications, servers and :term:`middleware` defined within the configuration file. The values in a ``[DEFAULT]`` section will be passed - to your application's ``main`` function as ``global_values`` (see + to your application's ``main`` function as ``global_config`` (see the reference to the ``main`` function in :ref:`init_py`). ``production.ini`` ~~~~~~~~~~~~~~~~~~~ -The ``development.ini`` file is a :term:`PasteDeploy` configuration file with +The ``production.ini`` file is a :term:`PasteDeploy` configuration file with a purpose much like that of ``development.ini``. However, it disables the WebError interactive debugger, replacing it with a logger which outputs exception messages to ``stderr`` by default. It also turns off template diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index c4a37c23d..18cc8e539 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -218,11 +218,11 @@ You can configure a view to use the JSON renderer by naming ``json`` as the .. code-block:: python :linenos: - config.add_view('myproject.views.hello_world', + config.add_view('myproject.views.hello_world', name='hello', context='myproject.resources.Hello', renderer='json') - + Views which use the JSON renderer can vary non-body response attributes by using the api of the ``request.response`` attribute. See @@ -246,7 +246,7 @@ See :ref:`chameleon_zpt_templates` for more information about ZPT templates. If the ``renderer`` attribute of a view configuration is an absolute path or a :term:`asset specification` which has a final path element with a filename extension of ``.txt``, the :term:`Chameleon` text renderer is used. See -:ref:`chameleon_zpt_templates` for more information about Chameleon text +:ref:`chameleon_text_templates` for more information about Chameleon text templates. The behavior of these renderers is the same, except for the engine @@ -264,7 +264,7 @@ dictionary, an error will be raised. Before passing keywords to the template, the keyword arguments derived from the dictionary returned by the view are augmented. The callable object -- -whatever object was used to define the ``view`` -- will be automatically +whatever object was used to define the view -- will be automatically inserted into the set of keyword arguments passed to the template as the ``view`` keyword. If the view callable was a class, the ``view`` keyword will be an instance of that class. Also inserted into the keywords passed to @@ -311,7 +311,7 @@ the API of the ``request.response`` attribute. See The ``Mako`` template renderer renders views using a Mako template. When used, the view must return a Response object or a Python *dictionary*. The dictionary items will then be used in the global template space. If the view -callable returns anything but a Response object, or a dictionary, an error +callable returns anything but a Response object or a dictionary, an error will be raised. When using a ``renderer`` argument to a :term:`view configuration` to specify @@ -498,15 +498,15 @@ following interface: class RendererFactory: def __init__(self, info): - """ Constructor: info will be an object having the the + """ Constructor: info will be an object having the following attributes: name (the renderer name), package (the package that was 'current' at the time the renderer was registered), type (the renderer type name), registry (the current application registry) and - settings (the deployment settings dictionary). """ + settings (the deployment settings dictionary). """ def __call__(self, value, system): - """ Call a the renderer implementation with the value + """ Call the renderer implementation with the value and the system value passed in as arguments and return the result (a string or unicode object). The value is the return value of a view. The system value is a @@ -518,7 +518,7 @@ factory constructor is available as :class:`pyramid.interfaces.IRendererInfo`. There are essentially two different kinds of renderer factories: -- A renderer factory which expects to accept a :term:`asset +- A renderer factory which expects to accept an :term:`asset specification`, or an absolute path, as the ``name`` attribute of the ``info`` object fed to its constructor. These renderer factories are registered with a ``name`` value that begins with a dot (``.``). These @@ -579,7 +579,7 @@ factory, which expects to be passed a filesystem path: .. code-block:: python :linenos: - config.add_renderer(name='.jinja2', + config.add_renderer(name='.jinja2', factory='my.package.MyJinja2Renderer') Adding the above code to your application startup will allow you to use the @@ -609,7 +609,7 @@ to the ``MyJinja2Renderer`` constructor will be the full value that was set as ``renderer=`` in the view configuration. Changing an Existing Renderer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can associate more than one filename extension with the same existing renderer implementation as necessary if you need to use a different file @@ -676,9 +676,9 @@ sets an ``override_renderer`` attribute on the request itself, which is the def set_xmlrpc_params(event): request = event.request if (request.content_type == 'text/xml' - and request.method == 'POST' - and not 'soapaction' in request.headers - and not 'x-pyramid-avoid-xmlrpc' in request.headers): + and request.method == 'POST' + and not 'soapaction' in request.headers + and not 'x-pyramid-avoid-xmlrpc' in request.headers): params, method = parse_xmlrpc_request(request) request.xmlrpc_params, request.xmlrpc_method = params, method request.is_xmlrpc = True diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index a11466a87..fa8ccc549 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -91,9 +91,9 @@ Here's a sample resource tree, represented by a variable named ``root``: root = Resource({'a':Resource({'b':Resource({'c':Resource()})})}) The resource tree we've created above is represented by a dictionary-like -root object which has a single child named ``a``. ``a`` has a single child -named ``b``, and ``b`` has a single child named ``c``, which has no children. -It is therefore possible to access ``c`` like so: +root object which has a single child named ``'a'``. ``'a'`` has a single child +named ``'b'``, and ``'b'`` has a single child named ``'c'``, which has no +children. It is therefore possible to access the ``'c'`` leaf resource like so: .. code-block:: python :linenos: @@ -101,7 +101,7 @@ It is therefore possible to access ``c`` like so: root['a']['b']['c'] If you returned the above ``root`` object from a :term:`root factory`, the -path ``/a/b/c`` would find the ``c`` object in the resource tree as the +path ``/a/b/c`` would find the ``'c'`` object in the resource tree as the result of :term:`traversal`. In this example, each of the resources in the tree is of the same class. @@ -428,7 +428,7 @@ list, we will get: .. code-block:: python :linenos: - + list(lineage(thing2)) [ <Thing object at thing2>, <Thing object at thing1> ] @@ -437,8 +437,8 @@ resource it was passed unconditionally. Then, if the resource supplied a ``__parent__`` attribute, it returns the resource represented by ``resource.__parent__``. If *that* resource has a ``__parent__`` attribute, return that resource's parent, and so on, until the resource being inspected -either has no ``__parent__`` attribute or which has a ``__parent__`` -attribute of ``None``. +either has no ``__parent__`` attribute or has a ``__parent__`` attribute of +``None``. See the documentation for :func:`pyramid.location.lineage` for more information. @@ -563,6 +563,7 @@ To do so, use the :func:`zope.interface.directlyProvides` function: .. code-block:: python :linenos: + import datetime from zope.interface import directlyProvides from zope.interface import Interface @@ -587,6 +588,7 @@ the :func:`zope.interface.alsoProvides` function: .. code-block:: python :linenos: + import datetime from zope.interface import alsoProvides from zope.interface import directlyProvides from zope.interface import Interface diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index b3747be61..e1715dc25 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -12,7 +12,7 @@ file system. Traversal walks down the path until it finds a published resource, analogous to a file system "directory" or "file". The resource found as the result of a traversal becomes the :term:`context` of the :term:`request`. Then, the :term:`view lookup` -subsystem is used to find some view code willing "publish" this +subsystem is used to find some view code willing to "publish" this resource by generating a :term:`response`. Using :term:`Traversal` to map a URL to code is optional. It is often @@ -49,17 +49,17 @@ For example, if the path info sequence is ``['a', 'b', 'c']``: can be configured to return whatever object is appropriate as the traversal root of your application. -- Next, the first element (``a``) is popped from the path segment +- Next, the first element (``'a'``) is popped from the path segment sequence and is used as a key to lookup the corresponding resource in the root. This invokes the root resource's ``__getitem__`` method - using that value (``a``) as an argument. + using that value (``'a'``) as an argument. -- If the root resource "contains" a resource with key ``a``, its +- If the root resource "contains" a resource with key ``'a'``, its ``__getitem__`` method will return it. The :term:`context` temporarily becomes the "A" resource. -- The next segment (``b``) is popped from the path sequence, and the "A" - resource's ``__getitem__`` is called with that value (``b``) as an +- The next segment (``'b'``) is popped from the path sequence, and the "A" + resource's ``__getitem__`` is called with that value (``'b'``) as an argument; we'll presume it succeeds. - The "A" resource's ``__getitem__`` returns another resource, which @@ -78,7 +78,7 @@ The results of a :term:`traversal` also include a :term:`view name`. If traversal ends before the path segment sequence is exhausted, the :term:`view name` is the *next* remaining path segment element. If the :term:`traversal` expends all of the path segments, then the :term:`view -name` is the empty string (`''`). +name` is the empty string (``''``). The combination of the context resource and the :term:`view name` found via traversal is used later in the same request by the :term:`view @@ -263,26 +263,26 @@ system uses this algorithm to find a :term:`context` resource and a UTF-8 encoding. If any URL-unquoted path segment in ``PATH_INFO`` is not decodeable using the UTF-8 decoding, a :exc:`TypeError` is raised. A segment will be fully URL-unquoted and UTF8-decoded before it is passed - it to the ``__getitem__`` of any resource during traversal. + in to the ``__getitem__`` of any resource during traversal. Thus, a request with a ``PATH_INFO`` variable of ``/a/b/c`` maps to the traversal sequence ``[u'a', u'b', u'c']``. #. :term:`Traversal` begins at the root resource returned by the root factory. For the traversal sequence ``[u'a', u'b', u'c']``, the root - resource's ``__getitem__`` is called with the name ``a``. Traversal + resource's ``__getitem__`` is called with the name ``'a'``. Traversal continues through the sequence. In our example, if the root resource's ``__getitem__`` called with the name ``a`` returns a resource (aka - "resource ``a``"), that resource's ``__getitem__`` is called with the - name ``b``. If resource A returns a resource when asked for ``b``, - "resource ``b``"'s ``__getitem__`` is then asked for the name ``c``, and - may return "resource ``c``". + resource "A"), that resource's ``__getitem__`` is called with the name + ``'b'``. If resource "A" returns a resource "B" when asked for ``'b'``, + resource B's ``__getitem__`` is then asked for the name ``'c'``, and may + return resource "C". #. Traversal ends when a) the entire path is exhausted or b) when any resouce raises a :exc:`KeyError` from its ``__getitem__`` or c) when any non-final path element traversal does not have a ``__getitem__`` method - (resulting in a :exc:`NameError`) or d) when any path element is prefixed - with the set of characters ``@@`` (indicating that the characters + (resulting in a :exc:`AttributeError`) or d) when any path element is + prefixed with the set of characters ``@@`` (indicating that the characters following the ``@@`` token should be treated as a :term:`view name`). #. When traversal ends for any of the reasons in the previous step, the last diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index d99e5bed5..5640800a2 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -77,7 +77,7 @@ All forms of view configuration accept the same general types of arguments. Many arguments supplied during view configuration are :term:`view predicate` arguments. View predicate arguments used during view configuration are used to narrow the set of circumstances in which :term:`view lookup` will find a -particular view callable. +particular view callable. In general, the fewer number of predicates which are supplied to a particular view configuration, the more likely it is that the associated @@ -112,7 +112,7 @@ Non-Predicate Arguments The name of a :term:`permission` that the user must possess in order to invoke the :term:`view callable`. See :ref:`view_security_section` for more information about view security and permissions. - + If ``permission`` is not supplied, no permission is registered for this view (it's accessible by any caller). @@ -183,7 +183,7 @@ Non-Predicate Arguments argument. The view callable it is passed will accept ``(context, request)``. The decorator must return a replacement view callable which also accepts ``(context, request)``. - + ``mapper`` A Python object or :term:`dotted Python name` which refers to a :term:`view mapper`, or ``None``. By default it is ``None``, which indicates that the @@ -228,7 +228,7 @@ configured view. ``pattern``, representing a part of the path that will be used by :term:`traversal` against the result of the route's :term:`root factory`. - If ``route_name`` is not supplied, the view callable will be have a chance + If ``route_name`` is not supplied, the view callable will only have a chance of being invoked if no other route was matched. This is when the request/context pair found via :term:`resource location` does not indicate it matched any configured route. @@ -400,7 +400,7 @@ configuration stanza: .. code-block:: python :linenos: - config.add_view('mypackage.views.my_view', name='my_view', request_method='POST', + config.add_view('mypackage.views.my_view', name='my_view', request_method='POST', context=MyResource, permission='read') All arguments to ``view_config`` may be omitted. For example: @@ -517,7 +517,7 @@ registration. For example: This registers the same view under two different names. -The decorator can also be used against class methods: +The decorator can also be used against a method of a class: .. code-block:: python :linenos: @@ -533,9 +533,9 @@ The decorator can also be used against class methods: def amethod(self): return Response('hello') -When the decorator is used against a class method, a view is registered for -the *class*, so the class constructor must accept an argument list in one of -two forms: either it must accept a single argument ``request`` or it must +When the decorator is used against a method of a class, a view is registered +for the *class*, so the class constructor must accept an argument list in one +of two forms: either it must accept a single argument ``request`` or it must accept two arguments, ``context, request``. The method which is decorated must return a :term:`response`. @@ -760,7 +760,7 @@ Here is an example for a simple view configuration using :term:`traversal`: URL = /FrontPage context: <tutorial.models.Page object at 0xa12536c> - view name: + view name: View: ----- @@ -791,7 +791,7 @@ A more complex configuration might generate something like this: route name: about route pattern: /about route path: /about - subpath: + subpath: route predicates (request method = GET) View: @@ -805,7 +805,7 @@ A more complex configuration might generate something like this: route name: about_post route pattern: /about route path: /about - subpath: + subpath: route predicates (request method = POST) View: diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst index 19c52d0c9..a99fd8b24 100644 --- a/docs/narr/zca.rst +++ b/docs/narr/zca.rst @@ -38,10 +38,10 @@ code is high. While the ZCA is an excellent tool with which to build a *framework* such as :app:`Pyramid`, it is not always the best tool with which to build an *application* due to the opacity of the ``zope.component`` -APIs. Accordingly, :app:`Pyramid` tends to hide the the presence -of the ZCA from application developers. You needn't understand the -ZCA to create a :app:`Pyramid` application; its use is effectively -only a framework implementation detail. +APIs. Accordingly, :app:`Pyramid` tends to hide the presence of the +ZCA from application developers. You needn't understand the ZCA to +create a :app:`Pyramid` application; its use is effectively only a +framework implementation detail. However, developers who are already used to writing :term:`Zope` applications often still wish to use the ZCA while building a |