diff options
37 files changed, 329 insertions, 309 deletions
diff --git a/docs/api/config.rst b/docs/api/config.rst index e6a67830e..39d504348 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -108,9 +108,7 @@ :class:`pyramid.registry.Introspectable` class (used during directives to provide introspection to actions). - .. note:: - - This attribute is new as of :app:`Pyramid` 1.3. + .. versionadded:: 1.3 .. attribute:: introspector @@ -118,9 +116,7 @@ instance implementing the :class:`pyramid.interfaces.IIntrospector` interface. - .. note:: - - This attribute is new as of :app:`Pyramid` 1.3. + .. versionadded:: 1.3 .. attribute:: registry diff --git a/docs/api/registry.rst b/docs/api/registry.rst index a7879d3d5..db348495c 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -16,6 +16,8 @@ .. attribute:: introspector + .. versionadded:: 1.3 + When a registry is set up (or created) by a :term:`Configurator`, the registry will be decorated with an instance named ``introspector`` implementing the :class:`pyramid.interfaces.IIntrospector` interface. @@ -27,28 +29,23 @@ This attribute is often accessed as ``request.registry.introspector`` in a typical Pyramid application. - This attribute is new as of :app:`Pyramid` 1.3. - .. class:: Introspectable + .. versionadded:: 1.3 + The default implementation of the interface :class:`pyramid.interfaces.IIntrospectable` used by framework exenders. An instance of this class is created when :attr:`pyramid.config.Configurator.introspectable` is called. - This class is new as of :app:`Pyramid` 1.3. - .. autoclass:: Deferred - This class is new as of :app:`Pyramid` 1.4. + .. versionadded:: 1.4 .. autofunction:: undefer - This function is new as of :app:`Pyramid` 1.4. + .. versionadded:: 1.4 .. autoclass:: predvalseq - This class is new as of :app:`Pyramid` 1.4. - - - + .. versionadded:: 1.4 diff --git a/docs/api/request.rst b/docs/api/request.rst index e4034c635..7b843f86e 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -163,9 +163,7 @@ .. method:: invoke_subrequest(request, use_tweens=False) - .. warning:: - - This API was added in Pyramid 1.4a1. + .. versionadded:: 1.4a1 Obtain a response object from the Pyramid application based on information in the ``request`` object provided. The ``request`` object @@ -247,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 diff --git a/docs/designdefense.rst b/docs/designdefense.rst index f51ef10a9..69a921498 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -919,7 +919,7 @@ creating a more Zope3-like environment without much effort. Pyramid Uses its Own HTTP Exception Class Hierarchy Rather Than ``webob.exc`` ----------------------------------------------------------------------------- -.. note:: This defense is new as of Pyramid 1.1. +.. versionadded:: 1.1 The HTTP exception classes defined in :mod:`pyramid.httpexceptions` are very much like the ones defined in ``webob.exc`` diff --git a/docs/glossary.rst b/docs/glossary.rst index 0036d045b..9220e6b5f 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1015,8 +1015,7 @@ Glossary Green Unicorn Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under - Python 2.5+ (although at the time of this writing does not support - Python 3). See http://gunicorn.org/ for detailed information. + Python 2.6+ or Python 3.1+. See http://gunicorn.org/ for detailed information. predicate factory A callable which is used by a third party during the registration of a diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 8d6b9d984..8e360216d 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -504,7 +504,8 @@ environment much like the environment produced when a particular using the :func:`pyramid.paster.bootstrap` command in the body of your script. -.. note:: This feature is new as of :app:`Pyramid` 1.1. +.. versionadded:: 1.1 + This feature. In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a single argument, which accepts the :term:`PasteDeploy` ``.ini`` file 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 8206e0bcb..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. @@ -504,12 +504,13 @@ default, this is ``false``. Mako Preprocessor ~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.1 + A callable (or a :term:`dotted Python name` which names a callable) which is called to preprocess the source before the template is called. The callable will be passed the full template source before it is parsed. The return result of the callable will be used as the template source code. -.. note:: This feature is new in Pyramid 1.1. +-----------------------------+ | Config File Setting Name | diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index 875bc9006..f33326279 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -227,9 +227,7 @@ augment Pyramid's configuration introspection system. Adding Configuration Introspection ---------------------------------- -.. note:: - - The introspection subsystem is new in Pyramid 1.3. +.. versionadded:: 1.3 Pyramid provides a configuration introspection system that can be used by debugging tools to provide visibility into the configuration of a running diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index c464203f0..dd9281c73 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -84,7 +84,7 @@ function in your application's ``__init__.py``. For example, rather than: config.add_view('myapp.views.view1', name='view1') config.add_view('myapp.views.view2', name='view2') -You should do move the calls to ``add_view`` outside of the (non-reusable) +You should move the calls to ``add_view`` outside of the (non-reusable) ``if __name__ == '__main__'`` block, and into a reusable function: .. code-block:: python diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..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 @@ -336,9 +425,9 @@ when adding renderer global values exists in :ref:`adding_renderer_globals`. Adding Renderer Globals (Deprecated) ------------------------------------ -.. warning:: this feature is deprecated as of Pyramid 1.1. A non-deprecated - mechanism which allows event subscribers to add renderer global values - is documented in :ref:`beforerender_event`. +.. deprecated:: 1.1 + An alternative mechanism which allows event subscribers to add renderer + global values is documented in :ref:`beforerender_event`. Whenever :app:`Pyramid` handles a request to perform a rendering (after a view with a ``renderer=`` configuration attribute is invoked, or when any of @@ -635,13 +724,13 @@ See :meth:`pyramid.config.add_resource_url_adapter` for more information. Changing How Pyramid Treats View Responses ------------------------------------------ +.. versionadded:: 1.1 + It is possible to control how Pyramid treats the result of calling a view callable on a per-type basis by using a hook involving :meth:`pyramid.config.Configurator.add_response_adapter` or the :class:`~pyramid.response.response_adapter` decorator. -.. note:: This feature is new as of Pyramid 1.1. - Pyramid, in various places, adapts the result of calling a view callable to the :class:`~pyramid.interfaces.IResponse` interface to ensure that the object returned by the view callable is a "true" response object. The vast @@ -936,8 +1025,8 @@ For full details, please read the `Venusian documentation Registering "Tweens" -------------------- -.. note:: Tweens are a feature which were added in Pyramid 1.2. They are - not available in any previous version. +.. versionadded:: 1.2 + Tweens A :term:`tween` (a contraction of the word "between") is a bit of code that sits between the Pyramid router's main request handling function and the @@ -1241,10 +1330,7 @@ implict and explicit tween chains used by an application. See Adding A Third Party View, Route, or Subscriber Predicate --------------------------------------------------------- -.. note:: - - Third-party view, route, and subscriber predicates are a feature new as of - Pyramid 1.4. +.. versionadded:: 1.4 .. _view_and_route_predicates: diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 224a62db7..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 @@ -166,9 +164,7 @@ distribute is not yet installed: ImportError: No module named setuptools If ``import setuptools`` raises an :exc:`ImportError` as it does above, you -will need to install setuptools or distribute manually. Note that above -we're using a Python 2.7-series interpreter on Mac OS X; your output may -differ if you're using a later Python version or a different platform. +will need to install setuptools or distribute manually. If you are using a "system" Python (one installed by your OS distributor or a 3rd-party packager such as Fink or MacPorts), you can usually install the @@ -207,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 5379a4a99..34b9ad00c 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -63,7 +63,6 @@ the ``renderer`` attribute. For example, this call to with a view callable: .. code-block:: python - :linenos: config.add_view('myproject.views.my_view', renderer='json') @@ -73,13 +72,13 @@ which renders view return values to a :term:`JSON` response serialization. Other built-in renderers include renderers which use the :term:`Chameleon` templating language to render a dictionary to a response. Additional -renderers can be added by developers to the system as necessary (see -:ref:`adding_and_overriding_renderers`). +renderers can be added by developers to the system as necessary. +See :ref:`adding_and_overriding_renderers`. Views which use a renderer and return a non-Response value can vary non-body response attributes (such as headers and the HTTP status code) by attaching a -property to the ``request.response`` attribute See -:ref:`request_response_attr`. +property to the ``request.response`` attribute. +See :ref:`request_response_attr`. If the :term:`view callable` associated with a :term:`view configuration` returns a Response object directly, any renderer associated with the view @@ -166,7 +165,6 @@ The body of the response returned by such a view will be a string representing the ``str()`` serialization of the return value: .. code-block:: python - :linenos: {'content': 'Hello!'} @@ -204,7 +202,6 @@ The body of the response returned by such a view will be a string representing the JSON serialization of the return value: .. code-block:: python - :linenos: '{"content": "Hello!"}' @@ -294,9 +291,8 @@ with the object. See :class:`pyramid.renderers.JSON` and :ref:`adding_and_overriding_renderers` for more information. -.. note:: - - Serializing custom objects is a feature new in Pyramid 1.4. +.. versionadded:: 1.4 + Serializing custom objects. .. index:: pair: renderer; JSONP @@ -306,9 +302,7 @@ See :class:`pyramid.renderers.JSON` and JSONP Renderer ~~~~~~~~~~~~~~ -.. note:: - - This feature is new in Pyramid 1.1. +.. versionadded:: 1.1 :class:`pyramid.renderers.JSONP` is a `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ renderer factory helper which @@ -571,8 +565,6 @@ in :ref:`request_module`. For more information on the API of Deprecated Mechanism to Vary Attributes of Rendered Responses ------------------------------------------------------------- -.. warning:: This section describes behavior deprecated in Pyramid 1.1. - 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 @@ -619,7 +611,6 @@ For example, to add a renderer which renders views which have a ``renderer`` attribute that is a path that ends in ``.jinja2``: .. code-block:: python - :linenos: config.add_renderer('.jinja2', 'mypackage.MyJinja2Renderer') @@ -689,12 +680,10 @@ There are essentially two different kinds of renderer factories: :term:`package`. Here's an example of the registration of a simple renderer factory via -:meth:`~pyramid.config.Configurator.add_renderer`: +:meth:`~pyramid.config.Configurator.add_renderer`, where ``config`` +is an instance of :meth:`pyramid.config.Configurator`: .. code-block:: python - :linenos: - - # config is an instance of pyramid.config.Configurator config.add_renderer(name='amf', factory='my.package.MyAMFRenderer') @@ -725,10 +714,8 @@ Here's an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path: .. code-block:: python - :linenos: - config.add_renderer(name='.jinja2', - factory='my.package.MyJinja2Renderer') + config.add_renderer(name='.jinja2', factory='my.package.MyJinja2Renderer') Adding the above code to your application startup will allow you to use the ``my.package.MyJinja2Renderer`` renderer factory implementation in view @@ -769,7 +756,6 @@ extension for the same kinds of templates. For example, to associate the :meth:`pyramid.config.Configurator.add_renderer` method: .. code-block:: python - :linenos: config.add_renderer('.zpt', 'pyramid.chameleon_zpt.renderer_factory') @@ -781,7 +767,6 @@ rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application's startup code: .. code-block:: python - :linenos: config.add_renderer('.pt', 'mypackage.pt_renderer') @@ -794,7 +779,6 @@ ones which do not possess a ``renderer`` attribute), pass ``None`` as the ``name`` attribute to the renderer tag: .. code-block:: python - :linenos: config.add_renderer(None, 'mypackage.json_renderer_factory') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index f7da7838e..fa4affd8a 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -29,7 +29,7 @@ during your :app:`Pyramid` configuration. A very basic, insecure sample session factory implementation is provided in the :app:`Pyramid` core. It uses a cookie to store session information. This implementation has the following -limitation: +limitations: - The session information in the cookies used by this implementation is *not* encrypted, so it can be viewed by anyone with access to the diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1cec26fbc..6a1fbf916 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -543,9 +543,7 @@ template as a :term:`renderer` like so: The above will render only the ``bar`` macro defined within the ``foo.pt`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: Chameleon text templates @@ -743,9 +741,7 @@ configure the template as a :term:`renderer` like so: The above will render the ``bar`` def from within the ``foo.mak`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: automatic reloading of templates diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index ec97bf3b2..749a2d49a 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -758,11 +758,8 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. -.. note:: - - the ``static`` argument to - :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid` - 1.1. +.. versionadded:: 1.1 + the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` .. index:: single: redirecting to slash-appended routes @@ -906,7 +903,7 @@ routes configured in your application; for more information, see Using a Route Prefix to Compose Applications -------------------------------------------- -.. note:: This feature is new as of :app:`Pyramid` 1.2. +.. versionadded:: 1.2 The :meth:`pyramid.config.Configurator.include` method allows configuration statements to be included from separate files. See diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index f00dae451..7001cd980 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -306,7 +306,7 @@ configured view. consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - .. note:: This feature is new as of :app:`Pyramid` 1.2. + .. versionadded:: 1.2 This param may be either a single string of the format "key=value" or a dict of key/value pairs. @@ -724,9 +724,7 @@ configuration to take effect. ``@view_defaults`` Class Decorator ---------------------------------- -.. note:: - - This feature is new in Pyramid 1.3. +.. versionadded:: 1.3 If you use a class as a view, you can use the :class:`pyramid.view.view_defaults` class decorator on the class to provide @@ -952,7 +950,7 @@ for more information about how, and where to set these values. Influencing HTTP Caching ------------------------ -.. note:: This feature is new in Pyramid 1.1. +.. versionadded:: 1.1 When a non-``None`` ``http_cache`` argument is passed to a view configuration, Pyramid will set ``Expires`` and ``Cache-Control`` response diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 4f30bb7fa..860c380f3 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -227,8 +227,8 @@ equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each HTTP response code to its purpose and its associated HTTP exception object is provided within :mod:`pyramid.httpexceptions`. -.. note:: The :func:`~pyramid.httpexceptions.exception_response` function is - new as of Pyramid 1.1. +.. versionadded:: 1.1 + The :func:`~pyramid.httpexceptions.exception_response` function. How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index a8c11acec..44940f9e6 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -251,7 +251,7 @@ API documentation for a multidict exists as Dealing With A JSON-Encoded Request Body ++++++++++++++++++++++++++++++++++++++++ -.. note:: this feature is new as of Pyramid 1.1. +.. versionadded:: 1.1 :attr:`pyramid.request.Request.json_body` is a property that returns a :term:`JSON` -decoded representation of the request body. If the request diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 03abedbd8..f9d4775ad 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -165,7 +165,7 @@ opposed to the tutorial :term:`package` directory) looks like this: .. literalinclude:: src/basiclayout/development.ini :language: ini -Note the existence of an ``[app:main]`` section which specifies our WSGI +Note the existence of a ``[app:main]`` section which specifies our WSGI application. Our ZODB database settings are specified as the ``zodbconn.uri`` setting within this section. This value, and the other values within this section are passed as ``**settings`` to the ``main`` diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py index 90bd89116..e1320a55f 100644 --- a/pyramid/config/__init__.py +++ b/pyramid/config/__init__.py @@ -104,14 +104,7 @@ class Configurator( A Configurator is used to configure a :app:`Pyramid` :term:`application registry`. - The Configurator accepts a number of arguments: ``registry``, - ``package``, ``settings``, ``root_factory``, ``authentication_policy``, - ``authorization_policy``, ``renderers``, ``debug_logger``, - ``locale_negotiator``, ``request_factory``, ``renderer_globals_factory``, - ``default_permission``, ``session_factory``, ``default_view_mapper``, - ``autocommit``, ``exceptionresponse_view`` and ``route_prefix``. - - If the ``registry`` argument is passed as a non-``None`` value, it must + If the ``registry`` argument is not ``None``, it must be an instance of the :class:`pyramid.registry.Registry` class representing the registry to configure. If ``registry`` is ``None``, the configurator will create a :class:`pyramid.registry.Registry` instance @@ -119,9 +112,9 @@ class Configurator( otherwise be done. After its construction, the configurator may be used to add further configuration to the registry. - .. warning:: If a ``registry`` is passed to the Configurator - constructor, all other constructor arguments except ``package`` - are ignored. + .. warning:: If ``registry`` is assigned the above-mentioned class + instance, all other constructor arguments are ignored, + with the exception of ``package``. If the ``package`` argument is passed, it must be a reference to a Python :term:`package` (e.g. ``sys.modules['thepackage']``) or a :term:`dotted @@ -154,12 +147,12 @@ class Configurator( authorization policy is supplied without also supplying an authentication policy (authorization requires authentication). - If ``renderers`` is passed, it should be a list of tuples - representing a set of :term:`renderer` factories which should be - configured into this application (each tuple representing a set of + If ``renderers`` is ``None`` (the default), a default set of + :term:`renderer` factories is used. Else, it should be a list of + tuples representing a set of renderer factories which should be + configured into this application, and each tuple representing a set of positional values that should be passed to - :meth:`pyramid.config.Configurator.add_renderer`). If - it is not passed, a default set of renderer factories is used. + :meth:`pyramid.config.Configurator.add_renderer`. If ``debug_logger`` is not passed, a default debug logger that logs to a logger will be used (the logger name will be the package name of the @@ -182,10 +175,9 @@ class Configurator( same. See :ref:`adding_renderer_globals`. By default, it is ``None``, which means use no renderer globals factory. - .. warning:: - - as of Pyramid 1.1, ``renderer_globals_factory`` is deprecated. Instead, - use a BeforeRender event subscriber as per :ref:`beforerender_event`. + .. deprecated:: 1.1 + Use a BeforeRender event subscriber as per :ref:`beforerender_event` + in place of ``renderer_globals_factory``. If ``default_permission`` is passed, it should be a :term:`permission` string to be used as the default permission for @@ -218,15 +210,15 @@ class Configurator( :meth:`pyramid.config.Configurator.commit` is called. When :meth:`pyramid.config.Configurator.commit` is called, the actions implied by the called methods will be checked for configuration conflicts unless - ``autocommit`` is ``True``. If a conflict is detected a + ``autocommit`` is ``True``. If a conflict is detected, a ``ConfigurationConflictError`` will be raised. Calling :meth:`pyramid.config.Configurator.make_wsgi_app` always implies a final commit. If ``default_view_mapper`` is passed, it will be used as the default :term:`view mapper` factory for view configurations that don't otherwise - specify one (see :class:`pyramid.interfaces.IViewMapperFactory`). If a - default_view_mapper is not passed, a superdefault view mapper will be + specify one (see :class:`pyramid.interfaces.IViewMapperFactory`). If + ``default_view_mapper`` is not passed, a superdefault view mapper will be used. If ``exceptionresponse_view`` is passed, it must be a :term:`view @@ -236,18 +228,26 @@ class Configurator( be registered, and all raised exception responses will be bubbled up to Pyramid's caller. By default, the ``pyramid.httpexceptions.default_exceptionresponse_view`` - function is used as the ``exceptionresponse_view``. This argument is new - in Pyramid 1.1. + function is used as the ``exceptionresponse_view``. If ``route_prefix`` is passed, all routes added with :meth:`pyramid.config.Configurator.add_route` will have the specified path - prepended to their pattern. This parameter is new in Pyramid 1.2. + prepended to their pattern. If ``introspection`` is passed, it must be a boolean value. If it's ``True``, introspection values during actions will be kept for use for tools like the debug toolbar. If it's ``False``, introspection values provided by registrations will be ignored. By default, it is - ``True``. This parameter is new as of Pyramid 1.3. + ``True``. + + .. versionadded:: 1.1 + The ``exceptionresponse_view`` argument. + + .. versionadded:: 1.2 + The ``route_prefix`` argument. + + .. versionadded:: 1.3 + The ``introspection`` argument. """ manager = manager # for testing injection venusian = venusian # for testing injection @@ -721,7 +721,9 @@ class Configurator( because the ``route_prefix`` argument will be prepended to the pattern. - The ``route_prefix`` parameter is new as of Pyramid 1.2. + .. versionadded:: 1.2 + The ``route_prefix`` parameter. + """ # """ <-- emacs @@ -819,10 +821,8 @@ class Configurator( def with_package(self, package): """ Return a new Configurator instance with the same registry - as this configurator using the package supplied as the - ``package`` argument to the new configurator. ``package`` may - be an actual Python package object or a :term:`dotted Python name` - representing a package.""" + as this configurator. ``package`` may be an actual Python package + object or a :term:`dotted Python name` representing a package.""" configurator = self.__class__( registry=self.registry, package=package, @@ -919,8 +919,6 @@ class Configurator( and scanned. See the :term:`Venusian` documentation for more information about the ``ignore`` argument. - .. note:: the ``ignore`` argument is new in Pyramid 1.3. - To perform a ``scan``, Pyramid creates a Venusian ``Scanner`` object. The ``kw`` argument represents a set of keyword arguments to pass to the Venusian ``Scanner`` object's constructor. See the @@ -932,7 +930,12 @@ class Configurator( may require additional arguments. Providing this argument is not often necessary; it's an advanced usage. - .. note:: the ``**kw`` argument is new in Pyramid 1.1 + .. versionadded:: 1.1 + The ``**kw`` argument. + + .. versionadded:: 1.3 + The ``ignore`` argument. + """ package = self.maybe_dotted(package) if package is None: # pragma: no cover diff --git a/pyramid/config/adapters.py b/pyramid/config/adapters.py index dad60660a..319beab67 100644 --- a/pyramid/config/adapters.py +++ b/pyramid/config/adapters.py @@ -38,9 +38,8 @@ class AdaptersConfiguratorMixin(object): :meth:`pyramid.config.Configurator.add_subscriber_predicate` before it can be used. See :ref:`subscriber_predicates` for more information. - .. note:: - - THe ``**predicates`` argument is new as of Pyramid 1.4. + .. versionadded:: 1.4 + The ``**predicates`` argument. """ dotted = self.maybe_dotted subscriber, iface = dotted(subscriber), dotted(iface) @@ -137,6 +136,8 @@ class AdaptersConfiguratorMixin(object): def add_subscriber_predicate(self, name, factory, weighs_more_than=None, weighs_less_than=None): """ + .. versionadded:: 1.4 + Adds a subscriber predicate factory. The associated subscriber predicate can later be named as a keyword argument to :meth:`pyramid.config.Configurator.add_subscriber` in the @@ -150,9 +151,6 @@ class AdaptersConfiguratorMixin(object): See :ref:`subscriber_predicates` for more information. - .. note:: - - This method is new as of Pyramid 1.4. """ self._add_predicate( 'subscriber', @@ -274,6 +272,8 @@ class AdaptersConfiguratorMixin(object): @action_method def add_resource_url_adapter(self, adapter, resource_iface=None): """ + .. versionadded:: 1.3 + When you add a traverser as described in :ref:`changing_the_traverser`, it's convenient to continue to use the :meth:`pyramid.request.Request.resource_url` API. However, since the @@ -299,10 +299,6 @@ class AdaptersConfiguratorMixin(object): ``None``, the url adapter will be used for every type of resource. See :ref:`changing_resource_url` for more information. - - .. note:: - - This API is new in Pyramid 1.3. """ adapter = self.maybe_dotted(adapter) resource_iface = self.maybe_dotted(resource_iface) diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py index ef7975d92..d30df3b74 100644 --- a/pyramid/config/factories.py +++ b/pyramid/config/factories.py @@ -182,9 +182,7 @@ class FactoriesConfiguratorMixin(object): def set_request_property(self, callable, name=None, reify=False): """ Add a property to the request object. - .. warning:: - - This method has been docs-deprecated as of Pyramid 1.4. + .. deprecated:: 1.4 :meth:`pyramid.config.Configurator.add_request_method` should be used instead. diff --git a/pyramid/config/rendering.py b/pyramid/config/rendering.py index 4f33b23d9..356bf033e 100644 --- a/pyramid/config/rendering.py +++ b/pyramid/config/rendering.py @@ -73,11 +73,9 @@ class RenderingConfiguratorMixin(object): dictionary, and therefore will be made available to the code which uses the renderer. - .. warning:: - - This method is deprecated as of Pyramid 1.1. Use a BeforeRender - event subscriber as documented in the :ref:`hooks_chapter` chapter - instead. + .. deprecated:: 1.1 + Use a BeforeRender event subscriber as documented in the + :ref:`hooks_chapter` chapter instead. .. note:: diff --git a/pyramid/config/routes.py b/pyramid/config/routes.py index e06d0fecd..7a7bbae1a 100644 --- a/pyramid/config/routes.py +++ b/pyramid/config/routes.py @@ -142,7 +142,7 @@ class RoutesConfiguratorMixin(object): request; it will only be useful for URL generation. By default, ``static`` is ``False``. See :ref:`static_route_narr`. - .. note:: New in :app:`Pyramid` 1.1. + .. versionadded:: 1.1 Predicate Arguments @@ -180,9 +180,9 @@ class RoutesConfiguratorMixin(object): will match if the request has *any* request method. If this predicate returns ``False``, route matching continues. - .. note:: The ability to pass a tuple of items as - ``request_method`` is new as of Pyramid 1.2. Previous - versions allowed only a string. + .. versionchanged:: 1.2 + The ability to pass a tuple of items as ``request_method``. + Previous versions allowed only a string. path_info @@ -276,8 +276,10 @@ class RoutesConfiguratorMixin(object): :meth:`pyramid.config.Configurator.add_view_predicate`. More than one key/value pair can be used at the same time. See :ref:`view_and_route_predicates` for more information about - third-party predicates. This argument is new as of Pyramid 1.4. - + third-party predicates. + + .. versionadded:: 1.4 + View-Related Arguments .. warning:: @@ -291,7 +293,7 @@ class RoutesConfiguratorMixin(object): view - .. warning:: Deprecated as of :app:`Pyramid` 1.1. + .. deprecated:: 1.1 A Python object or :term:`dotted Python name` to the same object that will be used as a view callable when this route @@ -299,7 +301,7 @@ class RoutesConfiguratorMixin(object): view_context - .. warning:: Deprecated as of :app:`Pyramid` 1.1. + .. deprecated:: 1.1 A class or an :term:`interface` or :term:`dotted Python name` to the same object which the :term:`context` of the @@ -315,7 +317,7 @@ class RoutesConfiguratorMixin(object): view_permission - .. warning:: Deprecated as of :app:`Pyramid` 1.1. + .. deprecated:: 1.1 The permission name required to invoke the view associated with this route. e.g. ``edit``. (see @@ -329,7 +331,7 @@ class RoutesConfiguratorMixin(object): view_renderer - .. warning:: Deprecated as of :app:`Pyramid` 1.1. + .. deprecated:: 1.1 This is either a single string term (e.g. ``json``) or a string implying a path or :term:`asset specification` @@ -353,7 +355,7 @@ class RoutesConfiguratorMixin(object): view_attr - .. warning:: Deprecated as of :app:`Pyramid` 1.1. + .. deprecated:: 1.1 The view machinery defaults to using the ``__call__`` method of the view callable (or the function itself, if the view @@ -491,9 +493,7 @@ class RoutesConfiguratorMixin(object): See :ref:`view_and_route_predicates` for more information. - .. note:: - - This method is new as of Pyramid 1.4. + .. versionadded:: 1.4 """ self._add_predicate( 'route', diff --git a/pyramid/config/testing.py b/pyramid/config/testing.py index 7141a5049..2ab85b1f5 100644 --- a/pyramid/config/testing.py +++ b/pyramid/config/testing.py @@ -37,19 +37,11 @@ class TestingConfiguratorMixin(object): not provided (or it is provided, and is ``None``), the default value ``[]`` (the empty list) will be returned by ``remember``. - .. note:: - - ``remember_result`` is new as of Pyramid 1.4. - ``forget_result``, if provided, should be the result returned by the ``forget`` method of the faux authentication policy. If it is not provided (or it is provided, and is ``None``), the default value ``[]`` (the empty list) will be returned by ``forget``. - .. note:: - - ``forget_result`` is new as of Pyramid 1.4. - The behavior of the registered :term:`authentication policy` depends on the values provided for the ``userid`` and ``groupids`` argument. The authentication policy will return @@ -64,6 +56,12 @@ class TestingConfiguratorMixin(object): :func:`pyramid.security.authenticated_userid`, :func:`pyramid.security.effective_principals`, and :func:`pyramid.security.principals_allowed_by_permission`. + + .. versionadded:: 1.4 + The ``remember_result`` argument. + + .. versionadded:: 1.4 + The ``forget_result`` argument. """ from pyramid.testing import DummySecurityPolicy policy = DummySecurityPolicy( diff --git a/pyramid/config/tweens.py b/pyramid/config/tweens.py index 1bc6dc95c..cd14c9ff6 100644 --- a/pyramid/config/tweens.py +++ b/pyramid/config/tweens.py @@ -24,7 +24,7 @@ from pyramid.config.util import ( class TweensConfiguratorMixin(object): def add_tween(self, tween_factory, under=None, over=None): """ - .. note:: This feature is new as of Pyramid 1.2. + .. versionadded:: 1.2 Add a 'tween factory'. A :term:`tween` (a contraction of 'between') is a bit of code that sits between the Pyramid router's main request diff --git a/pyramid/config/views.py b/pyramid/config/views.py index e4217f2f3..1b89437ea 100644 --- a/pyramid/config/views.py +++ b/pyramid/config/views.py @@ -710,7 +710,7 @@ class ViewsConfiguratorMixin(object): http_cache - .. note:: This feature is new as of Pyramid 1.1. + .. versionadded:: 1.1 When you supply an ``http_cache`` value to a view configuration, the ``Expires`` and ``Cache-Control`` headers of a response @@ -822,7 +822,8 @@ class ViewsConfiguratorMixin(object): think about preserving function attributes such as ``__name__`` and ``__module__`` within decorator logic). - Passing an iterable is only supported as of :app:`Pyramid` 1.4a4. + .. versionchanged:: 1.4a4 + Passing an iterable. mapper @@ -877,9 +878,9 @@ class ViewsConfiguratorMixin(object): supplied value. Note that use of ``GET`` also implies that the view will respond to ``HEAD`` as of Pyramid 1.4. - .. note:: The ability to pass a tuple of items as - ``request_method`` is new as of Pyramid 1.2. Previous - versions allowed only a string. + .. versionchanged:: 1.2 + The ability to pass a tuple of items as ``request_method``. + Previous versions allowed only a string. request_param @@ -897,7 +898,7 @@ class ViewsConfiguratorMixin(object): match_param - .. note:: This feature is new as of :app:`Pyramid` 1.2. + .. versionadded:: 1.2 This value can be a string of the format "key=value" or a tuple containing one or more of these strings. @@ -1354,7 +1355,10 @@ class ViewsConfiguratorMixin(object): @action_method def add_view_predicate(self, name, factory, weighs_more_than=None, weighs_less_than=None): - """ Adds a view predicate factory. The associated view predicate can + """ + .. versionadded:: 1.4 + + Adds a view predicate factory. The associated view predicate can later be named as a keyword argument to :meth:`pyramid.config.Configurator.add_view` in the ``predicates`` anonyous keyword argument dictionary. @@ -1366,10 +1370,6 @@ class ViewsConfiguratorMixin(object): ``factory`` should be a :term:`predicate factory`. See :ref:`view_and_route_predicates` for more information. - - .. note:: - - This method is new as of Pyramid 1.4. """ self._add_predicate( 'view', @@ -1557,9 +1557,7 @@ class ViewsConfiguratorMixin(object): ``for_``, or ``http_cache`` keyword arguments. These argument values make no sense in the context of a forbidden view. - .. note:: - - This method is new as of Pyramid 1.3. + .. versionadded:: 1.3 """ for arg in ('name', 'permission', 'context', 'for_', 'http_cache'): if arg in predicates: @@ -1646,9 +1644,7 @@ class ViewsConfiguratorMixin(object): Pyramid will return the result of the view callable provided as ``view``, as normal. - .. note:: - - This method is new as of Pyramid 1.3. + .. versionadded:: 1.3 """ for arg in ('name', 'permission', 'context', 'for_', 'http_cache'): if arg in predicates: diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index 54bce6fd2..0a5ec9588 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -744,10 +744,8 @@ class IResourceURL(Interface): class IContextURL(IResourceURL): """ An adapter which deals with URLs related to a context. - ..warning:: - - This interface is deprecated as of Pyramid 1.3 with the introduction of - IResourceURL. + .. deprecated:: 1.3 + use IResourceURL instead. """ # this class subclasses IResourceURL because request.resource_url looks # for IResourceURL via queryAdapter. queryAdapter will find a deprecated @@ -792,7 +790,7 @@ deprecated( 'scheduled to be removed. Use the ' '"pyramid.config.Configurator.add_resource_url_adapter" method to register ' 'a class that implements "pyramid.interfaces.IResourceURL" instead. ' - 'See the "What\'s new In Pyramid 1.3" document for a further description.' + 'See the "What\'s new In Pyramid 1.3" document for more details.' ) class IPackageOverrides(Interface): diff --git a/pyramid/path.py b/pyramid/path.py index e9c63a365..57eccdb19 100644 --- a/pyramid/path.py +++ b/pyramid/path.py @@ -114,7 +114,7 @@ class AssetResolver(Resolver): """ A class used to resolve an :term:`asset specification` to an :term:`asset descriptor`. - .. note:: This API is new as of Pyramid 1.3. + .. versionadded:: 1.3 The constructor accepts a single argument named ``package`` which may be any of: @@ -133,20 +133,19 @@ class AssetResolver(Resolver): to the :meth:`~pyramid.path.AssetResolver.resolve` method. An asset specification without a colon in it is treated as relative. - If the value ``None`` is supplied as the ``package``, the resolver will + If ``package`` is ``None``, the resolver will only be able to resolve fully qualified (not relative) asset specifications. Any attempt to resolve a relative asset specification - when the ``package`` is ``None`` will result in an :exc:`ValueError` - exception. + will result in an :exc:`ValueError` exception. - If the value :attr:`pyramid.path.CALLER_PACKAGE` is supplied as the - ``package``, the resolver will treat relative asset specifications as + If ``package`` is :attr:`pyramid.path.CALLER_PACKAGE`, + the resolver will treat relative asset specifications as relative to the caller of the :meth:`~pyramid.path.AssetResolver.resolve` method. - If a *module* or *module name* (as opposed to a package or package name) - is supplied as ``package``, its containing package is computed and this - package used to derive the package name (all names are resolved relative + If ``package`` is a *module* or *module name* (as opposed to a package or + package name), its containing package is computed and this + package is used to derive the package name (all names are resolved relative to packages, never to modules). For example, if the ``package`` argument to this type was passed the string ``xml.dom.expatbuilder``, and ``template.pt`` is supplied to the @@ -154,8 +153,8 @@ class AssetResolver(Resolver): asset spec would be ``xml.minidom:template.pt``, because ``xml.dom.expatbuilder`` is a module object, not a package object. - If a *package* or *package name* (as opposed to a module or module name) - is supplied as ``package``, this package will be used to compute relative + If ``package`` is a *package* or *package name* (as opposed to a module or + module name), this package will be used to compute relative asset specifications. For example, if the ``package`` argument to this type was passed the string ``xml.dom``, and ``template.pt`` is supplied to the :meth:`~pyramid.path.AssetResolver.resolve` method, the resulting @@ -209,7 +208,7 @@ class DottedNameResolver(Resolver): """ A class used to resolve a :term:`dotted Python name` to a package or module object. - .. note:: This API is new as of Pyramid 1.3. + .. versionadded:: 1.3 The constructor accepts a single argument named ``package`` which may be any of: @@ -229,18 +228,17 @@ class DottedNameResolver(Resolver): which has a ``.`` (dot) or ``:`` (colon) as its first character is treated as relative. - If the value ``None`` is supplied as the ``package``, the resolver will - only be able to resolve fully qualified (not relative) names. Any - attempt to resolve a relative name when the ``package`` is ``None`` will - result in an :exc:`ValueError` exception. + If ``package`` is ``None``, the resolver will only be able to resolve + fully qualified (not relative) names. Any attempt to resolve a + relative name will result in an :exc:`ValueError` exception. - If the value :attr:`pyramid.path.CALLER_PACKAGE` is supplied as the - ``package``, the resolver will treat relative dotted names as relative to + If ``package`` is :attr:`pyramid.path.CALLER_PACKAGE`, + the resolver will treat relative dotted names as relative to the caller of the :meth:`~pyramid.path.DottedNameResolver.resolve` method. - If a *module* or *module name* (as opposed to a package or package name) - is supplied as ``package``, its containing package is computed and this + If ``package`` is a *module* or *module name* (as opposed to a package or + package name), its containing package is computed and this package used to derive the package name (all names are resolved relative to packages, never to modules). For example, if the ``package`` argument to this type was passed the string ``xml.dom.expatbuilder``, and @@ -249,8 +247,8 @@ class DottedNameResolver(Resolver): import would be for ``xml.minidom``, because ``xml.dom.expatbuilder`` is a module object, not a package object. - If a *package* or *package name* (as opposed to a module or module name) - is supplied as ``package``, this package will be used to relative compute + If ``package`` is a *package* or *package name* (as opposed to a module or + module name), this package will be used to relative compute dotted names. For example, if the ``package`` argument to this type was passed the string ``xml.dom``, and ``.minidom`` is supplied to the :meth:`~pyramid.path.DottedNameResolver.resolve` method, the resulting diff --git a/pyramid/renderers.py b/pyramid/renderers.py index 6839d72f5..64951a6ba 100644 --- a/pyramid/renderers.py +++ b/pyramid/renderers.py @@ -43,23 +43,23 @@ from pyramid.threadlocal import get_current_registry # API def render(renderer_name, value, request=None, package=None): - """ Using the renderer specified as ``renderer_name`` (a template - or a static renderer) render the value (or set of values) present + """ Using the renderer ``renderer_name`` (a template + or a static renderer), render the value (or set of values) present in ``value``. Return the result of the renderer's ``__call__`` method (usually a string or Unicode). - If the renderer name refers to a file on disk (such as when the - renderer is a template), it's usually best to supply the name as a + If the ``renderer_name`` refers to a file on disk, such as when the + renderer is a template, it's usually best to supply the name as an :term:`asset specification` (e.g. ``packagename:path/to/template.pt``). You may supply a relative asset spec as ``renderer_name``. If the ``package`` argument is supplied, a relative renderer path will be converted to an absolute asset specification by - combining the package supplied as ``package`` with the relative - asset specification supplied as ``renderer_name``. If you do - not supply a ``package`` (or ``package`` is ``None``) the package - name of the *caller* of this function will be used as the package. + combining the package ``package`` with the relative + asset specification ``renderer_name``. If ``package`` + is ``None`` (the default), the package name of the *caller* of + this function will be used as the package. The ``value`` provided will be supplied as the input to the renderer. Usually, for template renderings, this should be a @@ -70,7 +70,7 @@ def render(renderer_name, value, request=None, package=None): top-level system names, such as ``request``, ``context``, ``renderer_name``, and ``view``. See :ref:`renderer_system_values` for the full list. If :term:`renderer globals` have been specified, these - will also be used to agument the value. + will also be used to augment the value. Supply a ``request`` parameter in order to provide the renderer with the most correct 'system' values (``request`` and ``context`` @@ -88,8 +88,8 @@ def render(renderer_name, value, request=None, package=None): return helper.render(value, None, request=request) def render_to_response(renderer_name, value, request=None, package=None): - """ Using the renderer specified as ``renderer_name`` (a template - or a static renderer) render the value (or set of values) using + """ Using the renderer ``renderer_name`` (a template + or a static renderer), render the value (or set of values) using the result of the renderer's ``__call__`` method (usually a string or Unicode) as the response body. @@ -100,8 +100,8 @@ def render_to_response(renderer_name, value, request=None, package=None): You may supply a relative asset spec as ``renderer_name``. If the ``package`` argument is supplied, a relative renderer name will be converted to an absolute asset specification by - combining the package supplied as ``package`` with the relative - asset specification supplied as ``renderer_name``. If you do + combining the package ``package`` with the relative + asset specification ``renderer_name``. If you do not supply a ``package`` (or ``package`` is ``None``) the package name of the *caller* of this function will be used as the package. @@ -134,16 +134,15 @@ def render_to_response(renderer_name, value, request=None, package=None): return helper.render_to_response(value, None, request=request) def get_renderer(renderer_name, package=None): - """ Return the renderer object for the renderer named as - ``renderer_name``. + """ Return the renderer object for the renderer ``renderer_name``. You may supply a relative asset spec as ``renderer_name``. If the ``package`` argument is supplied, a relative renderer name will be converted to an absolute asset specification by - combining the package supplied as ``package`` with the relative - asset specification supplied as ``renderer_name``. If you do - not supply a ``package`` (or ``package`` is ``None``) the package - name of the *caller* of this function will be used as the package. + combining the package ``package`` with the relative + asset specification ``renderer_name``. If ``package`` is ``None`` + (the default), the package name of the *caller* of this function + will be used as the package. """ if package is None: package = caller_package() @@ -204,11 +203,9 @@ class JSON(object): ``default``, and any extra ``kw`` keyword argments passed during renderer construction. - .. note:: - - This feature is new in Pyramid 1.4. Prior to 1.4 there was - no public API for supplying options to the underlying - serializer without defining a custom renderer. + .. versionadded:: 1.4 + Prior to this version, there was no public API for supplying options + to the underlying serializer without defining a custom renderer. """ def __init__(self, serializer=json.dumps, adapters=(), **kw): @@ -303,8 +300,8 @@ class JSONP(JSON): config = Configurator() config.add_renderer('jsonp', JSONP(param_name='callback', indent=4)) - .. note:: The ability of this class to accept a ``**kw`` in its - constructor is new as of Pyramid 1.4. + .. versionchanged:: 1.4 + The ability of this class to accept a ``**kw`` in its constructor. The arguments passed to this class' constructor mean the same thing as the arguments passed to :class:`pyramid.renderers.JSON` (including @@ -332,7 +329,7 @@ class JSONP(JSON): - If there is no callback parameter in the request's query string, the renderer will return a 'plain' JSON response. - .. note:: This feature is new in Pyramid 1.1. + .. versionadded:: 1.1 See also: :ref:`jsonp_renderer`. """ diff --git a/pyramid/response.py b/pyramid/response.py index 1dccb7ae8..0f61af472 100644 --- a/pyramid/response.py +++ b/pyramid/response.py @@ -35,20 +35,20 @@ class FileResponse(Response): ``path`` is a file path on disk. - ``request`` must be a Pyramid :term:`request` object if passed. Note + ``request`` must be a Pyramid :term:`request` object. Note that a request *must* be passed if the response is meant to attempt to use the ``wsgi.file_wrapper`` feature of the web server that you're using to serve your Pyramid application. - ``cache_max_age`` if passed, is the number of seconds that should be used + ``cache_max_age`` is the number of seconds that should be used to HTTP cache this response. - ``content_type``, if passed, is the content_type of the response. + ``content_type`` is the content_type of the response. - ``content_encoding``, if passed is the content_encoding of the response. + ``content_encoding`` is the content_encoding of the response. It's generally safe to leave this set to ``None`` if you're serving a - binary file. This argument will be ignored if you don't also pass - ``content-type``. + binary file. This argument will be ignored if you also leave + ``content-type`` as ``None``. """ def __init__(self, path, request=None, cache_max_age=None, content_type=None, content_encoding=None): diff --git a/pyramid/session.py b/pyramid/session.py index a5e6a8d3a..7db8c8e0e 100644 --- a/pyramid/session.py +++ b/pyramid/session.py @@ -140,30 +140,30 @@ def UnencryptedCookieSessionFactoryConfig( A number of seconds of inactivity before a session times out. ``cookie_name`` - The name of the cookie used for sessioning. Default: ``session``. + The name of the cookie used for sessioning. ``cookie_max_age`` The maximum age of the cookie used for sessioning (in seconds). Default: ``None`` (browser scope). ``cookie_path`` - The path used for the session cookie. Default: ``/``. + The path used for the session cookie. ``cookie_domain`` The domain used for the session cookie. Default: ``None`` (no domain). ``cookie_secure`` - The 'secure' flag of the session cookie. Default: ``False``. + The 'secure' flag of the session cookie. ``cookie_httponly`` - The 'httpOnly' flag of the session cookie. Default: ``False``. + The 'httpOnly' flag of the session cookie. ``cookie_on_exception`` If ``True``, set a session cookie even if an exception occurs - while rendering a view. Default: ``True``. + while rendering a view. ``signed_serialize`` - A callable which takes more or less arbitrary python data structure and + A callable which takes more or less arbitrary Python data structure and a secret and returns a signed serialization in bytes. Default: ``signed_serialize`` (using pickle). diff --git a/pyramid/url.py b/pyramid/url.py index 8fb5e49ab..84b58ac45 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -390,9 +390,8 @@ class URLMethodsMixin(object): pass ``app_url=''`. Passing ``app_url=''` when the resource path is ``/baz/bar`` will return ``/baz/bar``. - .. note:: - - ``app_url`` is new as of Pyramid 1.3. + .. versionadded:: 1.3 + ``app_url`` If ``app_url`` is passed and any of ``scheme``, ``port``, or ``host`` are also passed, ``app_url`` will take precedence and the values diff --git a/pyramid/view.py b/pyramid/view.py index 40d7c19b9..b88c2ea85 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -29,9 +29,11 @@ _marker = object() class static(static_view): """ Backwards compatibility alias for :class:`pyramid.static.static_view`; it overrides that class' constructor - to pass ``use_subpath=True`` by default. This class is deprecated as of - :app:`Pyramid` 1.1. Use :class:`pyramid.static.static_view` instead - (probably with a ``use_subpath=True`` argument). + to pass ``use_subpath=True`` by default. + + .. deprecated:: 1.1 + use :class:`pyramid.static.static_view` instead + (probably with a ``use_subpath=True`` argument) """ def __init__(self, root_dir, cache_max_age=3600, package_name=None): if package_name is None: @@ -312,11 +314,12 @@ See also :ref:`changing_the_notfound_view`. class notfound_view_config(object): """ + .. versionadded:: 1.3 An analogue of :class:`pyramid.view.view_config` which registers a - :term:`not found view`. + :term:`Not Found View`. - The notfound_view_config constructor accepts most of the same arguments + The ``notfound_view_config`` constructor accepts most of the same arguments as the constructor of :class:`pyramid.view.view_config`. It can be used in the same places, and behaves in largely the same way, except it always registers a not found exception view instead of a 'normal' view. @@ -346,9 +349,6 @@ class notfound_view_config(object): See :ref:`changing_the_notfound_view` for detailed usage information. - .. note:: - - This class is new as of Pyramid 1.3. """ venusian = venusian @@ -377,6 +377,7 @@ class notfound_view_config(object): class forbidden_view_config(object): """ + .. versionadded:: 1.3 An analogue of :class:`pyramid.view.view_config` which registers a :term:`forbidden view`. @@ -403,9 +404,6 @@ class forbidden_view_config(object): See :ref:`changing_the_forbidden_view` for detailed usage information. - .. note:: - - This class is new as of Pyramid 1.3. """ venusian = venusian @@ -436,11 +434,8 @@ def is_response(ob): """ Return ``True`` if ``ob`` implements the interface implied by :ref:`the_response`. ``False`` if not. - .. warning:: - - This function is deprecated as of :app:`Pyramid` 1.1. New - code should not use it. Instead, new code should use the - :func:`pyramid.request.Request.is_response` method.""" + .. deprecated:: 1.1 + use :func:`pyramid.request.Request.is_response` instead""" if ( hasattr(ob, 'app_iter') and hasattr(ob, 'headerlist') and hasattr(ob, 'status') ): return True |