single: introspection single: introspector
When Pyramid starts up, each call to a configuration directive
causes one or more introspectable
objects to be registered with an 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.
Here's an example of using Pyramid's introspector from within a view callable:
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 pyramid.interfaces.IIntrospector.get
method to return an introspectable in the category routes
with a 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 pyramid.interfaces.IIntrospectable
. In particular, the ~pyramid.interfaces.IIntrospector.get
, ~pyramid.interfaces.IIntrospector.get_category
, ~pyramid.interfaces.IIntrospector.categories
, ~pyramid.interfaces.IIntrospector.categorized
, and ~pyramid.interfaces.IIntrospector.related
methods of an introspector can be used to query for introspectables.
Introspectable objects are returned from query methods of an introspector. Each introspectable object implements the attributes and methods documented at 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
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:
route_intr = introspector.get('routes', 'edit_user')
pattern = route_intr['pattern']
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 topyramid.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 toadd_susbcriber
).
interfaces
A sequence of interfaces (or classes) that are subscribed to (the resolution of the
ifaces
argument passed toadd_subscriber
).
response adapters
Each introspectable in the
response adapters
category represents a call topyramid.config.Configurator.add_response_adapter
(or a decorator equivalent); each will have the following data.
adapter
The adapter object (the resolved
adapter
argument toadd_response_adapter
).
type
The resolved
type_or_iface
argument passed toadd_response_adapter
.
root factories
Each introspectable in the
root factories
category represents a call topyramid.config.Configurator.set_root_factory
(or the Configurator constructor equivalent) or afactory
argument passed topyramid.config.Configurator.add_route
; each will have the following data.
factory
The factory object (the resolved
factory
argument toset_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 beNone
.
session factory
Only one introspectable will exist in the
session factory
category. It represents a call topyramid.config.Configurator.set_session_factory
(or the Configurator constructor equivalent); it will have the following data.
factory
The factory object (the resolved
factory
argument toset_session_factory
).
request factory
Only one introspectable will exist in the
request factory
category. It represents a call topyramid.config.Configurator.set_request_factory
(or the Configurator constructor equivalent); it will have the following data.
factory
The factory object (the resolved
factory
argument toset_request_factory
).
locale negotiator
Only one introspectable will exist in the
locale negotiator
category. It represents a call topyramid.config.Configurator.set_locale_negotiator
(or the Configurator constructor equivalent); it will have the following data.
negotiator
The factory object (the resolved
negotiator
argument toset_locale_negotiator
).
renderer factories
Each introspectable in the
renderer factories
category represents a call topyramid.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 toadd_renderer
).
factory
The factory object (the resolved
factory
argument toadd_renderer
).
renderer globals factory
There will be one and only one introspectable in the
renderer globals factory
category. It represents a call topyramid.config.Configurator.set_renderer_globals_factory
; it will have the following data.
factory
The factory object (the resolved
factory
argument toset_renderer_globals_factory
).
routes
Each introspectable in the
routes
category represents a call topyramid.config.Configurator.add_route
; each will have the following data.
name
The
name
argument passed toadd_route
.
pattern
The
pattern
argument passed toadd_route
.
factory
The (resolved)
factory
argument passed toadd_route
.
xhr
The
xhr
argument passed toadd_route
.
request_method
The
request_method
argument passed toadd_route
.
request_methods
A sequence of request method names implied by the
request_method
argument passed toadd_route
or the valueNone
if arequest_method
argument was not supplied.
path_info
The
path_info
argument passed toadd_route
.
request_param
The
request_param
argument passed toadd_route
.
header
The
header
argument passed toadd_route
.
accept
The
accept
argument passed toadd_route
.
traverse
The
traverse
argument passed toadd_route
.
custom_predicates
The
custom_predicates
argument passed toadd_route
.
pregenerator
The
pregenerator
argument passed toadd_route
.
static
The
static
argument passed toadd_route
.
use_global_views
The
use_global_views
argument passed toadd_route
.
object
The
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 thepyramid.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 toset_authentication_policy
).
authorization policy
There will be one and only one introspectable in the
authorization policy
category. It represents a call to thepyramid.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 toset_authorization_policy
).
default permission
There will be one and only one introspectable in the
default permission
category. It represents a call to thepyramid.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 topyramid.config.Configurator.add_view
; each will have the following data.
name
The
name
argument passed toadd_view
.
context
The (resolved)
context
argument passed toadd_view
.
containment
The (resolved)
containment
argument passed toadd_view
.
request_param
The
request_param
argument passed toadd_view
.
request_methods
A sequence of request method names implied by the
request_method
argument passed toadd_view
or the valueNone
if arequest_method
argument was not supplied.
route_name
The
route_name
argument passed toadd_view
.
attr
The
attr
argument passed toadd_view
.
xhr
The
xhr
argument passed toadd_view
.
accept
The
accept
argument passed toadd_view
.
header
The
header
argument passed toadd_view
.
path_info
The
path_info
argument passed toadd_view
.
match_param
The
match_param
argument passed toadd_view
.
callable
The (resolved)
view
argument passed toadd_view
. Represents the "raw" view callable.
derived_callable
The view callable derived from the
view
argument passed toadd_view
. Represents the view callable which Pyramid itself calls (wrapped in security and other wrappers).
mapper
The (resolved)
mapper
argument passed toadd_view
.
decorator
The (resolved)
decorator
argument passed toadd_view
.
permissions
Each introspectable in the
permissions
category represents a call topyramid.config.Configurator.add_view
that has an explicitpermission
argument to or a call topyramid.config.Configurator.set_default_permission
; each will have the following data.
value
The permission name passed to
add_view
orset_default_permission
.
templates
Each introspectable in the
templates
category represents a call topyramid.config.Configurator.add_view
that has arenderer
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
pyramid.interfaces.IRendererInfo
object which represents this template's renderer.
view mapper
Each introspectable in the
permissions
category represents a call topyramid.config.Configurator.add_view
that has an explicitmapper
argument to or a call topyramid.config.Configurator.set_view_mapper
; each will have the following data.
mapper
The (resolved)
mapper
argument passed toadd_view
orset_view_mapper
.
asset overrides
Each introspectable in the
asset overrides
category represents a call topyramid.config.Configurator.override_asset
; each will have the following data.
to_override
The
to_override
argument (an asset spec) passed tooverride_asset
.
override_with
The
override_with
argument (an asset spec) passed tooverride_asset
.
translation directories
Each introspectable in the
asset overrides
category represents an individual element in aspecs
argument passed to topyramid.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 topyramid.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 toadd_tween
).
factory
The (resolved) tween factory object.
type
implict
orexplicit
as a string.
under
The
under
argument passed toadd_tween
(a string).
over
The
over
argument passed toadd_tween
(a string).
static views
Each introspectable in the
static views
category represents a call topyramid.config.Configurator.add_static_view
; each will have the following data.
name
The
name
argument provided toadd_static_view
.
spec
A normalized version of the
spec
argument provided toadd_static_view
.
traversers
Each introspectable in the
traversers
category represents a call topyramid.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 that this traverser will be used for.
adapter
The (resolved) traverser class.
resource url adapters
Each introspectable in the
resource url adapters
category represents a call topyramid.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 that this url adapter is registered for.
request_iface
The (resolved) interface or class object that represents the request interface that this url adapter is registered for.
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:
You can disable Pyramid introspection by passing the flag introspection=False
to the Configurator
constructor in your application setup:
from pyramid.config import Configurator
config = Configurator(..., introspection=False)
When introspection
is False
, all introspectables generated by configuration directives are thrown away.