path: root/docs/narr/introspector.rst

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

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.

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:`pryamid.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``

  XXX ``default root factory`` category?

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

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

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

  XXX default view mapper category?

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

  XXX

``translation directories``

  XXX

``tweens (implicit)``

  XXX

``tweens (explicit)``

  XXX