diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/advconfig.rst | 133 | ||||
| -rw-r--r-- | docs/narr/extconfig.rst | 265 |
2 files changed, 196 insertions, 202 deletions
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 9ceaaa495..ba9bd1352 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -6,12 +6,11 @@ Advanced Configuration ====================== -To support application extensibility, the :app:`Pyramid` -:term:`Configurator`, by default, detects configuration conflicts and allows -you to include configuration imperatively from other packages or modules. It -also, by default, performs configuration in two separate phases. This allows -you to ignore relative configuration statement ordering in some -circumstances. +To support application extensibility, the :app:`Pyramid` :term:`Configurator` +by default detects configuration conflicts and allows you to include +configuration imperatively from other packages or modules. It also by default +performs configuration in two separate phases. This allows you to ignore +relative configuration statement ordering in some circumstances. .. index:: pair: configuration; conflict detection @@ -70,11 +69,11 @@ try to add another view to the configuration with the same set of server = make_server('0.0.0.0', 8080, app) server.serve_forever() -The application now has two conflicting view configuration statements. When -we try to start it again, it won't start. Instead, we'll receive a traceback -that ends something like this: +The application now has two conflicting view configuration statements. When we +try to start it again, it won't start. Instead we'll receive a traceback that +ends something like this: -.. code-block:: guess +.. code-block:: text :linenos: Traceback (most recent call last): @@ -94,19 +93,19 @@ that ends something like this: This traceback is trying to tell us: -- We've got conflicting information for a set of view configuration - statements (The ``For:`` line). +- We've got conflicting information for a set of view configuration statements + (The ``For:`` line). - There are two statements which conflict, shown beneath the ``For:`` line: ``config.add_view(hello_world. 'hello')`` on line 14 of ``app.py``, and ``config.add_view(goodbye_world, 'hello')`` on line 17 of ``app.py``. -These two configuration statements are in conflict because we've tried to -tell the system that the set of :term:`predicate` values for both view +These two configuration statements are in conflict because we've tried to tell +the system that the set of :term:`predicate` values for both view configurations are exactly the same. Both the ``hello_world`` and ``goodbye_world`` views are configured to respond under the same set of -circumstances. This circumstance: the :term:`view name` (represented by the -``name=`` predicate) is ``hello``. +circumstances. This circumstance, the :term:`view name` represented by the +``name=`` predicate, is ``hello``. This presents an ambiguity that :app:`Pyramid` cannot resolve. Rather than allowing the circumstance to go unreported, by default Pyramid raises a @@ -138,8 +137,7 @@ made by your application. Use the detail provided in the modify your configuration code accordingly. If you're getting a conflict while trying to extend an existing application, -and that application has a function which performs configuration like this -one: +and that application has a function which performs configuration like this one: .. code-block:: python :linenos: @@ -147,8 +145,8 @@ one: def add_routes(config): config.add_route(...) -Don't call this function directly with ``config`` as an argument. Instead, -use :meth:`pyramid.config.Configurator.include`: +Don't call this function directly with ``config`` as an argument. Instead, use +:meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: @@ -156,9 +154,9 @@ use :meth:`pyramid.config.Configurator.include`: config.include(add_routes) Using :meth:`~pyramid.config.Configurator.include` instead of calling the -function directly provides a modicum of automated conflict resolution, with -the configuration statements you define in the calling code overriding those -of the included function. +function directly provides a modicum of automated conflict resolution, with the +configuration statements you define in the calling code overriding those of the +included function. .. seealso:: @@ -169,10 +167,10 @@ Using ``config.commit()`` +++++++++++++++++++++++++ You can manually commit a configuration by using the -:meth:`~pyramid.config.Configurator.commit` method between configuration -calls. For example, we prevent conflicts from occurring in the application -we examined previously as the result of adding a ``commit``. Here's the -application that generates conflicts: +:meth:`~pyramid.config.Configurator.commit` method between configuration calls. +For example, we prevent conflicts from occurring in the application we examined +previously as the result of adding a ``commit``. Here's the application that +generates conflicts: .. code-block:: python :linenos: @@ -199,11 +197,12 @@ application that generates conflicts: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -We can prevent the two ``add_view`` calls from conflicting by issuing a call -to :meth:`~pyramid.config.Configurator.commit` between them: +We can prevent the two ``add_view`` calls from conflicting by issuing a call to +:meth:`~pyramid.config.Configurator.commit` between them: .. code-block:: python :linenos: + :emphasize-lines: 16 from wsgiref.simple_server import make_server from pyramid.config import Configurator @@ -230,21 +229,20 @@ to :meth:`~pyramid.config.Configurator.commit` between them: server.serve_forever() In the above example we've issued a call to -:meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` -calls. :meth:`~pyramid.config.Configurator.commit` will execute any pending +:meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` calls. +:meth:`~pyramid.config.Configurator.commit` will execute any pending configuration statements. Calling :meth:`~pyramid.config.Configurator.commit` is safe at any time. It -executes all pending configuration actions and leaves the configuration -action list "clean". +executes all pending configuration actions and leaves the configuration action +list "clean". -Note that :meth:`~pyramid.config.Configurator.commit` has no effect when -you're using an *autocommitting* configurator (see -:ref:`autocommitting_configurator`). +Note that :meth:`~pyramid.config.Configurator.commit` has no effect when you're +using an *autocommitting* configurator (see :ref:`autocommitting_configurator`). .. _autocommitting_configurator: -Using An Autocommitting Configurator +Using an Autocommitting Configurator ++++++++++++++++++++++++++++++++++++ You can also use a heavy hammer to circumvent conflict detection by using a @@ -278,17 +276,17 @@ Automatic Conflict Resolution If your code uses the :meth:`~pyramid.config.Configurator.include` method to include external configuration, some conflicts are automatically resolved. Configuration statements that are made as the result of an "include" will be -overridden by configuration statements that happen within the caller of -the "include" method. +overridden by configuration statements that happen within the caller of the +"include" method. -Automatic conflict resolution supports this goal: if a user wants to reuse a +Automatic conflict resolution supports this goal. If a user wants to reuse a Pyramid application, and they want to customize the configuration of this application without hacking its code "from outside", they can "include" a configuration function from the package and override only some of its configuration statements within the code that does the include. No conflicts will be generated by configuration statements within the code that does the -including, even if configuration statements in the included code would -conflict if it was moved "up" to the calling code. +including, even if configuration statements in the included code would conflict +if it was moved "up" to the calling code. Methods Which Provide Conflict Detection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -312,9 +310,9 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_resource_url_adapter`, and :meth:`~pyramid.config.Configurator.add_response_adapter`. -:meth:`~pyramid.config.Configurator.add_static_view` also indirectly -provides conflict detection, because it's implemented in terms of the -conflict-aware ``add_route`` and ``add_view`` methods. +:meth:`~pyramid.config.Configurator.add_static_view` also indirectly provides +conflict detection, because it's implemented in terms of the conflict-aware +``add_route`` and ``add_view`` methods. .. index:: pair: configuration; including from external sources @@ -324,10 +322,10 @@ conflict-aware ``add_route`` and ``add_view`` methods. Including Configuration from External Sources --------------------------------------------- -Some application programmers will factor their configuration code in such a -way that it is easy to reuse and override configuration statements. For -example, such a developer might factor out a function used to add routes to -his application: +Some application programmers will factor their configuration code in such a way +that it is easy to reuse and override configuration statements. For example, +such a developer might factor out a function used to add routes to their +application: .. code-block:: python :linenos: @@ -335,8 +333,8 @@ his application: def add_routes(config): config.add_route(...) -Rather than calling this function directly with ``config`` as an argument. -Instead, use :meth:`pyramid.config.Configurator.include`: +Rather than calling this function directly with ``config`` as an argument, +instead use :meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: @@ -363,21 +361,21 @@ the special name ``includeme``, which should perform configuration (like the :meth:`~pyramid.config.Configurator.include` can also accept a :term:`dotted Python name` to a function or a module. -.. note: See :ref:`the_include_tag` for a declarative alternative to - the :meth:`~pyramid.config.Configurator.include` method. +.. note:: See :ref:`the_include_tag` for a declarative alternative to the + :meth:`~pyramid.config.Configurator.include` method. .. _twophase_config: Two-Phase Configuration ----------------------- -When a non-autocommitting :term:`Configurator` is used to do configuration -(the default), configuration execution happens in two phases. In the first -phase, "eager" configuration actions (actions that must happen before all -others, such as registering a renderer) are executed, and *discriminators* -are computed for each of the actions that depend on the result of the eager -actions. In the second phase, the discriminators of all actions are compared -to do conflict detection. +When a non-autocommitting :term:`Configurator` is used to do configuration (the +default), configuration execution happens in two phases. In the first phase, +"eager" configuration actions (actions that must happen before all others, such +as registering a renderer) are executed, and *discriminators* are computed for +each of the actions that depend on the result of the eager actions. In the +second phase, the discriminators of all actions are compared to do conflict +detection. Due to this, for configuration methods that have no internal ordering constraints, execution order of configuration method calls is not important. @@ -401,15 +399,14 @@ Has the same result as: config.add_view('some.view', renderer='path_to_custom/renderer.rn') Even though the view statement depends on the registration of a custom -renderer, due to two-phase configuration, the order in which the -configuration statements are issued is not important. ``add_view`` will be -able to find the ``.rn`` renderer even if ``add_renderer`` is called after -``add_view``. +renderer, due to two-phase configuration, the order in which the configuration +statements are issued is not important. ``add_view`` will be able to find the +``.rn`` renderer even if ``add_renderer`` is called after ``add_view``. The same is untrue when you use an *autocommitting* configurator (see :ref:`autocommitting_configurator`). When an autocommitting configurator is -used, two-phase configuration is disabled, and configuration statements must -be ordered in dependency order. +used, two-phase configuration is disabled, and configuration statements must be +ordered in dependency order. Some configuration methods, such as :meth:`~pyramid.config.Configurator.add_route` have internal ordering @@ -420,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article, `"A Whirlwind Tour of Advanced +For more information, see the article `"A Whirlwind Tour of Advanced Configuration Tactics" -<http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_, +<http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_ in the Pyramid Cookbook. diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index a61eca7b7..fee8d0d3a 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -7,9 +7,9 @@ Extending Pyramid Configuration =============================== Pyramid allows you to extend its Configurator with custom directives. Custom -directives can use other directives, they can add a custom :term:`action`, -they can participate in :term:`conflict resolution`, and they can provide -some number of :term:`introspectable` objects. +directives can use other directives, they can add a custom :term:`action`, they +can participate in :term:`conflict resolution`, and they can provide some +number of :term:`introspectable` objects. .. index:: single: add_directive @@ -20,18 +20,17 @@ some number of :term:`introspectable` objects. Adding Methods to the Configurator via ``add_directive`` -------------------------------------------------------- -Framework extension writers can add arbitrary methods to a -:term:`Configurator` by using the -:meth:`pyramid.config.Configurator.add_directive` method of the configurator. -Using :meth:`~pyramid.config.Configurator.add_directive` makes it possible to -extend a Pyramid configurator in arbitrary ways, and allows it to perform -application-specific tasks more succinctly. +Framework extension writers can add arbitrary methods to a :term:`Configurator` +by using the :meth:`pyramid.config.Configurator.add_directive` method of the +configurator. Using :meth:`~pyramid.config.Configurator.add_directive` makes it +possible to extend a Pyramid configurator in arbitrary ways, and allows it to +perform application-specific tasks more succinctly. The :meth:`~pyramid.config.Configurator.add_directive` method accepts two -positional arguments: a method name and a callable object. The callable -object is usually a function that takes the configurator instance as its -first argument and accepts other arbitrary positional and keyword arguments. -For example: +positional arguments: a method name and a callable object. The callable object +is usually a function that takes the configurator instance as its first +argument and accepts other arbitrary positional and keyword arguments. For +example: .. code-block:: python :linenos: @@ -48,8 +47,8 @@ For example: add_newrequest_subscriber) Once :meth:`~pyramid.config.Configurator.add_directive` is called, a user can -then call the added directive by its given name as if it were a built-in -method of the Configurator: +then call the added directive by its given name as if it were a built-in method +of the Configurator: .. code-block:: python :linenos: @@ -59,9 +58,9 @@ method of the Configurator: config.add_newrequest_subscriber(mysubscriber) -A call to :meth:`~pyramid.config.Configurator.add_directive` is often -"hidden" within an ``includeme`` function within a "frameworky" package meant -to be included as per :ref:`including_configuration` via +A call to :meth:`~pyramid.config.Configurator.add_directive` is often "hidden" +within an ``includeme`` function within a "frameworky" package meant to be +included as per :ref:`including_configuration` via :meth:`~pyramid.config.Configurator.include`. For example, if you put this code in a package named ``pyramid_subscriberhelpers``: @@ -72,8 +71,8 @@ code in a package named ``pyramid_subscriberhelpers``: config.add_directive('add_newrequest_subscriber', add_newrequest_subscriber) -The user of the add-on package ``pyramid_subscriberhelpers`` would then be -able to install it and subsequently do: +The user of the add-on package ``pyramid_subscriberhelpers`` would then be able +to install it and subsequently do: .. code-block:: python :linenos: @@ -91,13 +90,12 @@ Using ``config.action`` in a Directive If a custom directive can't do its work exclusively in terms of existing configurator methods (such as -:meth:`pyramid.config.Configurator.add_subscriber`, as above), the directive -may need to make use of the :meth:`pyramid.config.Configurator.action` -method. This method adds an entry to the list of "actions" that Pyramid will -attempt to process when :meth:`pyramid.config.Configurator.commit` is called. -An action is simply a dictionary that includes a :term:`discriminator`, -possibly a callback function, and possibly other metadata used by Pyramid's -action system. +:meth:`pyramid.config.Configurator.add_subscriber` as above), the directive may +need to make use of the :meth:`pyramid.config.Configurator.action` method. This +method adds an entry to the list of "actions" that Pyramid will attempt to +process when :meth:`pyramid.config.Configurator.commit` is called. An action is +simply a dictionary that includes a :term:`discriminator`, possibly a callback +function, and possibly other metadata used by Pyramid's action system. Here's an example directive which uses the "action" method: @@ -122,15 +120,15 @@ closure function named ``register`` is passed as the second argument named When the :meth:`~pyramid.config.Configurator.action` method is called, it appends an action to the list of pending configuration actions. All pending -actions with the same discriminator value are potentially in conflict with -one another (see :ref:`conflict_detection`). When the +actions with the same discriminator value are potentially in conflict with one +another (see :ref:`conflict_detection`). When the :meth:`~pyramid.config.Configurator.commit` method of the Configurator is called (either explicitly or as the result of calling :meth:`~pyramid.config.Configurator.make_wsgi_app`), conflicting actions are -potentially automatically resolved as per -:ref:`automatic_conflict_resolution`. If a conflict cannot be automatically -resolved, a :exc:`pyramid.exceptions.ConfigurationConflictError` is raised -and application startup is prevented. +potentially automatically resolved as per :ref:`automatic_conflict_resolution`. +If a conflict cannot be automatically resolved, a +:exc:`pyramid.exceptions.ConfigurationConflictError` is raised and application +startup is prevented. In our above example, therefore, if a consumer of our ``add_jammyjam`` directive did this: @@ -146,14 +144,14 @@ generated by the two calls are in direct conflict. Automatic conflict resolution cannot resolve the conflict (because no ``config.include`` is involved), and the user provided no intermediate :meth:`pyramid.config.Configurator.commit` call between the calls to -``add_jammyjam`` to ensure that the successive calls did not conflict with -each other. +``add_jammyjam`` to ensure that the successive calls did not conflict with each +other. This demonstrates the purpose of the discriminator argument to the action method: it's used to indicate a uniqueness constraint for an action. Two actions with the same discriminator will conflict unless the conflict is -automatically or manually resolved. A discriminator can be any hashable -object, but it is generally a string or a tuple. *You use a discriminator to +automatically or manually resolved. A discriminator can be any hashable object, +but it is generally a string or a tuple. *You use a discriminator to declaratively ensure that the user doesn't provide ambiguous configuration statements.* @@ -169,21 +167,20 @@ appended to the pending actions list. When the pending configuration actions are processed during :meth:`~pyramid.config.Configurator.commit`, and no conflicts occur, the *callable* provided as the second argument to the :meth:`~pyramid.config.Configurator.action` method within ``add_jammyjam`` is -called with no arguments. The callable in ``add_jammyjam`` is the -``register`` closure function. It simply sets the value -``config.registry.jammyjam`` to whatever the user passed in as the -``jammyjam`` argument to the ``add_jammyjam`` function. Therefore, the -result of the user's call to our directive will set the ``jammyjam`` -attribute of the registry to the string ``first``. *A callable is used by a -directive to defer the result of a user's call to the directive until -conflict detection has had a chance to do its job*. +called with no arguments. The callable in ``add_jammyjam`` is the ``register`` +closure function. It simply sets the value ``config.registry.jammyjam`` to +whatever the user passed in as the ``jammyjam`` argument to the +``add_jammyjam`` function. Therefore, the result of the user's call to our +directive will set the ``jammyjam`` attribute of the registry to the string +``first``. *A callable is used by a directive to defer the result of a user's +call to the directive until conflict detection has had a chance to do its job*. Other arguments exist to the :meth:`~pyramid.config.Configurator.action` -method, including ``args``, ``kw``, ``order``, and ``introspectables``. +method, including ``args``, ``kw``, ``order``, and ``introspectables``. -``args`` and ``kw`` exist as values, which, if passed, will be used as -arguments to the ``callable`` function when it is called back. For example -our directive might use them like so: +``args`` and ``kw`` exist as values, which if passed will be used as arguments +to the ``callable`` function when it is called back. For example, our +directive might use them like so: .. code-block:: python :linenos: @@ -198,31 +195,33 @@ our directive might use them like so: In the above example, when this directive is used to generate an action, and that action is committed, ``config.registry.jammyjam_args`` will be set to ``('one',)`` and ``config.registry.jammyjam_kw`` will be set to -``{'two':'two'}``. ``args`` and ``kw`` are honestly not very useful when -your ``callable`` is a closure function, because you already usually have -access to every local in the directive without needing them to be passed -back. They can be useful, however, if you don't use a closure as a callable. +``{'two':'two'}``. ``args`` and ``kw`` are honestly not very useful when your +``callable`` is a closure function, because you already usually have access to +every local in the directive without needing them to be passed back. They can +be useful, however, if you don't use a closure as a callable. ``order`` is a crude order control mechanism. ``order`` defaults to the integer ``0``; it can be set to any other integer. All actions that share an order will be called before other actions that share a higher order. This makes it possible to write a directive with callable logic that relies on the -execution of the callable of another directive being done first. For -example, Pyramid's :meth:`pyramid.config.Configurator.add_view` directive -registers an action with a higher order than the +execution of the callable of another directive being done first. For example, +Pyramid's :meth:`pyramid.config.Configurator.add_view` directive registers an +action with a higher order than the :meth:`pyramid.config.Configurator.add_route` method. Due to this, the -``add_view`` method's callable can assume that, if a ``route_name`` was -passed to it, that a route by this name was already registered by -``add_route``, and if such a route has not already been registered, it's a -configuration error (a view that names a nonexistent route via its -``route_name`` parameter will never be called). As of Pyramid 1.6 it is -possible for one action to invoke another. See :ref:`ordering_actions` for -more information. - -``introspectables`` is a sequence of :term:`introspectable` objects. You can -pass a sequence of introspectables to the -:meth:`~pyramid.config.Configurator.action` method, which allows you to -augment Pyramid's configuration introspection system. +``add_view`` method's callable can assume that, if a ``route_name`` was passed +to it, that a route by this name was already registered by ``add_route``, and +if such a route has not already been registered, it's a configuration error (a +view that names a nonexistent route via its ``route_name`` parameter will never +be called). + +.. versionchanged:: 1.6 + As of Pyramid 1.6 it is possible for one action to invoke another. See + :ref:`ordering_actions` for more information. + +Finally, ``introspectables`` is a sequence of :term:`introspectable` objects. +You can pass a sequence of introspectables to the +:meth:`~pyramid.config.Configurator.action` method, which allows you to augment +Pyramid's configuration introspection system. .. _ordering_actions: @@ -233,18 +232,17 @@ In Pyramid every :term:`action` has an inherent ordering relative to other actions. The logic within actions is deferred until a call to :meth:`pyramid.config.Configurator.commit` (which is automatically invoked by :meth:`pyramid.config.Configurator.make_wsgi_app`). This means you may call -``config.add_view(route_name='foo')`` **before** -``config.add_route('foo', '/foo')`` because nothing actually happens until -commit-time. During a commit cycle conflicts are resolved, actions are ordered -and executed. +``config.add_view(route_name='foo')`` **before** ``config.add_route('foo', +'/foo')`` because nothing actually happens until commit-time. During a commit +cycle, conflicts are resolved, and actions are ordered and executed. By default, almost every action in Pyramid has an ``order`` of :const:`pyramid.config.PHASE3_CONFIG`. Every action within the same order-level -will be executed in the order it was called. -This means that if an action must be reliably executed before or after another -action, the ``order`` must be defined explicitly to make this work. For -example, views are dependent on routes being defined. Thus the action created -by :meth:`pyramid.config.Configurator.add_route` has an ``order`` of +will be executed in the order it was called. This means that if an action must +be reliably executed before or after another action, the ``order`` must be +defined explicitly to make this work. For example, views are dependent on +routes being defined. Thus the action created by +:meth:`pyramid.config.Configurator.add_route` has an ``order`` of :const:`pyramid.config.PHASE2_CONFIG`. Pre-defined Phases @@ -252,8 +250,8 @@ Pre-defined Phases :const:`pyramid.config.PHASE0_CONFIG` -- This phase is reserved for developers who want to execute actions prior - to Pyramid's core directives. +- This phase is reserved for developers who want to execute actions prior to + Pyramid's core directives. :const:`pyramid.config.PHASE1_CONFIG` @@ -274,17 +272,17 @@ Pre-defined Phases - The default for all builtin or custom directives unless otherwise specified. -Calling Actions From Actions +Calling Actions from Actions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 1.6 -Pyramid's configurator allows actions to be added during a commit-cycle as -long as they are added to the current or a later ``order`` phase. This means -that your custom action can defer decisions until commit-time and then do -things like invoke :meth:`pyramid.config.Configurator.add_route`. It can also -provide better conflict detection if your addon needs to call more than one -other action. +Pyramid's configurator allows actions to be added during a commit-cycle as long +as they are added to the current or a later ``order`` phase. This means that +your custom action can defer decisions until commit-time and then do things +like invoke :meth:`pyramid.config.Configurator.add_route`. It can also provide +better conflict detection if your addon needs to call more than one other +action. For example, let's make an addon that invokes ``add_route`` and ``add_view``, but we want it to conflict with any other call to our addon: @@ -304,12 +302,12 @@ but we want it to conflict with any other call to our addon: config.action(('auto route', name), register, order=PHASE0_CONFIG) Now someone else can use your addon and be informed if there is a conflict -between this route and another, or two calls to ``add_auto_route``. -Notice how we had to invoke our action **before** ``add_view`` or -``add_route``. If we tried to invoke this afterward, the subsequent calls to -``add_view`` and ``add_route`` would cause conflicts because that phase had -already been executed, and the configurator cannot go back in time to add more -views during that commit-cycle. +between this route and another, or two calls to ``add_auto_route``. Notice how +we had to invoke our action **before** ``add_view`` or ``add_route``. If we +tried to invoke this afterward, the subsequent calls to ``add_view`` and +``add_route`` would cause conflicts because that phase had already been +executed, and the configurator cannot go back in time to add more views during +that commit-cycle. .. code-block:: python :linenos: @@ -341,16 +339,16 @@ All built-in Pyramid directives (such as 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. +values for the arguments passed into it. 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 against which +routes a particular view is registered. 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 :term:`introspectable` -objects is passed to the :meth:`~pyramid.config.Configurator.action` method. -Here's an example of a directive which uses introspectables: +Introspection values are set when a sequence of :term:`introspectable` objects +is passed to the :meth:`~pyramid.config.Configurator.action` method. Here's an +example of a directive which uses introspectables: .. code-block:: python :linenos: @@ -370,9 +368,9 @@ Here's an example of a directive which uses introspectables: config.add_directive('add_jammyjam', add_jammyjam) If you notice, the above directive uses the ``introspectable`` attribute of a -Configurator (:attr:`pyramid.config.Configurator.introspectable`) to create -an introspectable object. The introspectable object's constructor requires -at least four arguments: the ``category_name``, the ``discriminator``, the +Configurator (:attr:`pyramid.config.Configurator.introspectable`) to create an +introspectable object. The 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 @@ -392,19 +390,19 @@ The ``type_name`` is a value that can be used to subtype this introspectable within its category 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 +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. +``introspectable`` keyword argument. This associates this introspectable with +the action. Introspection tools will then display this introspectable in their +index. Introspectable Relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -435,30 +433,29 @@ Two introspectables may have relationships between each other. config.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. +introspectables: the first is related to the ``value`` passed to the directive, +and 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 -(:meth:`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. +(:meth:`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. +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 and vice versa. |