From 9d97b654057e621c4928fe597053d54aa5f63a8c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 03:00:15 -0500 Subject: add skeleton for using introspection chapter --- docs/narr/introspector.rst | 89 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/narr/introspector.rst (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst new file mode 100644 index 000000000..3cbafa010 --- /dev/null +++ b/docs/narr/introspector.rst @@ -0,0 +1,89 @@ +.. 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`. This 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: + +.. code-block:: python + :linenos: + + from pyramid.view import view_config + from pyramid.response import Response + + @view_config(route_name='foo') + @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['accept'])) + +This view will return a response that contains the "accept" argument provided +to the ``add_route`` method of the route which matched when the view was +called. It used 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 used the +returned introspectable to obtain an "accept" value. + +The introspector has a number of other query-related methods: see +:class:`pyramid.interfaces.IIntrospector` for more information. The +introspectable returned by the query methods of the introspector has methods +and attributes described by :class:`pyramid.interfaces.IIntrospectable`. + +Concrete Introspection Categories +--------------------------------- + +This is a list of concrete introspection categories provided by Pyramid. + +``subscribers`` + +``response adapters`` + +``asset overrides`` + +``root factories`` + +``session factory`` + +``request factory`` + +``locale negotiator`` + +``translation directories`` + +``renderer factories`` + +``routes`` + +``authentication policy`` + +``authorization policy`` + +``default permission`` + +``tweens (implicit)`` + +``views`` + +``templates`` + +``permissions`` + +``view mapper`` + -- cgit v1.2.3 From 5224059f71d0ad592a611c196a3af7cbd1dc828f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 16:24:34 -0500 Subject: add more content to the introspectables narr chapter; adjust introspection registrations while doing so --- docs/narr/introspector.rst | 425 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 401 insertions(+), 24 deletions(-) (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 3cbafa010..8adfde7d1 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -9,16 +9,17 @@ 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`. This 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 +: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: +Here's an example of using Pyramid's introspector from within a view +callable: .. code-block:: python :linenos: @@ -26,64 +27,440 @@ Here's an example of using Pyramid's introspector: from pyramid.view import view_config from pyramid.response import Response - @view_config(route_name='foo') @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['accept'])) + return Response(str(route_intr['pattern'])) -This view will return a response that contains the "accept" argument provided -to the ``add_route`` method of the route which matched when the view was -called. It used 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 used the -returned introspectable to obtain an "accept" value. +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 introspector has a number of other query-related methods: see -:class:`pyramid.interfaces.IIntrospector` for more information. The -introspectable returned by the query methods of the introspector has methods -and attributes described by :class:`pyramid.interfaces.IIntrospectable`. +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. -Concrete Introspection Categories ---------------------------------- +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`` -This is a list of concrete introspection categories provided by Pyramid. + 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`` -``asset overrides`` + 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`` -``translation directories`` + 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`` -``tweens (implicit)`` + 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`` -``templates`` + 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 + -- cgit v1.2.3 From 58c01ff8863971f81db59d437d49fd9e97b59e5c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 19:37:38 -0500 Subject: flesh out categories more --- docs/narr/introspector.rst | 80 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 69 insertions(+), 11 deletions(-) (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 8adfde7d1..ac0859164 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -15,6 +15,10 @@ 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 ---------------------- @@ -86,6 +90,12 @@ The important attributes shared by all introspectables are the following: 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. @@ -107,7 +117,7 @@ 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 + :meth:`pyramid.config.Configurator.add_subscriber` (or the decorator equivalent); each will have the following data. ``subscriber`` @@ -138,8 +148,6 @@ introspectables in categories not described here. ``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 @@ -435,8 +443,6 @@ introspectables in categories not described here. ``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 @@ -450,17 +456,69 @@ introspectables in categories not described here. ``asset overrides`` - XXX + 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`` - XXX + 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). -``tweens (implicit)`` +Toolbar Introspection +--------------------- - XXX +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: -``tweens (explicit)`` +.. image:: tb_introspector.png - XXX -- cgit v1.2.3 From b40fb8b26fe37102b076cd2310ea7a3fe8b79311 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 21:04:24 -0500 Subject: add a noop introspector (allow introspection to be turned off) --- docs/narr/introspector.rst | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index ac0859164..71b41773c 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -512,8 +512,8 @@ introspectables in categories not described here. The ``over`` argument passed to ``add_tween`` (a string). -Toolbar Introspection ---------------------- +Introspection in the Toolbar +---------------------------- The Pyramid debug toolbar (part of the ``pyramid_debugtoolbar`` package) provides a canned view of all registered introspectables and their @@ -521,4 +521,20 @@ 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 the +framework 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. -- cgit v1.2.3 From d8e504cb1d486b9cd1caea7437ff212f92ed4fdb Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 21:25:43 -0500 Subject: make add_route generate the right request methods introspection value --- docs/narr/introspector.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 71b41773c..1285a4cf1 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -258,7 +258,8 @@ introspectables in categories not described here. ``request_methods`` A sequence of request method names implied by the ``request_method`` - argument passed to ``add_route``. + argument passed to ``add_route`` or the value ``None`` if a + ``request_method`` argument was not supplied. ``path_info`` @@ -361,7 +362,8 @@ introspectables in categories not described here. ``request_methods`` A sequence of request method names implied by the ``request_method`` - argument passed to ``add_view``. + argument passed to ``add_view`` or the value ``None`` if a + ``request_method`` argument was not supplied. ``route_name`` -- cgit v1.2.3 From fc3e425e64420fc05dc4fa1ebf83951934a2f005 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 21:29:25 -0500 Subject: wording --- docs/narr/introspector.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/introspector.rst') diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 1285a4cf1..cfc6144dd 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -536,7 +536,7 @@ constructor in your application setup: from pyramid.registry import noop_introspector config = Configurator(..., introspector=noop_introspector) -When the noop introspector is active, all introspectables generated by the -framework 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. +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. -- cgit v1.2.3