improve the registry documentation to cover usage as a dictionary

Michael Merickel

2017-01-02 5e20f9c6686481d67020cf82e18802f06c54964e

improve the registry documentation to cover usage as a dictionary

fixes #2891

 docs/conf.py

@@ -81,7 +81,8 @@
    'webtest': ('http://webtest.pythonpaste.org/en/latest', None),
    'who': ('http://repozewho.readthedocs.org/en/latest', None),
    'zcml': ('http://docs.pylonsproject.org/projects/pyramid-zcml/en/latest', None),
    'zcomponent': ('http://zopecomponent.readthedocs.io/en/stable/', None),
    'zcomponent': ('http://zopecomponent.readthedocs.io/en/latest/', None),
    'zinterface': ('http://zopeinterface.readthedocs.io/en/latest/', None),
}



 pyramid/registry.py

@@ -9,28 +9,44 @@
from pyramid.decorator import reify

from pyramid.interfaces import (
    ISettings,
    IIntrospector,
    IIntrospectable,
    ISettings,
    )

from pyramid.path import (
    CALLER_PACKAGE,
    caller_package,
)

empty = text_('')

class Registry(Components, dict):
    """ A registry object is an :term:`application registry`.  It is used by
    the framework itself to perform mappings of URLs to view callables, as
    well as servicing other various framework duties. A registry has its own
    internal API, but this API is rarely used by Pyramid application
    developers (it's usually only used by developers of the Pyramid
    framework).  But it has a number of attributes that may be useful to
    application developers within application code, such as ``settings``,
    which is a dictionary containing application deployment settings.
    """ A registry object is an :term:`application registry`.

    It is used by the framework itself to perform mappings of URLs to view
    callables, as well as servicing other various framework duties. A registry
    has its own internal API, but this API is rarely used by Pyramid
    application developers (it's usually only used by developers of the
    Pyramid framework and Pyramid addons).  But it has a number of attributes
    that may be useful to application developers within application code,
    such as ``settings``, which is a dictionary containing application
    deployment settings.

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

    The registry may be used both as an :class:`pyramid.interfaces.IDict` and
    as a Zope component registry.
    These two ways of storing configuration are independent.
    Applications will tend to prefer to store information as key-values
    whereas addons may prefer to use the component registry to avoid naming
    conflicts and to provide more complex lookup mechanisms.

    The application registry is usually accessed as ``request.registry`` in
    application code.
    application code. By the time a registry is used to handle requests it
    should be considered frozen and read-only. Any changes to its internal
    state should be done with caution and concern for thread-safety.

    """

@@ -40,13 +56,16 @@

    _settings = None

    def __init__(self, *arg, **kw):
    def __init__(self, package_name=CALLER_PACKAGE):
        # add a registry-instance-specific lock, which is used when the lookup
        # cache is mutated
        self._lock = threading.Lock()
        # add a view lookup cache
        self._clear_view_lookup_cache()
        Components.__init__(self, *arg, **kw)
        if package_name is CALLER_PACKAGE:
            package_name = caller_package().__name__
        Components.__init__(self, package_name)
        dict.__init__(self)

    def _clear_view_lookup_cache(self):
        self._view_lookup_cache = {}

 pyramid/tests/test_registry.py

@@ -27,6 +27,10 @@
        registry = self._getTargetClass()(package_name)
        self.assertEqual(registry.package_name, package_name)

    def test_default_package_name(self):
        registry = self._getTargetClass()()
        self.assertEqual(registry.package_name, 'pyramid.tests')

    def test_registerHandler_and_notify(self):
        registry = self._makeOne()
        self.assertEqual(registry.has_listeners, False)