document the request.settings attribute as well as we can

Chris McDonough

2010-11-11 a1365e6f0da69e1b4e3f9cea11222849e5ca810a

document the request.settings attribute as well as we can

 docs/api.rst

@@ -20,6 +20,7 @@
   api/interfaces
   api/location
   api/paster
   api/registry
   api/renderers
   api/request
   api/response

 docs/glossary.rst

@@ -826,3 +826,10 @@
     :meth:`pyramid.configuration.Configurator.add_view` to make it more
     convenient to register a collection of views as a single class when
     using :term:`url dispatch`.  See also :ref:`handlers_chapter`.

   Deployment settings
     Deployment settings are settings passed to the :term:`Configurator` as a
     ``settings`` argument.  These are later accessible via a
     ``request.registry.settings`` dictionary.  Deployment settings can be
     used as global application values.


 docs/latexindex.rst

@@ -94,6 +94,7 @@
   api/interfaces
   api/location
   api/paster
   api/registry
   api/renderers
   api/request
   api/response

 docs/narr/startup.rst

@@ -138,7 +138,18 @@
   the application, and the application is running, waiting to receive
   requests.

.. _deployment_settings:

Deployment Settings
-------------------

Note that an augmented version of the values passed as ``**settings`` to the
:class:`pyramid.configuration.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
then be present in the ``request.registry.settings`` dictionary at
application runtime.


   

 pyramid/configuration.py

@@ -123,11 +123,10 @@
    is assumed to be the Python package in which the *caller* of the
    ``Configurator`` constructor lives.

    If the ``settings`` argument is passed, it should be a Python
    dictionary representing the deployment settings for this
    application.  These are later retrievable using the
    :meth:`pyramid.registry.Registry.settings` attribute or the
    :func:`pyramid.settings.get_settings` API.
    If the ``settings`` argument is passed, it should be a Python dictionary
    representing the deployment settings for this application.  These are
    later retrievable using the :attr:`pyramid.registry.Registry.settings`
    attribute (aka ``request.registry.settings``).

    If the ``root_factory`` argument is passed, it should be an object
    representing the default :term:`root factory` for your application
@@ -584,11 +583,11 @@

           config.add_settings(external_uri='http://example.com')

        This function is useful when you need to test code that calls
        the :func:`pyramid.settings.get_settings` API (or the
        :meth:`pyramid.configuration.Configurator.get_settings`
        API) and which uses return values from that API.

        This function is useful when you need to test code that calls the
        :func:`pyramid.settings.get_settings` API (or the
        :meth:`pyramid.configuration.Configurator.get_settings` API or
        accesses ``request.settings``) and which uses return values from that
        API.
        """
        if settings is None:
            settings = {}
@@ -610,8 +609,9 @@
           looked up as attributes of the settings object.

        .. note:: the :class:`pyramid.settings.get_settings` and function
        performs the same duty and the settings attribute can also be
        accessed as :attr:`pyramid.registry.Registry.settings`"""
           performs the same duty and the settings attribute can also be
           accessed as :attr:`pyramid.registry.Registry.settings`
           """
        return self.registry.settings

    def make_wsgi_app(self):

 pyramid/registry.py

@@ -2,6 +2,20 @@
from pyramid.interfaces import ISettings

class Registry(Components, dict):
    """ A registry object is an :term:`application registry`.  The existence
    of a registry implementation detail of :app:`pyramid`.  It is used by the
    framework itself to perform mappings of URLs to view callables, as well
    as servicing other various duties. Despite being an implementation detail
    of the framework, it has a number of attributes that may be useful within
    application code.

    For information about the purpose and usage of the application registry,
    see :ref:`zca_chapter`.

    The application registry is usually accessed as ``request.registry`` in
    application code.

    """

    # for optimization purposes, if no listeners are listening, don't try
    # to notify them