diff options
Diffstat (limited to 'docs/narr')
| -rw-r--r-- | docs/narr/configuration.rst | 41 | ||||
| -rw-r--r-- | docs/narr/environment.rst | 4 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 89 | ||||
| -rw-r--r-- | docs/narr/install.rst | 26 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 2 | ||||
| -rw-r--r-- | docs/narr/project.rst | 2 | ||||
| -rw-r--r-- | docs/narr/renderers.rst | 3 |
7 files changed, 124 insertions, 43 deletions
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index cd3dab099..6f82baf32 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -101,27 +101,25 @@ for decorations happens when the :meth:`pyramid.config.Configurator.scan` method is invoked: scanning implies searching for configuration declarations in a package and its subpackages. For example: -.. topic:: Starting A Scan - - .. code-block:: python - :linenos: - - from wsgiref.simple_server import make_server - from pyramid.config import Configurator - from pyramid.response import Response - from pyramid.view import view_config - - @view_config() - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from pyramid.config import Configurator - config = Configurator() - config.scan() - app = config.make_wsgi_app() - server = make_server('0.0.0.0', 8080, app) - server.serve_forever() +.. code-block:: python + :linenos: + + from wsgiref.simple_server import make_server + from pyramid.config import Configurator + from pyramid.response import Response + from pyramid.view import view_config + + @view_config() + def hello(request): + return Response('Hello') + + if __name__ == '__main__': + from pyramid.config import Configurator + config = Configurator() + config.scan() + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects @@ -144,7 +142,6 @@ In the example above, the scanner translates the arguments to .. ignore-next-block .. code-block:: python - :linenos: config.add_view(hello) diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index def5e12a4..281bb6919 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -203,7 +203,7 @@ Using the setting is equivalent to using the | | +---------------------------------+ -The value supplied as ``pyramid.includes`` should be a sequence. The +The value assigned to ``pyramid.includes`` should be a sequence. The sequence can take several different forms. 1) It can be a string. @@ -323,7 +323,7 @@ the behest of an add-on author. | | +---------------------------------+ -The value supplied as ``pyramid.tweens`` should be a sequence. The +The value assigned to ``pyramid.tweens`` should be a sequence. The sequence can take several different forms. 1) It can be a string. diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index fc5c0ff23..43bf48289 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -257,6 +257,95 @@ already constructed a :term:`configurator` it can also be registered via the config.set_request_factory(MyRequest) .. index:: + single: request method + +.. _adding_request_method: + +Adding Methods or Properties to Request Object +---------------------------------------------- + +.. versionadded:: 1.4. + +Since each Pyramid application can only have one :term:`request` factory, +:ref:`changing the request factory <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. + +.. 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 diff --git a/docs/narr/install.rst b/docs/narr/install.rst index c467779f4..85dfd5bf4 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -14,8 +14,8 @@ run :app:`Pyramid`. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` has been tested under Python 2.6.8, - Python 2.7.3, Python 3.2.3, and Python 3.3b1. :app:`Pyramid` does not + As of this writing, :app:`Pyramid` has been tested under Python 2.6, + Python 2.7, Python 3.2, and Python 3.3. :app:`Pyramid` does not run under any version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as @@ -88,17 +88,15 @@ using the following commands: .. code-block:: text - [chrism@vitaminf ~]$ cd ~ - [chrism@vitaminf ~]$ mkdir tmp - [chrism@vitaminf ~]$ mkdir opt - [chrism@vitaminf ~]$ cd tmp - [chrism@vitaminf tmp]$ wget \ - http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz - [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz - [chrism@vitaminf tmp]$ cd Python-2.7.3 - [chrism@vitaminf Python-2.7.3]$ ./configure \ - --prefix=$HOME/opt/Python-2.7.3 - [chrism@vitaminf Python-2.7.3]$ make; make install + $ cd ~ + $ mkdir tmp + $ mkdir opt + $ cd tmp + $ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz + $ tar xvzf Python-2.7.3.tgz + $ cd Python-2.7.3 + $ ./configure --prefix=$HOME/opt/Python-2.7.3 + $ make && make install Once these steps are performed, the Python interpreter will be invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell @@ -205,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 <http://python-distribute.org/distribute_setup.py>`_ then invoke it using the Python interpreter into which you want to install setuptools. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index c4f2ea512..3540ee5c4 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -749,7 +749,7 @@ that we change Pyramid? You can extend Pyramid's :term:`Configurator` with your own directives. For example, let's say you find yourself calling :meth:`pyramid.config.Configurator.add_view` repetitively. Usually you can take the boring away by using existing shortcuts, but let's say that this is -a case such a way that no existing shortcut works to take the boring away: +a case where there is no such shortcut: .. code-block:: python :linenos: diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fb62f4bd2..5a8ea0ecf 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -297,7 +297,7 @@ For example, your system might be configured to have an external IP address ``192.168.1.50``. If that's the case, if you use a browser running on the same system as Pyramid, it will be able to access the application via ``http://127.0.0.1:6543/`` as well as via -``http://129.168.1.50:6543/``. However, *other people* on other computers on +``http://192.168.1.50:6543/``. However, *other people* on other computers on the same network will also be able to visit your Pyramid application in their browser by visiting ``http://192.168.1.50:6543/``. 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 |