merge feature.introspection branch

1 files changed, 542 insertions, 0 deletions

diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
new file mode 100644
index 000000000..cfc6144dd
--- /dev/null
+++ b/docs/narr/introspector.rst
@@ -0,0 +1,542 @@
+.. index::
+   single: introspection
+   single: introspector
+
+.. _using_introspection:
+
+Pyramid Configuration Introspection
+===================================
+
+When Pyramid starts up, each call to a :term:`configuration directive` causes
+one or more :term:`introspectable` objects to be registered with an
+:term:`introspector`.  The introspector can be queried by application code to
+obtain information about the configuration of the running application.  This
+feature is useful for debug toolbars, command-line scripts which show some
+aspect of configuration, and for runtime reporting of startup-time
+configuration settings.
+
+.. warning::
+
+   Introspection is new in Pyramid 1.3.
+
+Using the Introspector
+----------------------
+
+Here's an example of using Pyramid's introspector from within a view
+callable:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.view import view_config
+    from pyramid.response import Response
+
+    @view_config(route_name='bar')
+    def route_accepts(request):
+        introspector = request.registry.introspector
+        route_name = request.matched_route.name
+        route_intr = introspector.get('routes', route_name)
+        return Response(str(route_intr['pattern']))
+
+This view will return a response that contains the "pattern" argument
+provided to the ``add_route`` method of the route which matched when the view
+was called.  It uses the :meth:`pyramid.interfaces.IIntrospector.get` method
+to return an introspectable in the category ``routes`` with a
+:term:`discriminator` equal to the matched route name.  It then uses the
+returned introspectable to obtain an "pattern" value.
+
+The introspectable returned by the query methods of the introspector has
+methods and attributes described by
+:class:`pyramid.interfaces.IIntrospectable`.  In particular, the
+:meth:`~pyramid.interfaces.IIntrospector.get`,
+:meth:`~pyramid.interfaces.IIntrospector.get_category`,
+:meth:`~pyramid.interfaces.IIntrospector.categories`,
+:meth:`~pyramid.interfaces.IIntrospector.categorized`, and
+:meth:`~pyramid.interfaces.IIntrospector.related` methods of an introspector
+can be used to query for introspectables.
+
+Introspectable Objects
+----------------------
+
+Introspectable objects are returned from query methods of an introspector.
+Each introspectable object implements the attributes and methods the
+documented at :class:`pyramid.interfaces.IIntrospectable`.
+
+The important attributes shared by all introspectables are the following:
+
+``title``
+
+  A human-readable text title describing the introspectable
+
+``category_name``
+
+  A text category name describing the introspection category to which this
+  introspectable belongs.  It is often a plural if there are expected to be
+  more than one introspectable registered within the category.
+
+``discriminator``
+
+  A hashable object representing the unique value of this introspectable
+  within its category.
+
+``discriminator_hash``
+
+  The integer hash of the discriminator (useful for using in HTML links).
+
+``type_name``
+
+  The text name of a subtype within this introspectable's category.  If there
+  is only one type name in this introspectable's category, this value will
+  often be a singular version of the category name but it can be an arbitrary
+  value.
+
+``action_info``
+
+  An object describing the directive call site which caused this
+  introspectable to be registered; contains attributes described in
+  :class:`pyramid.interfaces.IActionInfo`.
+
+Besides having the attributes described above, an introspectable is a
+dictionary-like object.  An introspectable can be queried for data values via
+its ``__getitem__``, ``get``, ``keys``, ``values``, or ``items`` methods.
+For example:
+
+.. code-block:: python
+   :linenos:
+
+    route_intr = introspector.get('routes', 'edit_user')
+    pattern = route_intr['pattern']
+
+Pyramid Introspection Categories
+--------------------------------
+
+The list of concrete introspection categories provided by built-in Pyramid
+configuration directives follows.  Add-on packages may supply other
+introspectables in categories not described here.
+
+``subscribers``
+
+  Each introspectable in the ``subscribers`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_subscriber` (or the decorator
+  equivalent); each will have the following data.
+
+  ``subscriber``
+
+    The subscriber callable object (the resolution of the ``subscriber``
+    argument passed to ``add_susbcriber``).
+
+  ``interfaces``
+
+    A sequence of interfaces (or classes) that are subscribed to (the
+    resolution of the ``ifaces`` argument passed to ``add_subscriber``).
+
+``response adapters``
+
+  Each introspectable in the ``response adapters`` category represents a call
+  to :meth:`pyramid.config.Configurator.add_response_adapter` (or a decorator
+  equivalent); each will have the following data.
+
+  ``adapter``
+
+    The adapter object (the resolved ``adapter`` argument to
+    ``add_response_adapter``).
+
+  ``type``
+
+    The resolved ``type_or_iface`` argument passed to
+    ``add_response_adapter``.
+
+``root factories``
+
+  Each introspectable in the ``root factories`` category represents a call to
+  :meth:`pyramid.config.Configurator.set_root_factory` (or the Configurator
+  constructor equivalent) *or* a ``factory`` argument passed to
+  :meth:`pyramid.config.Configurator.add_route`; each will have the following
+  data.
+
+  ``factory``
+
+    The factory object (the resolved ``factory`` argument to
+    ``set_root_factory``).
+
+  ``route_name``
+
+    The name of the route which will use this factory.  If this is the
+    *default* root factory (if it's registered during a call to
+    ``set_root_factory``), this value will be ``None``.
+
+``session factory``
+
+  Only one introspectable will exist in the ``session factory`` category.  It
+  represents a call to :meth:`pyramid.config.Configurator.set_session_factory`
+  (or the Configurator constructor equivalent); it will have the following
+  data.
+
+  ``factory``
+
+    The factory object (the resolved ``factory`` argument to
+    ``set_session_factory``).
+
+``request factory``
+
+  Only one introspectable will exist in the ``request factory`` category.  It
+  represents a call to :meth:`pyramid.config.Configurator.set_request_factory`
+  (or the Configurator constructor equivalent); it will have the following
+  data.
+
+  ``factory``
+
+    The factory object (the resolved ``factory`` argument to
+    ``set_request_factory``).
+
+``locale negotiator``
+
+  Only one introspectable will exist in the ``locale negotiator`` category.
+  It represents a call to
+  :meth:`pyramid.config.Configurator.set_locale_negotiator` (or the
+  Configurator constructor equivalent); it will have the following data.
+
+  ``negotiator``
+
+    The factory object (the resolved ``negotiator`` argument to
+    ``set_locale_negotiator``).
+
+``renderer factories``
+
+  Each introspectable in the ``renderer factories`` category represents a
+  call to :meth:`pyramid.config.Configurator.add_renderer` (or the
+  Configurator constructor equivalent); each will have the following data.
+
+  ``name``
+
+    The name of the renderer (the value of the ``name`` argument to
+    ``add_renderer``).
+
+  ``factory``
+
+    The factory object (the resolved ``factory`` argument to
+    ``add_renderer``).
+
+``renderer globals factory``
+
+  There will be one and only one introspectable in the ``renderer globals
+  factory`` category.  It represents a call to
+  :meth:`pyramid.config.Configurator.set_renderer_globals_factory`; it will
+  have the following data.
+
+  ``factory``
+
+    The factory object (the resolved ``factory`` argument to
+    ``set_renderer_globals_factory``).
+
+``routes``
+
+  Each introspectable in the ``routes`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_route`; each will have the following
+  data.
+
+  ``name``
+
+    The ``name`` argument passed to ``add_route``.
+
+  ``pattern``
+
+    The ``pattern`` argument passed to ``add_route``.
+
+  ``factory``
+
+    The (resolved) ``factory`` argument passed to ``add_route``.
+
+  ``xhr``
+
+    The ``xhr`` argument passed to ``add_route``.
+
+  ``request_method``
+
+    The ``request_method`` argument passed to ``add_route``.
+
+  ``request_methods``
+
+    A sequence of request method names implied by the ``request_method``
+    argument passed to ``add_route`` or the value ``None`` if a
+    ``request_method`` argument was not supplied.
+
+  ``path_info``
+
+    The ``path_info`` argument passed to ``add_route``.
+
+  ``request_param``
+
+    The ``request_param`` argument passed to ``add_route``.
+
+  ``header``
+
+    The ``header`` argument passed to ``add_route``.
+
+  ``accept``
+
+    The ``accept`` argument passed to ``add_route``.
+
+  ``traverse``
+
+    The ``traverse`` argument passed to ``add_route``.
+
+  ``custom_predicates``
+
+    The ``custom_predicates`` argument passed to ``add_route``.
+
+  ``pregenerator``
+
+    The ``pregenerator`` argument passed to ``add_route``.
+
+  ``pregenerator``
+
+    The ``static`` argument passed to ``add_route``.
+
+  ``pregenerator``
+
+    The ``use_global_views`` argument passed to ``add_route``.
+
+  ``object``
+
+     The :class:`pyramid.interfaces.IRoute` object that is used to perform
+     matching and generation for this route.
+
+``authentication policy``
+
+  There will be one and only one introspectable in the ``authentication
+  policy`` category.  It represents a call to the
+  :meth:`pyramid.config.Configurator.set_authentication_policy` method (or
+  its Configurator constructor equivalent); it will have the following data.
+
+  ``policy``
+
+    The policy object (the resolved ``policy`` argument to
+    ``set_authentication_policy``).
+
+``authorization policy``
+
+  There will be one and only one introspectable in the ``authorization
+  policy`` category.  It represents a call to the
+  :meth:`pyramid.config.Configurator.set_authorization_policy` method (or its
+  Configurator constructor equivalent); it will have the following data.
+
+  ``policy``
+
+    The policy object (the resolved ``policy`` argument to
+    ``set_authorization_policy``).
+
+``default permission``
+
+  There will be one and only one introspectable in the ``default permission``
+  category.  It represents a call to the
+  :meth:`pyramid.config.Configurator.set_default_permission` method (or its
+  Configurator constructor equivalent); it will have the following data.
+
+  ``value``
+
+    The permission name passed to ``set_default_permission``.
+
+``views``
+
+  Each introspectable in the ``views`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_view`; each will have the following
+  data.
+
+  ``name``
+
+    The ``name`` argument passed to ``add_view``.
+
+  ``context``
+
+    The (resolved) ``context`` argument passed to ``add_view``.
+
+  ``containment``
+
+    The (resolved) ``containment`` argument passed to ``add_view``.
+
+  ``request_param``
+
+    The ``request_param`` argument passed to ``add_view``.
+
+  ``request_methods``
+
+    A sequence of request method names implied by the ``request_method``
+    argument passed to ``add_view`` or the value ``None`` if a
+    ``request_method`` argument was not supplied.
+
+  ``route_name``
+
+    The ``route_name`` argument passed to ``add_view``.
+
+  ``attr``
+
+    The ``attr`` argument passed to ``add_view``.
+
+  ``xhr``
+
+    The ``xhr`` argument passed to ``add_view``.
+
+  ``accept``
+
+    The ``accept`` argument passed to ``add_view``.
+
+  ``header``
+
+    The ``header`` argument passed to ``add_view``.
+
+  ``path_info``
+
+    The ``path_info`` argument passed to ``add_view``.
+
+  ``match_param``
+
+    The ``match_param`` argument passed to ``add_view``.
+
+  ``callable``
+
+    The (resolved) ``view`` argument passed to ``add_view``.  Represents the
+    "raw" view callable.
+
+  ``derived_callable``
+
+    The view callable derived from the ``view`` argument passed to
+    ``add_view``.  Represents the view callable which Pyramid itself calls
+    (wrapped in security and other wrappers).
+
+  ``mapper``
+
+    The (resolved) ``mapper`` argument passed to ``add_view``.
+
+  ``decorator``
+
+    The (resolved) ``decorator`` argument passed to ``add_view``.
+
+``permissions``
+
+  Each introspectable in the ``permissions`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_view` that has an explicit
+  ``permission`` argument to *or* a call to
+  :meth:`pyramid.config.Configurator.set_default_permission`; each will have
+  the following data.
+
+  ``value``
+
+    The permission name passed to ``add_view`` or ``set_default_permission``.
+
+``templates``
+
+  Each introspectable in the ``templates`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_view` that has a ``renderer``
+  argument which points to a template; each will have the following data.
+
+  ``name``
+
+    The renderer's name (a string).
+
+  ``type``
+
+    The renderer's type (a string).
+
+  ``renderer``
+
+    The :class:`pyramid.interfaces.IRendererInfo` object which represents
+    this template's renderer.
+
+``view mapper``
+
+  Each introspectable in the ``permissions`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_view` that has an explicit
+  ``mapper`` argument to *or* a call to
+  :meth:`pyramid.config.Configurator.set_view_mapper`; each will have
+  the following data.
+
+  ``mapper``
+
+    The (resolved) ``mapper`` argument passed to ``add_view`` or
+    ``set_view_mapper``.
+
+``asset overrides``
+
+  Each introspectable in the ``asset overrides`` category represents a call
+  to :meth:`pyramid.config.Configurator.override_asset`; each will have the
+  following data.
+
+  ``to_override``
+
+    The ``to_override`` argument (an asset spec) passed to
+    ``override_asset``.
+
+  ``override_with``
+
+    The ``override_with`` argument (an asset spec) passed to
+    ``override_asset``.
+
+``translation directories``
+
+  Each introspectable in the ``asset overrides`` category represents an
+  individual element in a ``specs`` argument passed to to
+  :meth:`pyramid.config.Configurator.add_translation_dirs`; each will have
+  the following data.
+
+  ``directory``
+
+    The absolute path of the translation directory.
+
+  ``spec``
+
+    The asset specification passed to ``add_translation_dirs``.
+
+``tweens``
+
+  Each introspectable in the ``tweens`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_tween`; each will have the following
+  data.
+
+  ``name``
+
+    The dotted name to the tween factory as a string (passed as
+    the ``tween_factory`` argument to ``add_tween``).
+
+  ``factory``
+
+    The (resolved) tween factory object.
+
+  ``type``
+
+    ``implict`` or ``explicit`` as a string.
+
+  ``under``
+
+     The ``under`` argument passed to ``add_tween`` (a string).
+
+  ``over``
+
+     The ``over`` argument passed to ``add_tween`` (a string).
+
+Introspection in the Toolbar
+----------------------------
+
+The Pyramid debug toolbar (part of the ``pyramid_debugtoolbar`` package)
+provides a canned view of all registered introspectables and their
+relationships.  It looks something like this:
+
+.. image:: tb_introspector.png
+
+Disabling Introspection
+-----------------------
+
+You can disable Pyramid introspection by passing the object
+:attr:`pyramid.registry.noop_introspector` to the :term:`Configurator`
+constructor in your application setup:
+
+.. code-block:: python
+
+   from pyramid.config import Configurator
+   from pyramid.registry import noop_introspector
+   config = Configurator(..., introspector=noop_introspector)
+
+When the noop introspector is active, all introspectables generated by
+configuration directives are thrown away.  A noop introspector behaves just
+like a "real" introspector, but the methods of a noop introspector do nothing
+and return null values.