Michael Merickel
2016-09-13 0026fed16fb8fa31e436b5de22aed0fa62af41c2
Merge pull request #2765 from mmerickel/backports/2764

document more clearly the ``__call__`` method on route and view prediā€¦
2 files modified
36 ■■■■ changed files
CHANGES.txt 7 ●●●●● patch | view | raw | blame | history
docs/narr/hooks.rst 29 ●●●● patch | view | raw | blame | history
CHANGES.txt
@@ -1,3 +1,10 @@
unreleased
==========
- Fix an inconsistency in the documentation between view predicates and
  route predicates and highlight the differences in their APIs.
  See https://github.com/Pylons/pyramid/pull/2765
.. _changes_1.7.3:
1.7.3 (2016-08-17)
docs/narr/hooks.rst
@@ -1481,7 +1481,7 @@
        phash = text
        def __call__(self, context, request):
            return getattr(context, 'content_type', None) == self.val
            return request.content_type == self.val
The constructor of a predicate factory takes two arguments: ``val`` and
``config``.  The ``val`` argument will be the argument passed to
@@ -1500,13 +1500,28 @@
output anywhere, it just informs the uniqueness constraints for view
configuration.
The ``__call__`` method of a predicate factory must accept a resource
(``context``) and a request, and must return ``True`` or ``False``.  It is the
"meat" of the predicate.
The ``__call__`` method differs depending on whether the predicate is used as
a :term:`view predicate` or a :term:`route predicate`:
You can use the same predicate factory as both a view predicate and as a route
predicate, but you'll need to call ``add_view_predicate`` and
``add_route_predicate`` separately with the same factory.
- When used as a route predicate, the ``__call__`` signature is
  ``(info, request)``. The ``info`` object is a dictionary containing two
  keys: ``match`` and ``route``. ``info['match']`` is the matchdict containing
  the patterns matched in the route pattern. ``info['route']`` is the
  :class:`pyramid.interfaces.IRoute` object for the current route.
- When used as a view predicate, the ``__call__`` signature is
  ``(context, request)``. The ``context`` is the result of :term:`traversal`
  performed using either the route's :term:`root factory` or the app's
  :term:`default root factory`.
In both cases the ``__call__`` method is expected to return ``True`` or
``False``.
It is possible to use the same predicate factory as both a view predicate and
as a route predicate, but they'll need to handle the ``info`` or ``context``
argument specially (many predicates do not need this argument) and you'll need
to call ``add_view_predicate`` and ``add_route_predicate`` separately with
the same factory.
.. _subscriber_predicates: