diff options
| -rw-r--r-- | CHANGES.txt | 9 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/latexindex.rst | 1 | ||||
| -rw-r--r-- | docs/narr/introspector.rst | 89 |
4 files changed, 100 insertions, 0 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 6fdb03635..6ba72fc06 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -28,6 +28,10 @@ Features - Configuration conflict reporting is reported in a more understandable way ("Line 11 in file..." vs. a repr of a tuple of similar info). +- An configuration introspection system was added; see the narrative + documentation chapter entitled "Pyramid Configuration Introspection" for + more information. + - New APIs: ``pyramid.registry.Introspectable``, ``pyramid.config.Configurator.introspector``, ``pyramid.config.Configurator.introspectable``, @@ -103,6 +107,11 @@ Documentation - Minor updates to the ZODB Wiki tutorial. +- A narrative documentation chapter named "Extending Pyramid Configuration" + was added; it describes how to add a new directive, and how use the + ``pyramid.config.Configurator.action`` method within custom directives. It + also describes how to add introspectable objects. + Scaffolds --------- diff --git a/docs/index.rst b/docs/index.rst index f07e8eac2..ceb29d108 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -88,6 +88,7 @@ Narrative documentation in chapter form explaining how to use narr/security narr/hybrid narr/hooks + narr/introspector narr/extending narr/advconfig narr/extconfig diff --git a/docs/latexindex.rst b/docs/latexindex.rst index d74dbba79..4db5b64b2 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -55,6 +55,7 @@ Narrative Documentation narr/security narr/hybrid narr/hooks + narr/introspector narr/extending narr/advconfig narr/extconfig 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`` + |