From c746ba4d0893ed7f4322492fdba548f3cd2a1ac5 Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Fri, 3 Aug 2012 00:44:41 -0700 Subject: Adding helpful link to installing chapter from first app --- docs/narr/firstapp.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 1ca188d7e..a86826d86 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -8,7 +8,8 @@ Creating Your First :app:`Pyramid` Application In this chapter, we will walk through the creation of a tiny :app:`Pyramid` application. After we're finished creating the application, we'll explain in -more detail how it works. +more detail how it works. It assumes you already have :app:`Pyramid` installed. +If you do not, head over to the :ref:`installing_chapter` section. .. _helloworld_imperative: -- cgit v1.2.3 From 0196b2a06ef66d2e8b33a03cc84373ab84ba44be Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 6 Aug 2012 00:48:29 -0400 Subject: add docs for third-party view predicates --- docs/narr/hooks.rst | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 332805152..bdd968362 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1232,3 +1232,97 @@ Displaying Tween Ordering The ``ptweens`` command-line utility can be used to report the current implict and explicit tween chains used by an application. See :ref:`displaying_tweens`. + +.. _registering_thirdparty_predicates: + +Adding A Third Party View or Route Predicate +-------------------------------------------- + +View and route predicates used during view configuration allow you to narrow +the set of circumstances under which a view or route will match. For +example, the ``request_method`` view predicate can be used to ensure a view +callable is only invoked when the request's method is ``POST``: + +.. code-block:: python + + @view_config(request_method='POST') + def someview(request): + ... + +Likewise, a similar predicate can be used as a *route* predicate: + +.. code-block:: python + + config.add_route('name', '/foo', request_method='POST') + +Many other built-in predicates exists (``request_param``, and others). You +can add third-party predicates to the list of available predicates by using +one of :meth:`pyramid.config.Configurator.add_view_predicate` or +:meth:`pyramid.config.Configurator.add_route_predicate`. The former adds a +view predicate, the latter a route predicate. + +When using one of those APIs, you pass a *name* and a *factory* to add a +predicate during Pyramid's configuration stage. For example: + +.. code-block:: python + + config.add_view_predicate('content_type', ContentTypePredicate) + +The above example adds a new predicate named ``content_type`` to the list of +available predicates for views. This will allow the following view +configuration statement to work: + +.. code-block:: python + :linenos: + + @view_config(content_type='File') + def aview(request): ... + +The first argument to :meth:`pyramid.config.Configurator.add_view_predicate`, +the name, is a string representing the name that is expected to be passed to +``view_config`` (or its imperative analogue ``add_view``). + +The second argument is a predicate factory. A predicate factory is most +often a class with a constructor (``__init__``), a ``text`` method, a +``phash`` method and a ``__call__`` method. For example: + +.. code-block:: python + :linenos: + + class ContentTypePredicate(object): + def __init__(self, val, config): + self.val + + def text(self): + return 'content_type = %s' % (self.val,) + + phash = text + + def __call__(self, context, request): + return getattr(context, 'content_type', None) == self.val + +The constructor of a predicate factory takes two arguments: ``val`` and +``config``. The ``val`` argument will be the argument passed to +``view_config`` (or ``add_view``). In the example above, it will be the +string ``File``. The second arg, ``config`` will be the Configurator +instance at the time of configuration. + +The ``text`` method must return a string. It should be useful to describe +the behavior of the predicate in error messages. + +The ``phash`` method must return a string or a sequence of strings. It's +most often the same as ``text``, as long as ``text`` uniquely describes the +predicate's name and the value passed to the constructor. If ``text`` is +more general, or doesn't describe things that way, ``phash`` should return a +string with the name and the value serialized. The result of ``phash`` is +not seen in 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. + +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. + -- cgit v1.2.3 From cff71c316eb8b77b936bfc14a29d7ff9727edf70 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 6 Aug 2012 00:05:12 -0500 Subject: garden --- docs/narr/hooks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index bdd968362..9482bfcf8 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1291,7 +1291,7 @@ often a class with a constructor (``__init__``), a ``text`` method, a class ContentTypePredicate(object): def __init__(self, val, config): - self.val + self.val = val def text(self): return 'content_type = %s' % (self.val,) -- cgit v1.2.3 From 5664c428e22d73f8b4315b678588150d9bb2f0f5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 6 Aug 2012 11:10:15 -0400 Subject: add as-of-version notes --- docs/narr/hooks.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index bdd968362..73ee655ea 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1238,6 +1238,10 @@ implict and explicit tween chains used by an application. See Adding A Third Party View or Route Predicate -------------------------------------------- +.. note:: + + Third-party predicates are a feature new as of Pyramid 1.4. + View and route predicates used during view configuration allow you to narrow the set of circumstances under which a view or route will match. For example, the ``request_method`` view predicate can be used to ensure a view -- cgit v1.2.3