module name contractions

Chris McDonough

2011-01-28 70acd25f40f32fc6cbb3b5d38a695b8982b52a31

module name contractions

 docs/narr/advconfig.rst

@@ -163,7 +163,7 @@
+++++++++++++++++++++++++

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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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.

 docs/narr/assets.rst

@@ -142,7 +142,7 @@

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 @@
   # 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 @@
   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 @@
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 ``/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 @@
``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 @@
   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 @@
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 @@
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 @@
   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 @@
   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 @@
   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 @@
  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 @@
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 @@
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

 docs/narr/configuration.rst

@@ -127,7 +127,7 @@
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 @@
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

 docs/narr/events.rst

@@ -43,7 +43,7 @@

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 @@
  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 @@
  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

 docs/narr/extending.rst

@@ -115,15 +115,14 @@

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 ``<route>`` directive).  Views are declarations made using the
:meth:`pyramid.config.Configurator.add_view` method (or the ZCML ``<view>``
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 @@
~~~~~~~~~~~~~~~~~

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

 docs/narr/firstapp.rst

@@ -122,7 +122,7 @@
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.

 docs/narr/hooks.rst

@@ -42,7 +42,7 @@
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 @@

.. 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 @@
.. 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 @@

.. 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 @@

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 @@
: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 @@

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 @@
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 @@
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 @@
                                   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 @@
``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 @@
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 @@
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`.

 docs/narr/hybrid.rst

@@ -156,12 +156,12 @@
- 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 @@

  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 @@
   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 @@

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 @@
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 @@
   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:


 docs/narr/i18n.rst

@@ -59,7 +59,7 @@
   :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 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 @@
   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 @@

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 @@
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 @@
       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 @@
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 @@

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 @@
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 @@
                               '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 @@
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 @@
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 @@
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

 docs/narr/muchadoabouttraversal.rst

@@ -305,7 +305,6 @@
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.

 docs/narr/renderers.rst

@@ -23,7 +23,7 @@
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 @@

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 @@

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 @@
   :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 @@
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 @@
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:

 docs/narr/resources.rst

@@ -36,8 +36,8 @@
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 @@
  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 @@

.. 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 @@

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 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 @@
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 @@
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 @@
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 @@
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

 docs/narr/router.rst

@@ -29,10 +29,10 @@
#. 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 @@
   ``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 @@
   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 @@
   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 @@
   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 @@
   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.


 docs/narr/security.rst

@@ -72,14 +72,14 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 @@
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 @@
``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 @@
           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 @@

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 @@
            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.

 docs/narr/sessions.rst

@@ -42,7 +42,7 @@

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:

 docs/narr/startup.rst

@@ -94,7 +94,7 @@
   '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 @@
   ``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 @@
-------------------

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

 docs/narr/templates.rst

@@ -203,7 +203,7 @@

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 @@
       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 @@
-----------------------------------

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 @@
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 @@
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 @@
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 @@
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

 docs/narr/testing.rst

@@ -118,7 +118,7 @@
           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 @@
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 @@
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 @@
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 @@
       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 @@
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 @@
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 @@
``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 @@
                                                   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.

 docs/narr/threadlocals.rst

@@ -32,7 +32,7 @@
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 @@

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 @@
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 @@
  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 @@
``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

 docs/narr/traversal.rst

@@ -127,7 +127,7 @@
   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

 docs/narr/viewconfig.rst

@@ -51,11 +51,9 @@

- 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 @@

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 @@
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 @@

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 @@
       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 @@

   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 @@
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:

 docs/narr/views.rst

@@ -231,12 +231,12 @@
   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 @@

   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 @@
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 @@
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 @@
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

 docs/narr/zca.rst

@@ -171,7 +171,7 @@

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 @@

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