.. index:: single: introspection single: introspector .. _using_introspection: Pyramid Configuration Introspection =================================== .. versionadded:: 1.3 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 show_current_route_pattern(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 a "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 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 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. It 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_subscriber``). ``interfaces`` A sequence of interfaces (or classes) that are subscribed to (the resolution of the ``ifaces`` argument passed to ``add_subscriber``). ``derived_subscriber`` A wrapper around the subscriber used internally by the system so it can call it with more than one argument if your original subscriber accepts only one. ``predicates`` The predicate objects created as the result of passing predicate arguments to ``add_subscriber``. ``derived_predicates`` Wrappers around the predicate objects created as the result of passing predicate arguments to ``add_subscriber`` (to be used when predicates take only one value but must be passed more than one). ``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``). ``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``. ``static`` The ``static`` argument passed to ``add_route``. ``use_global_views`` 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. ``security policy`` There will be one and only one introspectable in the ``security policy`` category. It represents a call to the :meth:`pyramid.config.Configurator.set_security_policy` method (or its Configurator constructor equivalent). It will have the following data: ``policy`` The policy object (the resolved ``policy`` argument to ``set_security_policy``). ``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``. ``default csrf options`` There will be one and only one introspectable in the ``default csrf options`` category. It represents a call to the :meth:`pyramid.config.Configurator.set_default_csrf_options` method. It will have the following data. ``require_csrf`` The default value for ``require_csrf`` if left unspecified on calls to :meth:`pyramid.config.Configurator.add_view`. ``token`` The name of the token searched in ``request.POST`` to find a valid CSRF token. ``header`` The name of the request header searched to find a valid CSRF token. ``safe_methods`` The list of HTTP methods considered safe and exempt from CSRF checks. ``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``. ``csrf_token`` The ``csrf_token`` 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 *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 mappers`` Each introspectable in the ``view mappers`` category represents a call to :meth:`pyramid.config.Configurator.add_view` that has an explicit ``mapper`` argument *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 ``translation directories`` category represents an individual element in a ``specs`` argument passed 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`` ``implicit`` 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). ``static views`` Each introspectable in the ``static views`` category represents a call to :meth:`pyramid.config.Configurator.add_static_view`. Each will have the following data. ``name`` The ``name`` argument provided to ``add_static_view``. ``spec`` A normalized version of the ``spec`` argument provided to ``add_static_view``. ``traversers`` Each introspectable in the ``traversers`` category represents a call to :meth:`pyramid.config.Configurator.add_traverser`. Each will have the following data. ``iface`` The (resolved) interface or class object that represents the return value of a root factory for which this traverser will be used. ``adapter`` The (resolved) traverser class. ``resource url adapters`` Each introspectable in the ``resource url adapters`` category represents a call to :meth:`pyramid.config.Configurator.add_resource_url_adapter`. Each will have the following data. ``adapter`` The (resolved) resource URL adapter class. ``resource_iface`` The (resolved) interface or class object that represents the resource interface for which this URL adapter is registered. ``request_iface`` The (resolved) interface or class object that represents the request interface for which this URL adapter is registered. 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 is currently under the "Global" tab in the main navigation, and it looks something like this: .. image:: tb_introspector.png Disabling Introspection ----------------------- You can disable Pyramid introspection by passing the flag ``introspection=False`` to the :term:`Configurator` constructor in your application setup: .. code-block:: python from pyramid.config import Configurator config = Configurator(..., introspection=False) When ``introspection`` is ``False``, all introspectables generated by configuration directives are thrown away.