33.3.ADDING CONFIGURATION INTROSPECTION

33.3Adding Configuration Introspection

latex-note.png

The introspection subsystem is new in Pyramid 1.3.

Pyramid provides a configuration introspection system that can be used by debugging tools to provide visibility into the configuration of a running application.

All built-in Pyramid directives (such as pyramid.config.Configurator.add_view() and pyramid.config.Configurator.add_route()) register a set of introspectables when called. For example, when you register a view via add_view, the directive registers at least one introspectable: an introspectable about the view registration itself, providing human-consumable values for the arguments it was passed. You can later use the introspection query system to determine whether a particular view uses a renderer, or whether a particular view is limited to a particular request method, or which routes a particular view is registered against. The Pyramid “debug toolbar” makes use of the introspection system in various ways to display information to Pyramid developers.

Introspection values are set when a sequence of introspectable objects is passed to the action() method. Here’s an example of a directive which uses introspectables:

1 def add_jammyjam(config, value):

2def register():

3config.registry.jammyjam = value

4intr = config.introspectable(category_name=’jammyjams’,

8intr[’value’] = value

9config.action(’jammyjam’, register, introspectables=(intr,))

10

11if __name__ == ’__main__’:

12config = Configurator()

13config.add_directive(’add_jammyjam’, add_jammyjam)

If you notice, the above directive uses the introspectable attribute of a Configurator (pyramid.config.Configurator.introspectable) to create an introspectable object. The

373

33. EXTENDING PYRAMID CONFIGURATION

introspectable object’s constructor requires at least four arguments: the category_name, the discriminator, the title, and the type_name.

The category_name is a string representing the logical category for this introspectable. Usually the category_name is a pluralization of the type of object being added via the action.

The discriminator is a value unique within the category (unlike the action discriminator, which must be unique within the entire set of actions). It is typically a string or tuple representing the values unique to this introspectable within the category. It is used to generate links and as part of a relationshipforming target for other introspectables.

The title is a human-consumable string that can be used by introspection system frontends to show a friendly summary of this introspectable.

The type_name is a value that can be used to subtype this introspectable within its category for for sorting and presentation purposes. It can be any value.

An introspectable is also dictionary-like. It can contain any set of key/value pairs, typically related to the arguments passed to its related directive. While the category_name, discriminator, title and type_name are metadata about the introspectable, the values provided as key/value pairs are the actual data provided by the introspectable. In the above example, we set the value key to the value of the value argument passed to the directive.

Our directive above mutates the introspectable, and passes it in to the action method as the first element of a tuple as the value of the introspectable keyword argument. This associates this introspectable with the action. Introspection tools will then display this introspectable in their index.

33.3.1 Introspectable Relationships

Two introspectables may have relationships between each other.

1 def add_jammyjam(config, value, template):

2def register():

3config.registry.jammyjam = (value, template)

4intr = config.introspectable(category_name=’jammyjams’,

8intr[’value’] = value

9tmpl_intr = config.introspectable(category_name=’jammyjam templates’,

374

33.3. ADDING CONFIGURATION INTROSPECTION

13tmpl_intr[’value’] = template

14intr.relate(’jammyjam templates’, template)

15config.action(’jammyjam’, register, introspectables=(intr, tmpl_intr))

16

17if __name__ == ’__main__’:

18config = Configurator()

19config.add_directive(’add_jammyjam’, add_jammyjam)

In the above example, the add_jammyjam directive registers two introspectables. The first is related to the value passed to the directive; the second is related to the template passed to the directive. If you believe a concept within a directive is important enough to have its own introspectable, you can cause the same directive to register more than one introspectable, registering one introspectable for the “main idea” and another for a related concept.

The call to intr.relate above (pyramid.interfaces.IIntrospectable.relate()) is passed two arguments: a category name and a directive. The example above effectively indicates that the directive wishes to form a relationship between the intr introspectable and the tmpl_intr introspectable; the arguments passed to relate are the category name and discriminator of the tmpl_intr introspectable.

Relationships need not be made between two introspectables created by the same directive. Instead, a relationship can be formed between an introspectable created in one directive and another introspectable created in another by calling relate on either side with the other directive’s category name and discriminator. An error will be raised at configuration commit time if you attempt to relate an introspectable with another nonexistent introspectable, however.

Introspectable relationships will show up in frontend system renderings of introspection values. For example, if a view registration names a route name, the introspectable related to the view callable will show a reference to the route to which it relates to and vice versa.

375

33. EXTENDING PYRAMID CONFIGURATION

376