From 70acd25f40f32fc6cbb3b5d38a695b8982b52a31 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:06:55 -0500 Subject: module name contractions --- docs/narr/advconfig.rst | 18 ++++++------ docs/narr/assets.rst | 56 ++++++++++++++++++------------------- docs/narr/configuration.rst | 4 +-- docs/narr/events.rst | 9 +++--- docs/narr/extending.rst | 19 ++++++------- docs/narr/firstapp.rst | 2 +- docs/narr/hooks.rst | 28 +++++++++---------- docs/narr/hybrid.rst | 18 ++++++------ docs/narr/i18n.rst | 45 +++++++++++++++-------------- docs/narr/muchadoabouttraversal.rst | 3 +- docs/narr/renderers.rst | 13 ++++----- docs/narr/resources.rst | 26 ++++++++--------- docs/narr/router.rst | 24 ++++++++-------- docs/narr/security.rst | 18 ++++++------ docs/narr/sessions.rst | 2 +- docs/narr/startup.rst | 10 +++---- docs/narr/templates.rst | 18 ++++++------ docs/narr/testing.rst | 24 ++++++++-------- docs/narr/threadlocals.rst | 18 ++++++------ docs/narr/traversal.rst | 2 +- docs/narr/viewconfig.rst | 24 ++++++++-------- docs/narr/views.rst | 22 +++++++-------- docs/narr/zca.rst | 4 +-- 23 files changed, 198 insertions(+), 209 deletions(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 20316dc77..099bce35f 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -163,7 +163,7 @@ Using ``config.commit()`` +++++++++++++++++++++++++ You can manually commit a configuration by using the -:meth:`pyramid.config.Configurator.commit` method between configuration +:meth:`~pyramid.config.Configurator.commit` method between configuration calls. For example, we prevent conflicts from occurring in the application we examined previously as the result of adding a ``commit``. Here's the application that generates conflicts: @@ -255,7 +255,7 @@ conflict detection (and :ref:`twophase_config`) is disabled. Configuration statements will be executed immediately, and succeeding statements will override preceding ones. -:meth:`pyramid.config.Configurator.commit` has no effect when ``autocommit`` +:meth:`~pyramid.config.Configurator.commit` has no effect when ``autocommit`` is ``True``. If you use a Configurator in code that performs unit testing, it's usually a @@ -267,7 +267,7 @@ unconcerned about conflict detection or two-phase configuration in test code. Automatic Conflict Resolution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your code uses the :meth:`pyramid.config.Configurator.include` method to +If your code uses the :meth:`~pyramid.config.Configurator.include` method to include external configuration, some conflicts are automatically resolved. Configuration statements that are made as the result of an "include" will be overridden by configuration statements that happen within the caller of @@ -332,7 +332,7 @@ Instead, use :meth:`pyramid.config.Configuration.include`: Using ``include`` rather than calling the function directly will allow :ref:`automatic_conflict_resolution` to work. -:meth:`pyramid.config.Configuration.include` can also accept a :term:`module` +:meth:`~pyramid.config.Configuration.include` can also accept a :term:`module` as an argument: .. code-block:: python @@ -346,11 +346,11 @@ For this to work properly, the ``myapp`` module must contain a callable with the special name ``includeme``, which should perform configuration (like the ``add_routes`` callable we showed above as an example). -:meth:`pyramid.config.Configuration.include` can also accept a :term:`dotted +:meth:`~pyramid.config.Configuration.include` can also accept a :term:`dotted Python name` to a function or a module. .. note: See :ref:`the_include_tag` for a declarative alternative to - :meth:`pyramid.config.Configurator.include`. + the :meth:`~pyramid.config.Configurator.include` method. .. _twophase_config: @@ -368,8 +368,8 @@ to do conflict detection. Due to this, for configuration methods that have no internal ordering constraints, execution order of configuration method calls is not important. For example, the relative ordering of -:meth:`pyramid.config.Configurator.add_view` and -:meth:`pyramid.config.Configurator.add_renderer` is unimportant when a +:meth:`~pyramid.config.Configurator.add_view` and +:meth:`~pyramid.config.Configurator.add_renderer` is unimportant when a non-autocommitting configurator is used. This code snippet: .. code-block:: python @@ -398,7 +398,7 @@ used, two-phase configuration is disabled, and configuration statements must be ordered in dependency order. Some configuration methods, such as -:meth:`pyramid.config.Configurator.add_route` have internal ordering +:meth:`~pyramid.config.Configurator.add_route` have internal ordering constraints: the routes they imply require relative ordering. Such ordering constraints are not absolved by two-phase configuration. Routes are still added in configuration execution order. diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index ee2e0440e..a9dc1f129 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -142,7 +142,7 @@ see :ref:`advanced_static`. Here's another example that uses an :term:`asset specification` instead of an absolute path as the ``path`` argument. To convince -:meth:`pyramid.config.Configurator.add_static_view` to serve files up under +:meth:`~pyramid.config.Configurator.add_static_view` to serve files up under the ``/static`` URL from the ``a/b/c/static`` directory of the Python package named ``some_package``, we can use a fully qualified :term:`asset specification` as the ``path``: @@ -153,17 +153,17 @@ specification` as the ``path``: # config is an instance of pyramid.config.Configurator config.add_static_view(name='static', path='some_package:a/b/c/static') -The ``path`` provided to :meth:`pyramid.config.Configurator.add_static_view` +The ``path`` provided to :meth:`~pyramid.config.Configurator.add_static_view` may be a fully qualified :term:`asset specification` or an *absolute path*. Instead of representing a URL prefix, the ``name`` argument of a call to -:meth:`pyramid.config.Configurator.add_static_view` can alternately be a +:meth:`~pyramid.config.Configurator.add_static_view` can alternately be a *URL*. Each of examples we've seen so far have shown usage of the ``name`` argument as a URL prefix. However, when ``name`` is a *URL*, static assets can be served from an external webserver. In this mode, the ``name`` is used as the URL prefix when generating a URL using :func:`pyramid.url.static_url`. -For example, :meth:`pyramid.config.Configurator.add_static_view` may +For example, :meth:`~pyramid.config.Configurator.add_static_view` may be fed a ``name`` argument which is ``http://example.com/images``: .. code-block:: python @@ -173,20 +173,20 @@ be fed a ``name`` argument which is ``http://example.com/images``: config.add_static_view(name='http://example.com/images', path='mypackage:images') -Because :meth:`pyramid.config.Configurator.add_static_view` is provided with +Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with a ``name`` argument that is the URL ``http://example.com/images``, subsequent -calls to :func:`pyramid.url.static_url` with paths that start with the +calls to :func:`~pyramid.url.static_url` with paths that start with the ``path`` argument passed to -:meth:`pyramid.config.Configurator.add_static_view` will generate a URL +:meth:`~pyramid.config.Configurator.add_static_view` will generate a URL something like ``http://example.com/images/logo.png``. The external webserver listening on ``example.com`` must be itself configured to respond -properly to such a request. The :func:`pyramid.url.static_url` API is +properly to such a request. The :func:`~pyramid.url.static_url` API is discussed in more detail later in this chapter. .. note:: The :ref:`static_directive` ZCML directive offers an declarative - equivalent to :meth:`pyramid.config.Configurator.add_static_view`. Use of + equivalent to :meth:`~pyramid.config.Configurator.add_static_view`. Use of the :ref:`static_directive` ZCML directive is completely equivalent to using imperative configuration for the same purpose. @@ -199,7 +199,7 @@ discussed in more detail later in this chapter. Generating Static Asset URLs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a :meth:`pyramid.config.Configurator.add_static_view` method is used to +When a :meth:`~pyramid.config.Configurator.add_static_view` method is used to register a static asset directory, a special helper API named :func:`pyramid.url.static_url` can be used to generate the appropriate URL for an asset that lives in one of the directories named by the static @@ -221,7 +221,7 @@ visits a URL which begins with ``/static1``, and the assets in the visits a URL which begins with ``/static2``. You needn't generate the URLs to static assets "by hand" in such a -configuration. Instead, use the :func:`pyramid.url.static_url` API to +configuration. Instead, use the :func:`~pyramid.url.static_url` API to generate them for you. For example: .. code-block:: python @@ -242,15 +242,15 @@ If the request "application URL" of the running system is ``http://example.com/static1/foo.css``. The ``js_url`` generated above would be ``http://example.com/static2/foo.js``. -One benefit of using the :func:`pyramid.url.static_url` function rather than +One benefit of using the :func:`~pyramid.url.static_url` function rather than constructing static URLs "by hand" is that if you need to change the ``name`` of a static URL declaration, the generated URLs will continue to resolve properly after the rename. -URLs may also be generated by :func:`pyramid.url.static_url` to static assets +URLs may also be generated by :func:`~pyramid.url.static_url` to static assets that live *outside* the :app:`Pyramid` application. This will happen when -the :meth:`pyramid.config.Configurator.add_static_view` API associated with -the path fed to :func:`pyramid.url.static_url` is a *URL* instead of a view +the :meth:`~pyramid.config.Configurator.add_static_view` API associated with +the path fed to :func:`~pyramid.url.static_url` is a *URL* instead of a view name. For example, the ``name`` argument may be ``http://example.com`` while the the ``path`` given may be ``mypackage:images``: @@ -270,13 +270,13 @@ assets which begin with ``mypackage:images`` will be prefixed with static_url('mypackage:images/logo.png', request) # -> http://example.com/images/logo.png -Using :func:`pyramid.url.static_url` in conjunction with a -:meth:`pyramid.configuration.Configurator.add_static_view` makes it possible +Using :func:`~pyramid.url.static_url` in conjunction with a +:meth:`~pyramid.configuration.Configurator.add_static_view` makes it possible to put static media on a separate webserver during production (if the -``name`` argument to :meth:`pyramid.config.Configurator.add_static_view` is a +``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is a URL), while keeping static media package-internal and served by the development webserver during development (if the ``name`` argument to -:meth:`pyramid.config.Configurator.add_static_view` is a URL prefix). To +:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix). To create such a circumstance, we suggest using the :attr:`pyramid.registry.Registry.settings` API in conjunction with a setting in the application ``.ini`` file named ``media_location``. Then set the @@ -300,7 +300,7 @@ dispatch`, you may want static assets to only be available as a fallback if no previous route matches. Alternately, you might like to serve a particular static asset manually, because its download requires authentication. -Note that you cannot use the :func:`pyramid.url.static_url` API to generate +Note that you cannot use the :func:`~pyramid.url.static_url` API to generate URLs against assets made accessible by registering a custom static view. Root-Relative Custom Static View (URL Dispatch Only) @@ -309,7 +309,7 @@ Root-Relative Custom Static View (URL Dispatch Only) The :class:`pyramid.view.static` helper class generates a Pyramid view callable. This view callable can serve static assets from a directory. An instance of this class is actually used by the -:meth:`pyramid.config.Configurator.add_static_view` configuration method, so +:meth:`~pyramid.config.Configurator.add_static_view` configuration method, so its behavior is almost exactly the same once it's configured. .. warning:: The following example *will not work* for applications that use @@ -317,13 +317,13 @@ its behavior is almost exactly the same once it's configured. exclusively. The root-relative route we'll be registering will always be matched before traversal takes place, subverting any views registered via ``add_view`` (at least those without a ``route_name``). A - :class:`pyramid.view.static` static view cannot be made root-relative when + :class:`~pyramid.view.static` static view cannot be made root-relative when you use traversal. To serve files within a directory located on your filesystem at ``/path/to/static/dir`` as the result of a "catchall" route hanging from the root that exists at the end of your routing table, create an instance of the -:class:`pyramid.view.static` class inside a ``static.py`` file in your +:class:`~pyramid.view.static` class inside a ``static.py`` file in your application root as below. .. ignore-next-block @@ -334,7 +334,7 @@ application root as below. static_view = static('/path/to/static/dir') .. note:: For better cross-system flexibility, use an :term:`asset - specification` as the argument to :class:`pyramid.view.static` instead of + specification` as the argument to :class:`~pyramid.view.static` instead of a physical absolute filesystem path, e.g. ``mypackage:static`` instead of ``/path/to/mypackage/static``. @@ -351,7 +351,7 @@ application's startup code. config.add_route('catchall_static', '/*subpath', 'myapp.static.static_view') The special name ``*subpath`` above is used by the -:class:`pyramid.view.static` view callable to signify the path of the file +:class:`~pyramid.view.static` view callable to signify the path of the file relative to the directory you're serving. Registering A View Callable to Serve a "Static" Asset @@ -440,7 +440,7 @@ feature, a :term:`Configurator` API exists named setuptools :term:`pkg_resources` API. .. note:: The :term:`ZCML` directive named ``asset`` serves the same purpose - as the :meth:`pyramid.config.Configurator.override_asset` method. + as the :meth:`~pyramid.config.Configurator.override_asset` method. .. index:: single: override_asset @@ -450,7 +450,7 @@ feature, a :term:`Configurator` API exists named The ``override_asset`` API ~~~~~~~~~~~~~~~~~~~~~~~~~~ -An individual call to :meth:`pyramid.config.Configurator.override_asset` +An individual call to :meth:`~pyramid.config.Configurator.override_asset` can override a single asset. For example: .. ignore-next-block @@ -503,7 +503,7 @@ if you want to override assets for both ``some.package:templates``, and The package name in a specification may start with a dot, meaning that the package is relative to the package in which the configuration construction file resides (or the ``package`` argument to the -:class:`pyramid.config.Configurator` class construction). +:class:`~pyramid.config.Configurator` class construction). For example: .. ignore-next-block diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 05bc4d6cc..6360dc574 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -127,7 +127,7 @@ The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects defined within a module. These special attributes are typically attached to code via the use of a :term:`decorator`. For example, the -:class:`pyramid.view.view_config` decorator can be attached to a function or +:class:`~pyramid.view.view_config` decorator can be attached to a function or instance method. Once scanning is invoked, and :term:`configuration decoration` is found by @@ -136,7 +136,7 @@ behalf: these calls replace the need to add imperative configuration statements that don't live near the code being configured. In the example above, the scanner translates the arguments to -:class:`pyramid.view.view_config` into a call to the +:class:`~pyramid.view.view_config` into a call to the :meth:`pyramid.config.Configurator.add_view` method, effectively: .. ignore-next-block diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 224eeca16..929208083 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -43,7 +43,7 @@ Configuring an Event Listener Imperatively You can imperatively configure a subscriber function to be called for some event type via the -:meth:`pyramid.config.Configurator.add_subscriber` +:meth:`~pyramid.config.Configurator.add_subscriber` method (see also :term:`Configurator`): .. code-block:: python @@ -59,7 +59,7 @@ method (see also :term:`Configurator`): config.add_subscriber(mysubscriber, NewRequest) The first argument to -:meth:`pyramid.config.Configurator.add_subscriber` is the +:meth:`~pyramid.config.Configurator.add_subscriber` is the subscriber function (or a :term:`dotted Python name` which refers to a subscriber callable); the second argument is the event type. @@ -79,10 +79,9 @@ type via the :func:`pyramid.events.subscriber` function. def mysubscriber(event): event.request.foo = 1 -When the :func:`pyramid.subscriber` decorator is used a +When the :func:`~pyramid.events.subscriber` decorator is used a :term:`scan` must be performed against the package containing the -decorated function for the decorator to have any effect. See -:func:`pyramid.subscriber` for more information. +decorated function for the decorator to have any effect. Either of the above registration examples implies that every time the :app:`Pyramid` framework emits an event object that supplies an diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index c709e1f8f..416207584 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -115,15 +115,14 @@ Fundamental Plugpoints The fundamental "plug points" of an application developed using :app:`Pyramid` are *routes*, *views*, and *assets*. Routes are declarations -made using the :meth:`pyramid.config.Configurator.add_route` method (or the -ZCML ```` directive). Views are declarations made using the -:meth:`pyramid.config.Configurator.add_view` method (or the ZCML ```` -directive). 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, ``add_handler`` directive of -the ``pyramid_handlers`` package adds a single route, and some number of -views. +made using the :meth:`pyramid.config.Configurator.add_route` method. Views +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, +``add_handler`` directive of the ``pyramid_handlers`` package adds a single +route, and some number of views. .. index:: single: extending an existing application @@ -270,7 +269,7 @@ Overriding Routes ~~~~~~~~~~~~~~~~~ Route setup is currently typically performed in a sequence of ordered calls -to :meth:`pyramid.config.Configurator.add_route`. Because these calls are +to :meth:`~pyramid.config.Configurator.add_route`. Because these calls are ordered relative to each other, and because this ordering is typically important, you should retain their relative ordering when performing an override. Typically, this means *copying* all the ``add_route`` statements diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 822e3cb32..ea7134a3e 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -122,7 +122,7 @@ A view callable is required to return a :term:`response` object because a response object has all the information necessary to formulate an actual HTTP response; this object is then converted to text by the upstream :term:`WSGI` server and sent back to the requesting browser. To return a response, each -view callable creates an instance of the :class:`pyramid.response.Response` +view callable creates an instance of the :class:`~pyramid.response.Response` class. In the ``hello_world`` function, the string ``'Hello world!'`` is passed to the ``Response`` constructor as the *body* of the response. In the ``goodbye_world`` function, the string ``'Goodbye world!'`` is passed. diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b3b41046f..d2eaf8215 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -42,7 +42,7 @@ Like any other view, the notfound view must accept at least a ``request`` parameter, or both ``context`` and ``request``. The ``request`` is the current :term:`request` representing the denied action. The ``context`` (if used in the call signature) will be the instance of the -:exc:`pyramid.exceptions.NotFound` exception that caused the view to be +:exc:`~pyramid.exceptions.NotFound` exception that caused the view to be called. Here's some sample code that implements a minimal NotFound view callable: @@ -57,7 +57,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. note:: When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`pyramid.exceptions.NotFound` + be an instance of the :exc:`~pyramid.exceptions.NotFound` exception that caused the not found view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the not found error was raised. This message will be different when @@ -67,7 +67,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. warning:: When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the - :exc:`pyramid.exceptions.NotFound` exception instance. If available, the + :exc:`~pyramid.exceptions.NotFound` exception instance. If available, the resource context will still be available as ``request.context``. .. index:: @@ -122,7 +122,7 @@ Here's some sample code that implements a minimal forbidden view: .. note:: When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`pyramid.exceptions.Forbidden` + be an instance of the :exc:`~pyramid.exceptions.Forbidden` exception that caused the forbidden view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the forbidden was raised. This message will be different when the @@ -253,7 +253,7 @@ that can be used for this purpose. For example: An object of this type is sent as an event just before a :term:`renderer` is invoked (but *after* the application-level renderer globals factory added via -:class:`pyramid.config.Configurator.set_renderer_globals_factory`, if any, +:class:`~pyramid.config.Configurator.set_renderer_globals_factory`, if any, has injected its own keys into the renderer globals dictionary). If a subscriber attempts to add a key that already exist in the renderer @@ -263,7 +263,7 @@ keys added to the renderer globals dictionary by all :class:`pyramid.events.BeforeRender` subscribers and renderer globals factories must be unique. -See the API documentation for the :class:`pyramid.events.BeforeRender` event +See the API documentation for the :class:`~pyramid.events.BeforeRender` event interface at :class:`pyramid.interfaces.IBeforeRender`. Another mechanism which allows event subscribers more control when adding @@ -307,14 +307,14 @@ callback will be an exception object instead of its default value of Response callbacks are called in the order they're added (first-to-most-recently-added). All response callbacks are called *after* -the :class:`pyramid.events.NewResponse` event is sent. Errors raised by +the :class:`~pyramid.events.NewResponse` event is sent. Errors raised by response callbacks are not handled specially. They will be propagated to the caller of the :app:`Pyramid` router application. A response callback has a lifetime of a *single* request. If you want a response callback to happen as the result of *every* request, you must re-register the callback into every new request (perhaps within a subscriber -of a :class:`pyramid.events.NewRequest` event). +of a :class:`~pyramid.events.NewRequest` event). .. index:: single: finished callback @@ -377,7 +377,7 @@ application. A finished callback has a lifetime of a *single* request. If you want a finished callback to happen as the result of *every* request, you must re-register the callback into every new request (perhaps within a subscriber -of a :class:`pyramid.events.NewRequest` event). +of a :class:`~pyramid.events.NewRequest` event). .. index:: single: traverser @@ -472,7 +472,7 @@ However, since the way traversal is done will have been modified, the URLs it generates by default may be incorrect. If you've added a traverser, you can change how -:func:`pyramid.url.resource_url` generates a URL for a specific type of +:func:`~pyramid.url.resource_url` generates a URL for a specific type of resource by adding a registerAdapter call for :class:`pyramid.interfaces.IContextURL` to your application: @@ -488,7 +488,7 @@ resource by adding a registerAdapter call for IContextURL) In the above example, the ``myapp.traversal.URLGenerator`` class will be used -to provide services to :func:`pyramid.url.resource_url` any time the +to provide services to :func:`~pyramid.url.resource_url` any time the :term:`context` passed to ``resource_url`` is of class ``myapp.resources.MyRoot``. The second argument in the ``(MyRoot, Interface)`` tuple represents the type of interface that must be possessed by @@ -496,7 +496,7 @@ the :term:`request` (in this case, any interface, represented by ``zope.interface.Interface``). The API that must be implemented by a class that provides -:class:`pyramid.interfaces.IContextURL` is as follows: +:class:`~pyramid.interfaces.IContextURL` is as follows: .. code-block:: python :linenos: @@ -611,7 +611,7 @@ to set a *default* view mapper (overriding the superdefault view mapper used by Pyramid itself). A *single* view registration can use a view mapper by passing the mapper as -the ``mapper`` argument to :meth:`pyramid.config.Configuration.add_view`. +the ``mapper`` argument to :meth:`~pyramid.config.Configuration.add_view`. .. index:: single: configuration decorator @@ -621,7 +621,7 @@ the ``mapper`` argument to :meth:`pyramid.config.Configuration.add_view`. Registering Configuration Decorators ------------------------------------ -Decorators such as :class:`pyramid.view.view_config` don't change the +Decorators such as :class:`~pyramid.view.view_config` don't change the behavior of the functions or classes they're decorating. Instead, when a :term:`scan` is performed, a modified version of the function or class is registered with :app:`Pyramid`. diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 181ae1285..780cb0975 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -156,12 +156,12 @@ match is straightforward. When a route is matched: - If the route's configuration does not have a ``factory`` argument, the *global* :term:`root factory` will be called to generate a :term:`root` object. The global root factory is the - callable implied by the ``root_factory`` argument passed to - :class:`pyramid.config.Configurator` at application + callable implied by the ``root_factory`` argument passed to the + :class:`~pyramid.config.Configurator` at application startup time. - If a ``root_factory`` argument is not provided to the - :class:`pyramid.config.Configurator` at startup time, a + :class:`~pyramid.config.Configurator` at startup time, a *default* root factory is used. The default root factory is used to generate a root object. @@ -260,7 +260,7 @@ route statement is a reasonable thing to do. We could have also used our ``root_factory`` callable as the ``root_factory`` argument of the - :class:`pyramid.config.Configurator` constructor, instead + :class:`~pyramid.config.Configurator` constructor, instead of associating it with a particular route inside the route's configuration. Every hybrid route configuration that is matched but which does *not* name a ``factory`` attribute will use the use @@ -300,13 +300,13 @@ invoked after a route matches: config.add_view('mypackage.views.myview', route_name='home') Note that the above call to -:meth:`pyramid.config.Configurator.add_view` includes a ``route_name`` +:meth:`~pyramid.config.Configurator.add_view` includes a ``route_name`` argument. View configurations that include a ``route_name`` argument are meant to associate a particular view declaration with a route, using the route's name, in order to indicate that the view should *only be invoked when the route matches*. -Calls to :meth:`pyramid.config.Configurator.add_view` may pass a +Calls to :meth:`~pyramid.config.Configurator.add_view` may pass a ``route_name`` attribute, which refers to the value of an existing route's ``name`` argument. In the above example, the route name is ``home``, referring to the name of the route defined above it. @@ -357,7 +357,7 @@ Using the ``traverse`` Argument In a Route Definition Rather than using the ``*traverse`` remainder marker in a pattern, you can use the ``traverse`` argument to the -:meth:`pyramid.config.Configurator.add_route` method. +:meth:`~pyramid.config.Configurator.add_route` method. When you use the ``*traverse`` remainder marker, the traversal path is limited to being the remainder segments of a request URL when a route @@ -365,7 +365,7 @@ matches. However, when you use the ``traverse`` argument or attribute, you have more control over how to compose a traversal path. Here's a use of the ``traverse`` pattern in a call to -:meth:`pyramid.config.Configurator.add_route`: +:meth:`~pyramid.config.Configurator.add_route`: .. code-block:: python :linenos: @@ -472,7 +472,7 @@ startup time. config.add_view('myproject.views.another', route_name='home') This is because the ``view`` argument to the -:meth:`pyramid.config.Configurator.add_route` above is an *implicit* +:meth:`~pyramid.config.Configurator.add_route` above is an *implicit* default view when that route matches. ``add_route`` calls don't *need* to supply a view attribute. For example, this ``add_route`` call: diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 7bfd29631..9a43e8772 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -59,7 +59,7 @@ This creates a Unicode-like object that is a TranslationString. :term:`Django` i18n, using a TranslationString is a lot like using "lazy" versions of related gettext APIs. -The first argument to :class:`pyramid.i18n.TranslationString` is +The first argument to :class:`~pyramid.i18n.TranslationString` is the ``msgid``; it is required. It represents the key into the translation mappings provided by a particular localization. The ``msgid`` argument must be a Unicode object or an ASCII string. The @@ -139,7 +139,7 @@ Using the ``TranslationStringFactory`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to generate a translation string is to use the -:attr:`pyramid.i18n.TranslationStringFactory` object. This object +:attr:`~pyramid.i18n.TranslationStringFactory` object. This object is a *translation string factory*. Basically a translation string factory presets the ``domain`` value of any :term:`translation string` generated by using it. For example: @@ -156,11 +156,11 @@ generated by using it. For example: file generation tools. After assigning ``_`` to the result of a -:func:`pyramid.i18n.TranslationStringFactory`, the subsequent result -of calling ``_`` will be a :class:`pyramid.i18n.TranslationString` +:func:`~pyramid.i18n.TranslationStringFactory`, the subsequent result +of calling ``_`` will be a :class:`~pyramid.i18n.TranslationString` instance. Even though a ``domain`` value was not passed to ``_`` (as would have been necessary if the -:class:`pyramid.i18n.TranslationString` constructor were used instead +:class:`~pyramid.i18n.TranslationString` constructor were used instead of a translation string factory), the ``domain`` attribute of the resulting translation string will be ``pyramid``. As a result, the previous code example is completely equivalent (except for spelling) @@ -175,7 +175,7 @@ to: You can set up your own translation string factory much like the one provided above by using the -:class:`pyramid.i18n.TranslationStringFactory` class. For example, +:class:`~pyramid.i18n.TranslationStringFactory` class. For example, if you'd like to create a translation string factory which presets the ``domain`` value of generated translation strings to ``form``, you'd do something like this: @@ -491,13 +491,12 @@ translations will be available to :app:`Pyramid`. Using a Localizer ----------------- -A :term:`localizer` is an object that allows you to perform -translation or pluralization "by hand" in an application. You may use -the :func:`pyramid.i18n.get_localizer` function to obtain a -:term:`localizer`. :func:`pyramid.i18n.get_localizer`. This -function will return either the localizer object implied by the active -:term:`locale negotiator` or a default localizer object if no explicit -locale negotiator is registered. +A :term:`localizer` is an object that allows you to perform translation or +pluralization "by hand" in an application. You may use the +:func:`pyramid.i18n.get_localizer` function to obtain a :term:`localizer`. +This function will return either the localizer object implied by the active +:term:`locale negotiator` or a default localizer object if no explicit locale +negotiator is registered. .. code-block:: python :linenos: @@ -534,7 +533,7 @@ translation in a view component of an application might look like so: translated = localizer.translate(ts) # translation string # ... use translated ... -The :func:`pyramid.i18n.get_localizer` function will return a +The :func:`~pyramid.i18n.get_localizer` function will return a :class:`pyramid.i18n.Localizer` object bound to the locale name represented by the request. The translation returned from its :meth:`pyramid.i18n.Localizer.translate` method will depend on the @@ -612,9 +611,9 @@ locale negotiator returns ``None``. You can change the default locale name by changing the ``default_locale_name`` setting; see :ref:`default_locale_name_setting`. -Once :func:`pyramid.i18n.get_locale_name` is first run, the locale +Once :func:`~pyramid.i18n.get_locale_name` is first run, the locale name is stored on the request object. Subsequent calls to -:func:`pyramid.i18n.get_locale_name` will return the stored locale +:func:`~pyramid.i18n.get_locale_name` will return the stored locale name without invoking the :term:`locale negotiator`. To avoid this caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: @@ -641,7 +640,7 @@ You can also obtain the locale name related to a request using the Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by calling the -:func:`pyramid.i18n.get_locale_name` function. +:func:`~pyramid.i18n.get_locale_name` function. .. index:: single: date and currency formatting (i18n) @@ -753,7 +752,7 @@ Localization-Related Deployment Settings A :app:`Pyramid` application will have a ``default_locale_name`` setting. This value represents the :term:`default locale name` used when the :term:`locale negotiator` returns ``None``. Pass it to the -:mod:`pyramid.config.Configurator` constructor at startup +:mod:`~pyramid.config.Configurator` constructor at startup time: .. code-block:: python @@ -891,7 +890,7 @@ application startup. For example: 'another.application:locale/') A message catalog in a translation directory added via -:meth:`pyramid.config.Configurator.add_translation_dirs` +:meth:`~pyramid.config.Configurator.add_translation_dirs` will be merged into translations from a message catalog added earlier if both translation directories contain translations for the same locale and :term:`translation domain`. @@ -937,8 +936,8 @@ a particular request. A locale negotiator is a bit of code which accepts a request and which returns a :term:`locale name`. It is consulted when :meth:`pyramid.i18n.Localizer.translate` or :meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also -consulted when :func:`pyramid.i18n.get_locale_name` or -:func:`pyramid.i18n.negotiate_locale_name` is invoked. +consulted when :func:`~pyramid.i18n.get_locale_name` or +:func:`~pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: @@ -949,7 +948,7 @@ Most applications can make use of the default locale negotiator, which requires no additional coding or configuration. The default locale negotiator implementation named -:class:`pyramid.i18n.default_locale_negotiator` uses the following +:class:`~pyramid.i18n.default_locale_negotiator` uses the following set of steps to dermine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the @@ -1000,7 +999,7 @@ You may add your newly created locale negotiator to your application's configuration by passing an object which can act as the negotiator (or a :term:`dotted Python name` referring to the object) as the ``locale_negotiator`` argument of the -:class:`pyramid.config.Configurator` instance during application +:class:`~pyramid.config.Configurator` instance during application startup. For example: .. code-block:: python diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 2dbfba779..6aef2fd6b 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -305,7 +305,6 @@ don't require it, great: stick with :term:`URL dispatch`. But if you're using :app:`Pyramid` and you ever find that you *do* need to support one of these use cases, you'll be glad you have traversal in your toolkit. -.. note:: - It is even possible to mix and match :term:`traversal` with +.. note:: It is even possible to mix and match :term:`traversal` with :term:`URL dispatch` in the same :app:`Pyramid` application. See the :ref:`hybrid_chapter` chapter for details. diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index a80c5a9c2..792c64fcb 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -23,7 +23,7 @@ dictionary does not implement the Pyramid response interface, so you might believe that this example would fail. However, since a ``renderer`` is associated with the view callable through its :term:`view configuration` (in this case, using a ``renderer`` argument passed to -:func:`pyramid.view.view_config`), if the view does *not* return a Response +:func:`~pyramid.view.view_config`), if the view does *not* return a Response object, the renderer will attempt to convert the result of the view to a response on the developer's behalf. @@ -60,7 +60,7 @@ object serialization techniques. View configuration can vary the renderer associated with a view callable via the ``renderer`` attribute. For example, this call to -:meth:`pyramid.config.Configurator.add_view` associates the ``json`` renderer +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer with a view callable: .. code-block:: python @@ -187,7 +187,7 @@ values serializable by :func:`json.dumps`. You can configure a view to use the JSON renderer by naming ``json`` as the ``renderer`` argument of a view configuration, e.g. by using -:meth:`pyramid.config.Configurator.add_view`: +:meth:`~pyramid.config.Configurator.add_view`: .. code-block:: python :linenos: @@ -472,7 +472,7 @@ There are essentially two different kinds of renderer factories: :term:`package`. Here's an example of the registration of a simple renderer factory via -:meth:`pyramid.config.Configurator.add_renderer`: +:meth:`~pyramid.config.Configurator.add_renderer`: .. code-block:: python :linenos: @@ -539,9 +539,6 @@ ending with ``.jinja2`` in its ``renderer`` value. The ``name`` passed to the ``Jinja2Renderer`` constructor will be the full value that was set as ``renderer=`` in the view configuration. -See also :ref:`renderer_directive` and -:meth:`pyramid.config.Configurator.add_renderer`. - Changing an Existing Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -595,7 +592,7 @@ user instructing the view to use a template renderer with one that uses an XML-RPC renderer. This renderer would produce an XML-RPC representation of the data returned by an arbitrary view callable. -To use this feature, create a :class:`pyramid.events.NewRequest` +To use this feature, create a :class:`~pyramid.events.NewRequest` :term:`subscriber` which sniffs at the request data and which conditionally sets an ``override_renderer`` attribute on the request itself, which is the *name* of a registered renderer. For example: diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 895d6c1c6..4fc7e037e 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -36,8 +36,8 @@ application. Also: - The ``context`` and ``containment`` predicate arguments to - :meth:`pyramid.config.Configurator.add_view` (or a - :func:`pyramid.view.view_config` decorator) reference a resource class + :meth:`~pyramid.config.Configurator.add_view` (or a + :func:`~pyramid.view.view_config` decorator) reference a resource class or resource :term:`interface`. - A :term:`root factory` returns a resource. @@ -46,7 +46,7 @@ Also: view. - Various helpful :app:`Pyramid` API methods expect a resource as an - argument (e.g. :func:`pyramid.url.resource_url` and others). + argument (e.g. :func:`~pyramid.url.resource_url` and others). .. index:: single: resource tree @@ -162,9 +162,9 @@ you will reach the filesystem root directory. .. warning:: If your root resource has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the - :func:`pyramid.url.resource_url` function and paths generated by - the :func:`pyramid.traversal.resource_path` and - :func:`pyramid.traversal.resource_path_tuple` APIs will be + :func:`~pyramid.url.resource_url` function and paths generated by + the :func:`~pyramid.traversal.resource_path` and + :func:`~pyramid.traversal.resource_path_tuple` APIs will be generated improperly. The value of ``__name__`` will be prepended to every path and URL generated (as opposed to a single leading slash or empty tuple element). @@ -281,7 +281,7 @@ about virtually rooting a resource. The shortcut method of the :term:`request` named :meth:`pyramid.request.Request.resource_url` can be used instead of -:func:`pyramid.url.resource_url` to generate a resource URL. +:func:`~pyramid.url.resource_url` to generate a resource URL. For more information about generating resource URLs, see the documentation for :func:`pyramid.url.resource_url`. @@ -292,13 +292,13 @@ Overriding Resource URL Generation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a resource object implements a ``__resource_url__`` method, this method -will be called when :func:`pyramid.url.resource_url` is called to generate a +will be called when :func:`~pyramid.url.resource_url` is called to generate a URL for the resource, overriding the default URL returned for the resource by :func:`~pyramid.url.resource_url`. The ``__resource_url__`` hook is passed two arguments: ``request`` and ``info``. ``request`` is the :term:`request` object passed to -:func:`pyramid.url.resource_url`. ``info`` is a dictionary with two +:func:`~pyramid.url.resource_url`. ``info`` is a dictionary with two keys: ``physical_path`` @@ -331,7 +331,7 @@ or port number of the generated URL. Note that the URL generated by ``__resource_url__`` should be fully qualified, should end in a slash, and should not contain any query string or anchor elements (only path elements) to work best with -:func:`pyramid.url.resource_url`. +:func:`~pyramid.url.resource_url`. Generating the Path To a Resource --------------------------------- @@ -350,7 +350,7 @@ character. If ``resource`` in the example above was accessible in the tree as ``root['a']['b']``, the above example would generate the string ``/a/b``. -Any positional arguments passed in to :func:`pyramid.traversal.resource_path` +Any positional arguments passed in to :func:`~pyramid.traversal.resource_path` will be appended as path segments to the end of the resource path. .. code-block:: python @@ -618,7 +618,7 @@ configuration, see :ref:`using_resource_interfaces`. Finding a Resource With a Class or Interface in Lineage ------------------------------------------------------- -Use the :func:`pyramid.traversal.find_interface` API to locate a parent that +Use the :func:`~pyramid.traversal.find_interface` API to locate a parent that is of a particular Python class, or which implements some :term:`interface`. For example, if your resource tree is composed as follows: @@ -669,7 +669,7 @@ These can be used to walk down a resource tree, or conveniently locate one resource "inside" another. Some APIs in :ref:`security_module` accept a resource object as a parameter. -For example, the :func:`pyramid.security.has_permission` API accepts a +For example, the :func:`~pyramid.security.has_permission` API accepts a resource object as one of its arguments; the ACL is obtained from this resource or one of its ancestors. Other APIs in the :mod:`pyramid.security` module also accept :term:`context` as an argument, and a context is always a diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 782098bac..11f84d4ea 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -29,10 +29,10 @@ processing? #. The :term:`application registry` and the :term:`request` object created in the last step are pushed on to the :term:`thread local` stack that :app:`Pyramid` uses to allow the functions named - :func:`pyramid.threadlocal.get_current_request` and - :func:`pyramid.threadlocal.get_current_registry` to work. + :func:`~pyramid.threadlocal.get_current_request` and + :func:`~pyramid.threadlocal.get_current_registry` to work. -#. A :class:`pyramid.events.NewRequest` :term:`event` is sent to any +#. A :class:`~pyramid.events.NewRequest` :term:`event` is sent to any subscribers. #. If any :term:`route` has been defined within application @@ -46,7 +46,7 @@ processing? ``matched_route`` attributes are added to the request object; the former contains a dictionary representing the matched dynamic elements of the request's ``PATH_INFO`` value, the latter contains - the :class:`pyramid.interfaces.IRoute` object representing the + the :class:`~pyramid.interfaces.IRoute` object representing the route which matched. The root object associated with the route found is also generated: if the :term:`route configuration` which matched has an associated a ``factory`` argument, this factory is @@ -74,7 +74,7 @@ processing? they can be accessed via e.g. ``request.context`` within :term:`view` code. -#. A :class:`pyramid.events.ContextFound` :term:`event` is +#. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any subscribers. #. :app:`Pyramid` looks up a :term:`view` callable using the @@ -83,7 +83,7 @@ processing? the context, the type of the request, and the value of the view name, and any :term:`predicate` attributes applied to the view configuration), :app:`Pyramid` raises a - :class:`pyramid.exceptions.NotFound` exception, which is meant + :class:`~pyramid.exceptions.NotFound` exception, which is meant to be caught by a surrounding exception handler. #. If a view callable was found, :app:`Pyramid` attempts to call @@ -97,14 +97,14 @@ processing? security information attached to the context. If it returns ``True``, :app:`Pyramid` calls the view callable to obtain a response. If it returns ``False``, it raises a - :class:`pyramid.exceptions.Forbidden` exception, which is meant + :class:`~pyramid.exceptions.Forbidden` exception, which is meant to be called by a surrounding exception handler. #. If any exception was raised within a :term:`root factory`, by :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself (such as when it raises - :class:`pyramid.exceptions.NotFound` or - :class:`pyramid.exceptions.Forbidden`), the router catches the + :class:`~pyramid.exceptions.NotFound` or + :class:`~pyramid.exceptions.Forbidden`), the router catches the exception, and attaches it to the request as the ``exception`` attribute. It then attempts to find a :term:`exception view` for the exception that was caught. If it finds an exception view @@ -116,15 +116,15 @@ processing? successfully generated by a normal :term:`view callable` or an :term:`exception view` callable. :app:`Pyramid` will attempt to execute any :term:`response callback` functions attached via - :meth:`pyramid.request.Request.add_response_callback`. A - :class:`pyramid.events.NewResponse` :term:`event` is then sent to any + :meth:`~pyramid.request.Request.add_response_callback`. A + :class:`~pyramid.events.NewResponse` :term:`event` is then sent to any subscribers. The response object's ``app_iter``, ``status``, and ``headerlist`` attributes are then used to generate a WSGI response. The response is sent back to the upstream WSGI server. #. :app:`Pyramid` will attempt to execute any :term:`finished callback` functions attached via - :meth:`pyramid.request.Request.add_finished_callback`. + :meth:`~pyramid.request.Request.add_finished_callback`. #. The :term:`thread local` stack is popped. diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 61948650e..72e4e3a6f 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -72,14 +72,14 @@ Enabling an Authorization Policy Imperatively ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Passing an ``authorization_policy`` argument to the constructor of the -:class:`pyramid.config.Configurator` class enables an +:class:`~pyramid.config.Configurator` class enables an authorization policy. You must also enable an :term:`authentication policy` in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the ``authentication_policy`` argument to the -:class:`pyramid.config.Configurator` class during +:class:`~pyramid.config.Configurator` class during application setup to specify an authentication policy. For example: @@ -187,11 +187,9 @@ These APIs are in support of configuring a default permission for an application: - The ``default_permission`` constructor argument to the - :mod:`pyramid.config.Configurator` constructor. + :mod:`~pyramid.config.Configurator` constructor. -- The - :meth:`pyramid.config.Configurator.set_default_permission` - method. +- The :meth:`pyramid.config.Configurator.set_default_permission` method. When a default permission is registered: @@ -546,7 +544,7 @@ one of :data:`pyramid.security.ACLAllowed`, ``msg`` attribute, which is a string indicating why the permission was denied or allowed. Introspecting this information in the debugger or via print statements when a call to -:func:`pyramid.security.has_permission` fails is often useful. +:func:`~pyramid.security.has_permission` fails is often useful. .. index:: single: authentication policy (creating) @@ -591,7 +589,7 @@ that implements the following interface: current user on subsequent requests. """ After you do so, you can pass an instance of such a class into the -:class:`pyramid.config.Configurator` class at configuration +:class:`~pyramid.config.Configurator` class at configuration time as ``authentication_policy`` to use it. .. index:: @@ -610,7 +608,7 @@ otherwise specified. In some cases, it's useful to be able to use a different authorization policy than the default -:class:`pyramid.authorization.ACLAuthorizationPolicy`. For +:class:`~pyramid.authorization.ACLAuthorizationPolicy`. For example, it might be desirable to construct an alternate authorization policy which allows the application to use an authorization mechanism that does not involve :term:`ACL` objects. @@ -641,5 +639,5 @@ following interface: used.""" After you do so, you can pass an instance of such a class into the -:class:`pyramid.config.Configurator` class at configuration +:class:`~pyramid.config.Configurator` class at configuration time as ``authorization_policy`` to use it. diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 0ed52b563..97e3ebc55 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -42,7 +42,7 @@ tampered with. You can configure this session factory in your :app:`Pyramid` application by using the ``session_factory`` argument to the -:class:`pyramid.config.Configurator` class: +:class:`~pyramid.config.Configurator` class: .. code-block:: python :linenos: diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 1b21cb516..f4655727c 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -94,7 +94,7 @@ Here's a high-level time-ordered overview of what happens when you press 'default_locale_name':'en'}``. #. The ``main`` function first constructs a - :class:`pyramid.config.Configurator` instance, passing a root resource + :class:`~pyramid.config.Configurator` instance, passing a root resource factory (constructor) to it as its ``root_factory`` argument, and ``settings`` dictionary captured via the ``**settings`` kwarg as its ``settings`` argument. @@ -109,18 +109,18 @@ Here's a high-level time-ordered overview of what happens when you press ``debug_authorization``, etc. #. The ``main`` function then calls various methods on the an instance of the - class :class:`pyramid.config.Configurator` method. The intent of + class :class:`~pyramid.config.Configurator` method. The intent of calling these methods is to populate an :term:`application registry`, which represents the :app:`Pyramid` configuration related to the application. -#. The :meth:`pyramid.config.Configurator.make_wsgi_app` method is called. +#. The :meth:`~pyramid.config.Configurator.make_wsgi_app` method is called. The result is a :term:`router` instance. The router is associated with the :term:`application registry` implied by the configurator previously populated by other methods run against the Configurator. The router is a WSGI application. -#. A :class:`pyramid.events.ApplicationCreated` event is emitted (see +#. A :class:`~pyramid.events.ApplicationCreated` event is emitted (see :ref:`events_chapter` for more information about events). #. Assuming there were no errors, the ``main`` function in ``myproject`` @@ -142,7 +142,7 @@ Deployment Settings ------------------- Note that an augmented version of the values passed as ``**settings`` to the -:class:`pyramid.config.Configurator` constructor will be available in +:class:`~pyramid.config.Configurator` constructor will be available in :app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. You can create objects you wish to access later from view code, and put them into the dictionary you pass to the configurator as ``settings``. They will diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index b97cc7be6..ae212fe5e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -203,7 +203,7 @@ may set attributes on the response that influence these values. Here's an example of changing the content-type and status of the response object returned by -:func:`pyramid.renderers.render_to_response`: +:func:`~pyramid.renderers.render_to_response`: .. code-block:: python :linenos: @@ -219,7 +219,7 @@ response object returned by return response Here's an example of manufacturing a response object using the result -of :func:`pyramid.renderers.render` (a string): +of :func:`~pyramid.renderers.render` (a string): .. code-block:: python :linenos: @@ -247,8 +247,8 @@ System Values Used During Rendering ----------------------------------- When a template is rendered using -:func:`pyramid.renderers.render_to_response` or -:func:`pyramid.renderers.render`, the renderer representing the +:func:`~pyramid.renderers.render_to_response` or +:func:`~pyramid.renderers.render`, the renderer representing the template will be provided with a number of *system* values. These values are provided in a dictionary to the renderer and include: @@ -282,7 +282,7 @@ variables. Templates Used as Renderers via Configuration --------------------------------------------- -An alternative to using :func:`pyramid.renderers.render_to_response` +An alternative to using :func:`~pyramid.renderers.render_to_response` to render templates manually in your view callable code, is to specify the template as a :term:`renderer` in your *view configuration*. This can be done with any of the @@ -299,7 +299,7 @@ The association of a template as a renderer for a :term:`view configuration` makes it possible to replace code within a :term:`view callable` that handles the rendering of a template. -Here's an example of using a :class:`pyramid.view.view_config` +Here's an example of using a :class:`~pyramid.view.view_config` decorator to specify a :term:`view configuration` that names a template renderer: @@ -456,8 +456,8 @@ Here's what a simple :term:`Chameleon` ZPT template used under Note the use of :term:`Genshi` -style ``${replacements}`` above. This is one of the ways that :term:`Chameleon` ZPT differs from standard ZPT. The above template expects to find a ``project`` key in the set -of keywords passed in to it via :func:`pyramid.renderers.render` or -:func:`pyramid.renderers.render_to_response`. Typical ZPT +of keywords passed in to it via :func:`~pyramid.renderers.render` or +:func:`~pyramid.renderers.render_to_response`. Typical ZPT attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also works in these templates. @@ -480,7 +480,7 @@ passing the macro template, or even the macro itself, *into* the rendered template. To do this you can use the :func:`pyramid.renderers.get_renderer` API to retrieve the macro template, and pass it into the template being rendered via the dictionary returned by the view. For example, using a -:term:`view configuration` via a :class:`pyramid.view.view_config` decorator +:term:`view configuration` via a :class:`~pyramid.view.view_config` decorator that uses a :term:`renderer`: .. code-block:: python diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index e166962f2..bd45388c2 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -118,7 +118,7 @@ of using this feature: testing.tearDown() The above will make sure that -:func:`pyramid.threadlocal.get_current_registry` called within a test +:func:`~pyramid.threadlocal.get_current_registry` called within a test case method of ``MyTest`` will return the :term:`application registry` associated with the ``config`` Configurator instance. Each test case method attached to ``MyTest`` will use an isolated registry. @@ -128,7 +128,7 @@ functions accepts various arguments that influence the environment of the test. See the :ref:`testing_module` chapter for information about the extra arguments supported by these functions. -If you also want to make :func:`pyramid.get_current_request` return something +If you also want to make :func:`~pyramid.get_current_request` return something other than ``None`` during the course of a single test, you can pass a :term:`request` object into the :func:`pyramid.testing.setUp` within the ``setUp`` method of your test: @@ -150,9 +150,9 @@ other than ``None`` during the course of a single test, you can pass a If you pass a :term:`request` object into :func:`pyramid.testing.setUp` within your test case's ``setUp``, any test method attached to the ``MyTest`` test case that directly or indirectly calls -:func:`pyramid.threadlocal.get_current_request` will receive the request +:func:`~pyramid.threadlocal.get_current_request` will receive the request object. Otherwise, during testing, -:func:`pyramid.threadlocal.get_current_request` will return ``None``. +:func:`~pyramid.threadlocal.get_current_request` will return ``None``. We use a "dummy" request implementation supplied by :class:`pyramid.testing.DummyRequest` because it's easier to construct than a "real" :app:`Pyramid` request object. @@ -163,8 +163,8 @@ What? Thread local data structures are always a bit confusing, especially when they're used by frameworks. Sorry. So here's a rule of thumb: if you don't *know* whether you're calling code that uses the -:func:`pyramid.threadlocal.get_current_registry` or -:func:`pyramid.threadlocal.get_current_request` functions, or you don't care +:func:`~pyramid.threadlocal.get_current_registry` or +:func:`~pyramid.threadlocal.get_current_request` functions, or you don't care about any of this, but you still want to write test code, just always call :func:`pyramid.testing.setUp` in your test's ``setUp`` method and :func:`pyramid.testing.tearDown` in your tests' ``tearDown`` method. This @@ -199,7 +199,7 @@ function. return {'greeting':'hello'} Without doing anything special during a unit test, the call to -:func:`pyramid.security.has_permission` in this view function will always +:func:`~pyramid.security.has_permission` in this view function will always return a ``True`` value. When a :app:`Pyramid` application starts normally, it will populate a :term:`application registry` using :term:`configuration declaration` calls made against a :term:`Configurator`. But if this @@ -255,7 +255,7 @@ be found when ``setup.py test`` is run. It has two test methods. The first test method, ``test_view_fn_forbidden`` tests the ``view_fn`` when the authentication policy forbids the current user the ``edit`` permission. Its third line registers a "dummy" "non-permissive" authorization policy -using the :meth:`pyramid.config.Configurator.testing_securitypolicy` method, +using the :meth:`~pyramid.config.Configurator.testing_securitypolicy` method, which is a special helper method for unit testing. We then create a :class:`pyramid.testing.DummyRequest` object which simulates @@ -264,13 +264,13 @@ request object that requires less setup than a "real" :app:`Pyramid` request. We call the function being tested with the manufactured request. When the function is called, :func:`pyramid.security.has_permission` will call the "dummy" authentication policy we've registered through -:meth:`pyramid.config.Configuration.testing_securitypolicy`, which denies +:meth:`~pyramid.config.Configuration.testing_securitypolicy`, which denies access. We check that the view function raises a :exc:`Forbidden` error. The second test method, named ``test_view_fn_allowed`` tests the alternate case, where the authentication policy allows access. Notice that we pass different values to -:meth:`pyramid.config.Configurator.testing_securitypolicy` to obtain this +:meth:`~pyramid.config.Configurator.testing_securitypolicy` to obtain this result. We assert at the end of this that the view function returns a value. Note that the test calls the :func:`pyramid.testing.setUp` function in its @@ -278,7 +278,7 @@ Note that the test calls the :func:`pyramid.testing.setUp` function in its ``tearDown`` method. We assign the result of :func:`pyramid.testing.setUp` as ``config`` on the unittest class. This is a :term:`Configurator` object and all methods of the configurator can be called as necessary within -tests. If you use any of the :class:`pyramid.config.Configurator` APIs during +tests. If you use any of the :class:`~pyramid.config.Configurator` APIs during testing, be sure to use this pattern in your test case's ``setUp`` and ``tearDown``; these methods make sure you're using a "fresh" :term:`application registry` per test run. @@ -357,7 +357,7 @@ after accessing some values that require a fully set up environment. str(len(body)))) Unless you cannot avoid it, you should prefer writing unit tests that use the -:class:`pyramid.config.Configurator` API to set up the right "mock" +:class:`~pyramid.config.Configurator` API to set up the right "mock" registrations rather than creating an integration test. Unit tests will run faster (because they do less for each test) and the result of a unit test is usually easier to make assertions about. diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst index 13bfe41cb..909f643a0 100644 --- a/docs/narr/threadlocals.rst +++ b/docs/narr/threadlocals.rst @@ -32,7 +32,7 @@ bad idea, at least if code readability counts as an important concern. For historical reasons, however, thread local variables are indeed consulted by various :app:`Pyramid` API functions. For example, the implementation of the :mod:`pyramid.security` function named -:func:`pyramid.security.authenticated_userid` retrieves the thread +:func:`~pyramid.security.authenticated_userid` retrieves the thread local :term:`application registry` as a matter of course to find an :term:`authentication policy`. It uses the :func:`pyramid.threadlocal.get_current_registry` function to @@ -43,8 +43,8 @@ allows arbitrary authentication policies to be "plugged in". When they need to do so, :app:`Pyramid` internals use two API functions to retrieve the :term:`request` and :term:`application -registry`: :func:`pyramid.threadlocal.get_current_request` and -:func:`pyramid.threadlocal.get_current_registry`. The former +registry`: :func:`~pyramid.threadlocal.get_current_request` and +:func:`~pyramid.threadlocal.get_current_registry`. The former returns the "current" request; the latter returns the "current" registry. Both ``get_current_*`` functions retrieve an object from a thread-local data structure. These API functions are documented in @@ -88,17 +88,17 @@ the :mod:`pyramid.scripting` API will never cause any Router code to be executed. However, the :mod:`pyramid.scripting` APIs also push some values on to the thread locals stack as a matter of course. Such scripts should expect the -:func:`pyramid.threadlocal.get_current_request` function to always +:func:`~pyramid.threadlocal.get_current_request` function to always return ``None``, and should expect the -:func:`pyramid.threadlocal.get_current_registry` function to return +:func:`~pyramid.threadlocal.get_current_registry` function to return exactly the same :term:`application registry` for every request. Why You Shouldn't Abuse Thread Locals ------------------------------------- You probably should almost never use the -:func:`pyramid.threadlocal.get_current_request` or -:func:`pyramid.threadlocal.get_current_registry` functions, except +:func:`~pyramid.threadlocal.get_current_request` or +:func:`~pyramid.threadlocal.get_current_registry` functions, except perhaps in tests. In particular, it's almost always a mistake to use ``get_current_request`` or ``get_current_registry`` in application code because its usage makes it possible to write code that can be @@ -134,7 +134,7 @@ follows: application depend upon it) means you're forming a dependency in the wrong direction. -Use of the :func:`pyramid.threadlocal.get_current_request` function +Use of the :func:`~pyramid.threadlocal.get_current_request` function in application code *is* still useful in very limited circumstances. As a rule of thumb, usage of ``get_current_request`` is useful **within code which is meant to eventually be removed**. For @@ -151,7 +151,7 @@ time, the older implementation code is disused and the hack that uses ``get_current_request`` is removed. This would be an appropriate place to use the ``get_current_request``. -Use of the :func:`pyramid.threadlocal.get_current_registry` +Use of the :func:`~pyramid.threadlocal.get_current_registry` function should be limited to testing scenarios. The registry made current by use of the :meth:`pyramid.config.Configurator.begin` method during a diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 7c6280ba1..68c3fabd0 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -127,7 +127,7 @@ passing it to an instance of a :term:`Configurator` named ``config``: config = Configurator(root_factory=Root) The ``root_factory`` argument to the -:class:`pyramid.config.Configurator` constructor registers this root +:class:`~pyramid.config.Configurator` constructor registers this root factory to be called to generate a root resource whenever a request enters the application. The root factory registered this way is also known as the global root factory. A root factory can alternately be diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 3f2b1b179..63a1b11d6 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -51,11 +51,9 @@ View configuration is performed in one of these ways: - by running a :term:`scan` against application source code which has a :class:`pyramid.view.view_config` decorator attached to a Python object as - per :class:`pyramid.view.view_config` and - :ref:`mapping_views_using_a_decorator_section`. + per :ref:`mapping_views_using_a_decorator_section`. - by using the :meth:`pyramid.config.Configurator.add_view` method as per - :meth:`pyramid.config.Configurator.add_view` and :ref:`mapping_views_using_imperative_config_section`. - By specifying a view within a :term:`route configuration`. View @@ -373,14 +371,14 @@ same purpose. Usage of the ``view_config`` decorator is a form of :term:`declarative configuration`, like ZCML, but in decorator form. -:class:`pyramid.view.view_config` can be used to associate :term:`view +:class:`~pyramid.view.view_config` can be used to associate :term:`view configuration` information -- as done via the equivalent imperative code or ZCML -- with a function that acts as a :app:`Pyramid` view callable. All arguments to the :meth:`pyramid.config.Configurator.add_view` method (save for the ``view`` argument) are available in decorator form and mean precisely the same thing. -An example of the :class:`pyramid.view.view_config` decorator might reside in +An example of the :class:`~pyramid.view.view_config` decorator might reside in a :app:`Pyramid` application module ``views.py``: .. ignore-next-block @@ -427,9 +425,9 @@ request method, request type, request param, route name, or containment. The mere existence of a ``@view_config`` decorator doesn't suffice to perform view configuration. All that the decorator does is "annotate" the function with your configuration declarations, it doesn't process them. To make -:app:`Pyramid` process your :class:`pyramid.view.view_config` declarations, +:app:`Pyramid` process your :class:`~pyramid.view.view_config` declarations, you *must* do use the ``scan`` method of a -:class:`pyramid.config.Configurator`: +:class:`~pyramid.config.Configurator`: .. code-block:: python :linenos: @@ -440,17 +438,17 @@ you *must* do use the ``scan`` method of a Please see :ref:`decorations_and_code_scanning` for detailed information about what happens when code is scanned for configuration declarations -resulting from use of decorators like :class:`pyramid.view.view_config`. +resulting from use of decorators like :class:`~pyramid.view.view_config`. See :ref:`configuration_module` for additional API arguments to the -:meth:`pyramid.config.Configurator.scan` method. For example, the method +:meth:`~pyramid.config.Configurator.scan` method. For example, the method allows you to supply a ``package`` argument to better control exactly *which* code will be scanned. ``@view_config`` Placement ++++++++++++++++++++++++++ -A :class:`pyramid.view.view_config` decorator can be placed in various points +A :class:`~pyramid.view.view_config` decorator can be placed in various points in your application. If your view callable is a function, it may be used as a function decorator: @@ -484,7 +482,7 @@ against a class as when they are applied against a function. For example: def __call__(self): return Response('hello') -You can use the :class:`pyramid.view.view_config` decorator as a simple +You can use the :class:`~pyramid.view.view_config` decorator as a simple callable to manually decorate classes in Python 2.5 and below without the decorator syntactic sugar, if you wish: @@ -503,7 +501,7 @@ decorator syntactic sugar, if you wish: my_view = view_config()(MyView) -More than one :class:`pyramid.view.view_config` decorator can be stacked on +More than one :class:`~pyramid.view.view_config` decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example: @@ -702,7 +700,7 @@ to a :term:`view configuration` found during view lookup will be verified. This will ensure that the currently authenticated user possesses that permission against the :term:`context` resource before the view function is actually called. Here's an example of specifying a permission in a view -configuration using :meth:`pyramid.config.Configurator.add_view`: +configuration using :meth:`~pyramid.config.Configurator.add_view`: .. code-block:: python :linenos: diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 16d9d964d..3f042712f 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -231,12 +231,12 @@ implements the :term:`Response` interface is to return a def view(request): return Response('OK') -You don't need to always use :class:`pyramid.response.Response` to represent a -response. :app:`Pyramid` provides a range of different "exception" classes +You don't need to always use :class:`~pyramid.response.Response` to represent +a response. :app:`Pyramid` provides a range of different "exception" classes which can act as response objects too. For example, an instance of the class -:class:`pyramid.httpexceptions.HTTPFound` is also a valid response object (see -:ref:`http_redirect`). A view can actually return any object that has the -following attributes. +:class:`pyramid.httpexceptions.HTTPFound` is also a valid response object +(see :ref:`http_redirect`). A view can actually return any object that has +the following attributes. status The HTTP status code (including the name) for the response as a string. @@ -291,7 +291,7 @@ Unauthorized``. It is possible, however, in Python 2.5 and above, to configure an *exception view* to catch these exceptions, and return an appropriate - :class:`pyramid.response.Response`. The simplest such view could just + :class:`~pyramid.response.Response`. The simplest such view could just catch and return the original exception. See :ref:`exception_views` for more details. @@ -313,11 +313,11 @@ handled by :app:`Pyramid` itself. These are Both are exception classes which accept a single positional constructor argument: a ``message``. -If :exc:`pyramid.exceptions.NotFound` is raised within view code, the result +If :exc:`~pyramid.exceptions.NotFound` is raised within view code, the result of the :term:`Not Found View` will be returned to the user agent which performed the request. -If :exc:`pyramid.exceptions.Forbidden` is raised within view code, the result +If :exc:`~pyramid.exceptions.Forbidden` is raised within view code, the result of the :term:`Forbidden View` will be returned to the user agent which performed the request. @@ -333,8 +333,8 @@ available to the view which :app:`Pyramid` invokes as Exception Views --------------- -The machinery which allows the special :exc:`pyramid.exceptions.NotFound` and -:exc:`pyramid.exceptions.Forbidden` exceptions to be caught by specialized +The machinery which allows the special :exc:`~pyramid.exceptions.NotFound` and +:exc:`~pyramid.exceptions.Forbidden` exceptions to be caught by specialized views as described in :ref:`special_exceptions_in_callables` can also be used by application developers to convert arbitrary exceptions to responses. @@ -516,7 +516,7 @@ an error when it can't decode some high-order character encoded in another character set within form data, e.g., when ``request.params['somename']`` is accessed. -If you are using the :class:`pyramid.response.Response` class to generate a +If you are using the :class:`~pyramid.response.Response` class to generate a response, or if you use the ``render_template_*`` templating APIs, the UTF-8 charset is set automatically as the default via the ``Content-Type`` header. If you return a ``Content-Type`` header without an explicit charset, a diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst index 78a7b0b75..fcab0653e 100644 --- a/docs/narr/zca.rst +++ b/docs/narr/zca.rst @@ -171,7 +171,7 @@ when a :term:`Configurator` constructor is called, or when a During a request, the application registry created by the Configurator is "made current". This means calls to -:func:`pyramid.threadlocal.get_current_registry` in the thread +:func:`~pyramid.threadlocal.get_current_registry` in the thread handling the request will return the component registry associated with the application. @@ -184,7 +184,7 @@ always return the global ZCA registry (the one in To "fix" this and make the ZCA global APIs use the "current" BFG registry, you need to call -:meth:`pyramid.config.Configurator.hook_zca` within your +:meth:`~pyramid.config.Configurator.hook_zca` within your setup code. For example: .. code-block:: python -- cgit v1.2.3