diff options
Diffstat (limited to 'docs/narr/extconfig.rst')
| -rw-r--r-- | docs/narr/extconfig.rst | 25 |
1 files changed, 15 insertions, 10 deletions
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index 4468e95b4..570d20ec7 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -140,17 +140,22 @@ directive did this: config.add_jammyjam('first') config.add_jammyjam('second') -When the action list was committed, the user's application would not start, -because the discriminators of the actions generated by the two calls are in -direct conflict. Automatic conflict resolution cannot resolve the conflict, -and the user provided no intermediate +When the action list was committed resulting from the set of calls above, our +user's application would not start, because the discriminators of the actions +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. This is the purpose of the discriminator argument to the action +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. +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.* But let's imagine that a consumer of ``add_jammyjam`` used it in such a way that no configuration conflicts are generated. @@ -160,7 +165,7 @@ that no configuration conflicts are generated. config.add_jammyjam('first') -What happens then? When the ``add_jammyjam`` method is called, an action is +What happens now? When the ``add_jammyjam`` method is called, an action is 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 @@ -170,9 +175,9 @@ called with no arguments. The callable in ``add_jammyjam`` is the ``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 a directive until conflict -detection has had a chance to do its job. +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``. |