From f564808a72d2720888525f6684dc79cc2affb6e9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 24 Jan 2013 00:56:50 -0800 Subject: Add source code snippets to supply context for the narrative. --- docs/tutorials/wiki/definingviews.rst | 37 ++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index efcc7bf21..4dedf4320 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -71,6 +71,13 @@ and a final view named ``edit_page`` will allow a page to be edited. The ``view_wiki`` view function ------------------------------- +Here is the code for the ``view_wiki`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 12-14 + :language: python + The ``view_wiki`` function will be configured to respond as the default view callable for a Wiki resource. We'll provide it with a ``@view_config`` decorator which names the class ``tutorial.models.Wiki`` as its context. @@ -84,16 +91,22 @@ The ``view_wiki`` view callable always redirects to the URL of a Page resource named "FrontPage". To do so, it returns an instance of the :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement the :class:`pyramid.interfaces.IResponse` interface like -:class:`pyramid.response.Response` does). The -:meth:`pyramid.request.Request.resource_url` API. +:class:`pyramid.response.Response` does). :meth:`pyramid.request.Request.resource_url` constructs a URL to the -``FrontPage`` page resource (e.g. ``http://localhost:6543/FrontPage``), and +``FrontPage`` page resource (i.e., ``http://localhost:6543/FrontPage``), and uses it as the "location" of the HTTPFound response, forming an HTTP redirect. The ``view_page`` view function ------------------------------- +Here is the code for the ``view_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 16-33 + :language: python + The ``view_page`` function will be configured to respond as the default view of a Page resource. We'll provide it with a ``@view_config`` decorator which names the class ``tutorial.models.Page`` as its context. This means that @@ -101,7 +114,7 @@ when a Page resource is the context, and no :term:`view name` exists in the request, this view will be used. We inform :app:`Pyramid` this view will use the ``templates/view.pt`` template file as a ``renderer``. -The ``view_page`` function generates the :term:`ReStructuredText` body of a +The ``view_page`` function generates the :term:`reStructuredText` body of a page (stored as the ``data`` attribute of the context passed to the view; the context will be a Page resource) as HTML. Then it substitutes an HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular @@ -140,6 +153,13 @@ callable. In the ``view_wiki`` view callable, we unconditionally return a The ``add_page`` view function ------------------------------ +Here is the code for the ``add_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 35-50 + :language: python + The ``add_page`` function will be configured to respond when the context resource is a Wiki and the :term:`view name` is ``add_page``. We'll provide it with a ``@view_config`` decorator which names the string ``add_page`` as @@ -171,7 +191,7 @@ we're trying to add. If the view rendering is *not* a result of a form submission (if the expression ``'form.submitted' in request.params`` is ``False``), the view renders a template. To do so, it generates a "save url" which the template -use as the form post URL during rendering. We're lazy here, so we're trying +uses as the form post URL during rendering. We're lazy here, so we're trying to use the same template (``templates/edit.pt``) for the add view as well as the page edit view. To do so, we create a dummy Page resource object in order to satisfy the edit form's desire to have *some* page object exposed as @@ -187,6 +207,13 @@ the page body, and save it into "our context" (the Wiki) using the The ``edit_page`` view function ------------------------------- +Here is the code for the ``edit_page`` view function and its decorator, which +will be added to ``views.py``: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 52-60 + :language: python + The ``edit_page`` function will be configured to respond when the context is a Page resource and the :term:`view name` is ``edit_page``. We'll provide it with a ``@view_config`` decorator which names the string ``edit_page`` as its -- cgit v1.2.3 From 9db1a14cd16f6e92fdb72650d2a3e3ef6e55ef9a Mon Sep 17 00:00:00 2001 From: kusut Date: Mon, 28 Jan 2013 23:42:27 +0700 Subject: narrative docs for add_request_method --- docs/narr/hooks.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..957426ec2 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -256,6 +256,97 @@ already constructed a :term:`configurator` it can also be registered via the config = Configurator() config.set_request_factory(MyRequest) +.. index:: + single: request method + +.. _adding_request_method: + +Adding Methods or Properties to Request Object +---------------------------------------------- + +Since each pyramid application can only have one :term:`request` factory, +:ref:`changing the request factory ` +is not that extensible especially if you want to build composable features +(e.g., pyramid add-ons and plugins). + +A lazy property can be registered to the request object via the +:meth:`pyramid.config.Configurator.add_request_method` API. This allows you +to specify a callable that will be available on the request object, but will not +actually execute the function until accessed. + +.. note:: This feature is new as of Pyramid 1.4. + +.. warning:: This will silently override methods and properties from + :term:`request factory` that have the same name. + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + def total(request, *args): + return sum(args) + + def prop(request): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(total) + config.add_request_method(prop, reify=True) + +In the above example, ``total`` is added as a method. However, ``prop`` is added +as a property and its result is cached per-request by setting ``reify=True``. +This way, we eliminate the overhead of running the function multiple times. + + >>> request.total(1, 2, 3) + 6 + >>> request.prop + getting the property + the property + >>> request.prop + the property + +To not cache the result of ``request.prop``, set ``property=True`` instead of +``reify=True``. + +Here is an example of passing a class to ``Configurator.add_request_method``: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + from pyramid.decorator import reify + + + class ExtraStuff(object): + + def __init__(self, request): + self.request = request + + def total(self, *args): + return sum(args) + + # use @property if you don't want to cache the result + @reify + def prop(self): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(ExtraStuff, 'extra', reify=True) + +We attach and cache an object named ``extra`` to the ``request`` object. + + >>> request.extra.total(1, 2, 3) + 6 + >>> request.extra.prop + getting the property + the property + >>> request.extra.prop + the property + + .. index:: single: before render event single: adding renderer globals -- cgit v1.2.3 From 5b9c21ebe7d295bb9ac4356033899181ac69396e Mon Sep 17 00:00:00 2001 From: kusut Date: Tue, 29 Jan 2013 22:16:00 +0700 Subject: enhance! --- docs/narr/hooks.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 957426ec2..d693149e4 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -264,18 +264,18 @@ already constructed a :term:`configurator` it can also be registered via the Adding Methods or Properties to Request Object ---------------------------------------------- -Since each pyramid application can only have one :term:`request` factory, +.. versionadded:: 1.4. + +Since each Pyramid application can only have one :term:`request` factory, :ref:`changing the request factory ` -is not that extensible especially if you want to build composable features -(e.g., pyramid add-ons and plugins). +is not that extensible, especially if you want to build composable features +(e.g., Pyramid add-ons and plugins). A lazy property can be registered to the request object via the :meth:`pyramid.config.Configurator.add_request_method` API. This allows you to specify a callable that will be available on the request object, but will not actually execute the function until accessed. -.. note:: This feature is new as of Pyramid 1.4. - .. warning:: This will silently override methods and properties from :term:`request factory` that have the same name. @@ -318,7 +318,6 @@ Here is an example of passing a class to ``Configurator.add_request_method``: from pyramid.config import Configurator from pyramid.decorator import reify - class ExtraStuff(object): def __init__(self, request): @@ -346,7 +345,6 @@ We attach and cache an object named ``extra`` to the ``request`` object. >>> request.extra.prop the property - .. index:: single: before render event single: adding renderer globals -- cgit v1.2.3 From 4d059a786bc019673715754be58fd61dd8d5359c Mon Sep 17 00:00:00 2001 From: "David\\ Beitey" Date: Thu, 31 Jan 2013 13:27:38 +1000 Subject: Document PredicateMismatch for exception contexts --- docs/api/exceptions.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index 1dfbf46fd..ab158f18d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,6 +5,8 @@ .. automodule:: pyramid.exceptions + .. autoclass:: PredicateMismatch + .. autoclass:: Forbidden .. autoclass:: NotFound -- cgit v1.2.3 From 1bdfad6c7303a810b05c60c53443dacc4d111852 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 00:47:47 +0200 Subject: remove obvious, and therefore redundant, info --- docs/narr/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index b092f73bc..85dfd5bf4 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -203,7 +203,7 @@ Installing Distribute On Python 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``setuptools`` doesn't work under Python 3. Instead, you can use -``distribute``, which is a fork of setuptools that does work on Python 3. To +``distribute``, which is a fork of setuptools. To install it, first download `distribute_setup.py `_ then invoke it using the Python interpreter into which you want to install setuptools. -- cgit v1.2.3 From 268737d1e1162867e4324f3400acaf158675ad6a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 14:16:49 +0200 Subject: grammar --- docs/api/request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/request.rst b/docs/api/request.rst index 9f1f71b31..7b843f86e 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -245,7 +245,7 @@ influence response values from a view that uses a renderer (such as the status code, a header, the content type, etc) you would set these attributes. See :ref:`response_prefixed_attrs` for further discussion. - As of Pyramid 1.1, assignment to ``response_*`` attrs are deprecated. + As of Pyramid 1.1, assignment to ``response_*`` attrs is deprecated. Assigning to one is still supported but will cause a deprecation warning to be emitted, and eventually the feature will be removed. For new code, instead of assigning ``response_*`` attributes to the -- cgit v1.2.3 From 0d40143635c5a248453b881247db66d2ba1f8d00 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Feb 2013 14:17:56 +0200 Subject: avoid repetition; the heading already mentions that this stuff is deprecated --- docs/narr/renderers.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 863932e83..34b9ad00c 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -565,9 +565,6 @@ in :ref:`request_module`. For more information on the API of Deprecated Mechanism to Vary Attributes of Rendered Responses ------------------------------------------------------------- -.. deprecated:: 1.1 - The behavior described in this entire section. - In previous releases of Pyramid (1.0 and before), the ``request.response`` attribute did not exist. Instead, Pyramid required users to set special ``response_`` -prefixed attributes of the request to influence response -- cgit v1.2.3