diff options
Diffstat (limited to 'docs/whatsnew-1.1.rst')
| -rw-r--r-- | docs/whatsnew-1.1.rst | 236 |
1 files changed, 180 insertions, 56 deletions
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index b249b0ba7..18d0aa0b1 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -29,6 +29,12 @@ The major feature additions in Pyramid 1.1 are: - Default HTTP exception view. +- ``http_cache`` view configuration parameter causes Pyramid to set HTTP + caching headers. + +- Features that make it easier to write scripts that work in a :app:`Pyramid` + environment. + ``request.response`` ~~~~~~~~~~~~~~~~~~~~ @@ -91,6 +97,81 @@ Default HTTP Exception View exception to that of Pyramid 1.0 (the exception will propagate to middleware and to the WSGI server). +``http_cache`` +~~~~~~~~~~~~~~ + +A new value ``http_cache`` can be used as a :term:`view configuration` +parameter. + +When you supply an ``http_cache`` value to a view configuration, the +``Expires`` and ``Cache-Control`` headers of a response generated by the +associated view callable are modified. The value for ``http_cache`` may be +one of the following: + +- A nonzero integer. If it's a nonzero integer, it's treated as a number + of seconds. This number of seconds will be used to compute the + ``Expires`` header and the ``Cache-Control: max-age`` parameter of + responses to requests which call this view. For example: + ``http_cache=3600`` instructs the requesting browser to 'cache this + response for an hour, please'. + +- A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` + instance, it will be converted into a number of seconds, and that number + of seconds will be used to compute the ``Expires`` header and the + ``Cache-Control: max-age`` parameter of responses to requests which call + this view. For example: ``http_cache=datetime.timedelta(days=1)`` + instructs the requesting browser to 'cache this response for a day, + please'. + +- Zero (``0``). If the value is zero, the ``Cache-Control`` and + ``Expires`` headers present in all responses from this view will be + composed such that client browser cache (and any intermediate caches) are + instructed to never cache the response. + +- A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, + {'public':True})``), the first value in the tuple may be a nonzero + integer or a ``datetime.timedelta`` instance; in either case this value + will be used as the number of seconds to cache the response. The second + value in the tuple must be a dictionary. The values present in the + dictionary will be used as input to the ``Cache-Control`` response + header. For example: ``http_cache=(3600, {'public':True})`` means 'cache + for an hour, and add ``public`` to the Cache-Control header of the + response'. All keys and values supported by the + ``webob.cachecontrol.CacheControl`` interface may be added to the + dictionary. Supplying ``{'public':True}`` is equivalent to calling + ``response.cache_control.public = True``. + +Providing a non-tuple value as ``http_cache`` is equivalent to calling +``response.cache_expires(value)`` within your view's body. + +Providing a two-tuple value as ``http_cache`` is equivalent to calling +``response.cache_expires(value[0], **value[1])`` within your view's body. + +If you wish to avoid influencing, the ``Expires`` header, and instead wish +to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` +with the first element of ``None``, e.g.: ``(None, {'public':True})``. + +The environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and configuration +file value ``prevent_http_cache`` are synonymous and allow you to prevent +HTTP cache headers from being set by Pyramid's ``http_cache`` machinery +globally in a process. see :ref:`influencing_http_caching` and +:ref:`preventing_http_caching`. + +Easier Scripting Writing +~~~~~~~~~~~~~~~~~~~~~~~~ + +A new API function :func:`pyramid.paster.bootstrap` has been added to make +writing scripts that need to work under Pyramid environment easier, e.g.: + +.. code-block:: python + + from pyramid.paster import bootstrap + info = bootstrap('/path/to/my/development.ini') + request = info['request'] + print request.route_url('myroute') + +See :ref:`writing_a_script` for more details. + Minor Feature Additions ----------------------- @@ -100,8 +181,12 @@ Minor Feature Additions user. See "The Interactive Shell" in the "Creating a Pyramid Project" narrative documentation section. -- ``paster pshell`` now offers more built-in global variables by default - (including ``app`` and ``settings``). See :ref:`interactive_shell`. +- The ``paster pshell``, ``paster pviews``, and ``paster proutes`` commands + each now under the hood uses :func:`pyramid.paster.bootstrap`, which makes + it possible to supply an ``.ini`` file without naming the "right" section + in the file that points at the actual Pyramid application. Instead, you + can generally just run ``paster {pshell|proutes|pviews} development.ini`` + and it will do mostly the right thing. - It is now possible to add a ``[pshell]`` section to your application's .ini configuration file, which influences the global names available to a pshell @@ -116,57 +201,6 @@ Minor Feature Additions JSON-decoded variant of the request body. If the request body is not well-formed JSON, this property will raise an exception. -- A new value ``http_cache`` can be used as a :term:`view configuration` - parameter. - - When you supply an ``http_cache`` value to a view configuration, the - ``Expires`` and ``Cache-Control`` headers of a response generated by the - associated view callable are modified. The value for ``http_cache`` may be - one of the following: - - - A nonzero integer. If it's a nonzero integer, it's treated as a number - of seconds. This number of seconds will be used to compute the - ``Expires`` header and the ``Cache-Control: max-age`` parameter of - responses to requests which call this view. For example: - ``http_cache=3600`` instructs the requesting browser to 'cache this - response for an hour, please'. - - - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` - instance, it will be converted into a number of seconds, and that number - of seconds will be used to compute the ``Expires`` header and the - ``Cache-Control: max-age`` parameter of responses to requests which call - this view. For example: ``http_cache=datetime.timedelta(days=1)`` - instructs the requesting browser to 'cache this response for a day, - please'. - - - Zero (``0``). If the value is zero, the ``Cache-Control`` and - ``Expires`` headers present in all responses from this view will be - composed such that client browser cache (and any intermediate caches) are - instructed to never cache the response. - - - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, - {'public':True})``), the first value in the tuple may be a nonzero - integer or a ``datetime.timedelta`` instance; in either case this value - will be used as the number of seconds to cache the response. The second - value in the tuple must be a dictionary. The values present in the - dictionary will be used as input to the ``Cache-Control`` response - header. For example: ``http_cache=(3600, {'public':True})`` means 'cache - for an hour, and add ``public`` to the Cache-Control header of the - response'. All keys and values supported by the - ``webob.cachecontrol.CacheControl`` interface may be added to the - dictionary. Supplying ``{'public':True}`` is equivalent to calling - ``response.cache_control.public = True``. - - Providing a non-tuple value as ``http_cache`` is equivalent to calling - ``response.cache_expires(value)`` within your view's body. - - Providing a two-tuple value as ``http_cache`` is equivalent to calling - ``response.cache_expires(value[0], **value[1])`` within your view's body. - - If you wish to avoid influencing, the ``Expires`` header, and instead wish - to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` - with the first element of ``None``, e.g.: ``(None, {'public':True})``. - - A `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ renderer. See :ref:`jsonp_renderer` for more details. @@ -245,6 +279,54 @@ Minor Feature Additions preprocessor to be specified as a Python callable or Python dotted name. See https://github.com/Pylons/pyramid/pull/183 for rationale. +- New API class: :class:`pyramid.static.static_view`. This supersedes the + (now deprecated) :class:`pyramid.view.static` class. + :class:`pyramid.static.static_view`, by default, serves up documents as the + result of the request's ``path_info``, attribute rather than it's + ``subpath`` attribute (the inverse was true of + :class:`pyramid.view.static`, and still is). + :class:`pyramid.static.static_view` exposes a ``use_subpath`` flag for use + when you want the static view to behave like the older deprecated version. + +- A new api function :func:`pyramid.scripting.prepare` has been added. It is + a lower-level analogue of :func:`pyramid.paster.boostrap` that accepts a + request and a registry instead of a config file argument, and is used for + the same purpose: + + .. code-block:: python + + from pyramid.scripting import prepare + info = prepare(registry=myregistry) + request = info['request'] + print request.route_url('myroute') + +- A new API function :func:`pyramid.scripting.make_request` has been added. + The resulting request will have a ``registry`` attribute. It is meant to + be used in conjunction with :func:`pyramid.scripting.prepare` and/or + :func:`pyramid.paster.bootstrap` (both of which accept a request as an + argument): + + .. code-block:: python + + from pyramid.scripting import make_request + request = make_request('/') + +- New API attribute :attr:`pyramid.config.global_registries` is an iterable + object that contains references to every Pyramid registry loaded into the + current process via :meth:`pyramid.config.Configurator.make_app`. It also + has a ``last`` attribute containing the last registry loaded. This is used + by the scripting machinery, and is available for introspection. + +- Added the :attr:`pyramid.renderers.null_renderer` object as an API. The + null renderer is an object that can be used in advanced integration cases + as input to the view configuration ``renderer=`` argument. When the null + renderer is used as a view renderer argument, Pyramid avoids converting the + view callable result into a Response object. This is useful if you want to + reuse the view configuration and lookup machinery outside the context of + its use by the Pyramid router. (This feature was added for consumption by + the ``pyramid_rpc`` package, which uses view configuration and lookup + outside the context of a router in exactly this way.) + Backwards Incompatibilities --------------------------- @@ -308,6 +390,20 @@ Backwards Incompatibilities Deprecations and Behavior Differences ------------------------------------- +.. note:: Under Python 2.7+, it's necessary to pass the Python interpreter + the correct warning flags to see deprecation warnings emitted by Pyramid + when porting your application from an older version of Pyramid. Use the + ``PYTHONWARNINGS`` environment variable with the value ``all`` in the + shell you use to invoke ``paster serve`` to see these warnings, e.g. on + UNIX, ``PYTHONWARNINGS=all bin/paster serve development.ini``. Python 2.5 + and 2.6 show deprecation warnings by default, so this is unecessary there. + All deprecation warnings are emitted to the console. + +- The :class:`pyramid.view.static` class has been deprecated in favor of the + newer :class:`pyramid.static.static_view` class. A deprecation warning is + raised when it is used. You should replace it with a reference to + :class:`pyramid.static.static_view` with the ``use_subpath=True`` argument. + - The ``paster pshell``, ``paster proutes``, and ``paster pviews`` commands now take a single argument in the form ``/path/to/config.ini#sectionname`` rather than the previous 2-argument spelling ``/path/to/config.ini @@ -383,7 +479,7 @@ Deprecations and Behavior Differences these methods will be removed entirely. - A custom request factory is now required to return a request object that - has a ``response`` attribute (or "reified"/lazy property) if they the + has a ``response`` attribute (or "reified"/lazy property) if the request is meant to be used in a view that uses a renderer. This ``response`` attribute should be an instance of the class :class:`pyramid.response.Response`. @@ -446,8 +542,8 @@ Deprecations and Behavior Differences - Deprecated the :meth:`pyramid.config.Configurator.set_renderer_globals_factory` method and the ``renderer_globals`` Configurator constructor parameter. Users should - use convert code using this feature to use a BeforeRender event als - :ref:`beforerender_event`. + convert code using this feature to use a BeforeRender event. See the section + :ref:`beforerender_event` in the Hooks chapter. - In Pyramid 1.0, the :class:`pyramid.events.subscriber` directive behaved contrary to the documentation when passed more than one interface object to @@ -472,6 +568,31 @@ Deprecations and Behavior Differences def expects_object_event(object, event): print object, event +- In 1.0, if a :class:`pyramid.events.BeforeRender` event subscriber added a + value via the ``__setitem__`` or ``update`` methods of the event object + with a key that already existed in the renderer globals dictionary, a + ``KeyError`` was raised. With the deprecation of the + "add_renderer_globals" feature of the configurator, there was no way to + override an existing value in the renderer globals dictionary that already + existed. Now, the event object will overwrite an older value that is + already in the globals dictionary when its ``__setitem__`` or ``update`` is + called (as well as the new ``setdefault`` method), just like a plain old + dictionary. As a result, for maximum interoperability with other + third-party subscribers, if you write an event subscriber meant to be used + as a BeforeRender subscriber, your subscriber code will now need to (using + ``.get`` or ``__contains__`` of the event object) ensure no value already + exists in the renderer globals dictionary before setting an overriding + value. + +- The :meth:`pyramid.config.Configurator.add_route` method allowed two routes + with the same route to be added without an intermediate call to + :meth:`pyramid.config.Configurator.commit`. If you now receive a + ``ConfigurationError`` at startup time that appears to be ``add_route`` + related, you'll need to either a) ensure that all of your route names are + unique or b) call ``config.commit()`` before adding a second route with the + name of a previously added name or c) use a Configurator that works in + ``autocommit`` mode. + Dependency Changes ------------------ @@ -484,6 +605,9 @@ Dependency Changes Documentation Enhancements -------------------------- +- Added a section entitled :ref:`writing_a_script` to the "Command-Line + Pyramid" chapter. + - The :ref:`bfg_wiki_tutorial` was updated slightly. - The :ref:`bfg_sql_wiki_tutorial` was updated slightly. |