From 9ec766cf34014de1e357a449133830ff944efb19 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 12 Aug 2011 03:08:54 -0500 Subject: Updated the docs with the new over/under tuples. --- docs/narr/hooks.rst | 16 ++++++++++++---- pyramid/config.py | 18 ++++++++++++------ 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index f81385c93..fafb407d3 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -948,6 +948,10 @@ Allowable values for ``under`` or ``over`` (or both) are: - One of the constants :attr:`pyramid.tweens.MAIN`, :attr:`pyramid.tweens.INGRESS`, or :attr:`pyramid.tweens.EXCVIEW`. +- An iterable of any combination of the above. This allows the user to specify + fallbacks if the desired tween is not included, as well as compatibility + with multiple other tweens. + Effectively, ``under`` means "closer to the main Pyramid application than", ``over`` means "closer to the request ingress than". @@ -999,10 +1003,14 @@ this:: Specifying neither ``over`` nor ``under`` is equivalent to specifying ``under=INGRESS``. -If an ``under`` or ``over`` value is provided that does not match a tween -factory dotted name or alias in the current configuration, that value will be -ignored. It is not an error to provide an ``under`` or ``over`` value that -matches an unused tween factory. +If all options for ``under`` (or ``over``) cannot be found in the current +configuration, it is an error. If some options are specified purely for +compatibilty with other tweens, just add a fallback of MAIN or INGRESS. +For example, ``under=('someothertween', 'someothertween2', INGRESS)``. +This constraint will require the tween to be located under both the +'someothertween' tween, the 'someothertween2' tween, and INGRESS. If any of +these is not in the current configuration, this constraint will only organize +itself based on the tweens that are present. :meth:`~pyramid.config.Configurator.add_tween` also accepts an ``alias`` argument. If ``alias`` is not ``None``, should be a string. The string will diff --git a/pyramid/config.py b/pyramid/config.py index d6e9fd11c..3c6e8db6f 100644 --- a/pyramid/config.py +++ b/pyramid/config.py @@ -996,8 +996,9 @@ class Configurator(object): - One of the constants :attr:`pyramid.tweens.MAIN`, :attr:`pyramid.tweens.INGRESS`, or :attr:`pyramid.tweens.EXCVIEW`. - - A tuple of any combination of the above. This allows the user - to specify fallbacks if the desired tween is not included. + - An iterable of any combination of the above. This allows the user + to specify fallbacks if the desired tween is not included, as well + as compatibility with multiple other tweens. ``under`` means 'closer to the main Pyramid application than', ``over`` means 'closer to the request ingress than'. @@ -1011,10 +1012,15 @@ class Configurator(object): fictional) 'someothertween' tween factory (which was presumably added via ``add_tween(factory, alias='someothertween')``). - If an ``under`` or ``over`` value is provided that does not match a - tween factory dotted name or alias in the current configuration, that - value will be ignored. It is not an error to provide an ``under`` or - ``over`` value that matches an unused tween factory. + If all options for ``under`` (or ``over``) cannot be found in the + current configuration, it is an error. If some options are specified + purely for compatibilty with other tweens, just add a fallback of + MAIN or INGRESS. For example, + ``under=('someothertween', 'someothertween2', INGRESS)``. + This constraint will require the tween to be located under both the + 'someothertween' tween, the 'someothertween2' tween, and INGRESS. If + any of these is not in the current configuration, this constraint will + only organize itself based on the tweens that are present. Specifying neither ``over`` nor ``under`` is equivalent to specifying ``under=INGRESS``. -- cgit v1.2.3