From fcd7045e051632c6e43227c44ac540d4d655d1dd Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 15 Sep 2012 23:26:01 -0400 Subject: really add whatsnew-1.4 --- docs/whatsnew-1.4.rst | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 docs/whatsnew-1.4.rst (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst new file mode 100644 index 000000000..58a44202c --- /dev/null +++ b/docs/whatsnew-1.4.rst @@ -0,0 +1,250 @@ +What's New In Pyramid 1.4 +========================= + +This article explains the new features in :app:`Pyramid` version 1.4 as +compared to its predecessor, :app:`Pyramid` 1.3. It also documents backwards +incompatibilities between the two versions and deprecations added to +:app:`Pyramid` 1.4, as well as software dependency changes and notable +documentation additions. + +Major Feature Additions +----------------------- + +The major feature additions in Pyramid 1.4 follow. + +Third-Party Predicates +~~~~~~~~~~~~~~~~~~~~~~~ + +- Third-party custom view, route, and subscriber predicates can now be added + for use by view authors via + :meth:`pyramid.config.Configurator.add_view_predicate`, + :meth:`pyramid.config.Configurator.add_route_predicate` and + :meth:`pyramid.config.Configurator.add_subscriber_predicate`. So, for + example, doing this:: + + config.add_view_predicate('abc', my.package.ABCPredicate) + + Might allow a view author to do this in an application that configured that + predicate:: + + @view_config(abc=1) + + Similar features exist for :meth:`pyramid.config.Configurator.add_route`, + and :meth:`pyramid.config.Configurator.add_subscriber`. See + :ref:`registering_thirdparty_predicates` for more information. + +Easy Custom JSON Serialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Views can now return custom objects which will be serialized to JSON by a + JSON renderer by defining a ``__json__`` method on the object's class. This + method should return values natively serializable by ``json.dumps`` (such + as ints, lists, dictionaries, strings, and so forth). See + :ref:`json_serializing_custom_objects` for more information. The JSON + renderer now also allows for the definition of custom type adapters to + convert unknown objects to JSON serializations, in case you can't add a + ``__json__`` method to returned objects. + +Partial Mako and Chameleon Template Renderings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The Mako renderer now supports using a def name in an asset spec. When the + def name is present in the asset spec, the system will render the template + named def within the template instead of rendering the entire template. An + example asset spec which names a def is + ``package:path/to/template#defname.mako``. This will render the def named + ``defname`` inside the ``template.mako`` template instead of rendering the + entire template. The old way of returning a tuple in the form + ``('defname', {})`` from the view is supported for backward compatibility. + +- The Chameleon ZPT renderer now supports using a macro name in an asset + spec. When the macro name is present in the asset spec, the system will + render the macro listed as a ``define-macro`` and return the result instead + of rendering the entire template. An example asset spec: + ``package:path/to/template#macroname.pt``. This will render the macro + defined as ``macroname`` within the ``template.pt`` template instead of the + entire templae. + +Minor Feature Additions +----------------------- + +- :meth:`pyramid.config.Configurator.add_directive` now accepts arbitrary + callables like partials or objects implementing ``__call__`` which dont + have ``__name__`` and ``__doc__`` attributes. See + https://github.com/Pylons/pyramid/issues/621 and + https://github.com/Pylons/pyramid/pull/647. + +- As of this release, the ``request_method`` view/route predicate, when used, + will also imply that ``HEAD`` is implied when you use ``GET``. For + example, using ``@view_config(request_method='GET')`` is equivalent to + using ``@view_config(request_method=('GET', 'HEAD'))``. Using + ``@view_config(request_method=('GET', 'POST')`` is equivalent to using + ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because + HEAD is a variant of GET that omits the body, and WebOb has special support + to return an empty body when a HEAD is used. + +- :meth:`pyramid.config.Configurator.add_request_method` has been introduced + to support extending request objects with arbitrary callables. This method + expands on the previous + :meth:`pyramid.config.Configurator.set_request_property` by supporting + methods as well as properties. This method causes less code to be executed + at request construction time than + :meth:`~pyramid.config.Configurator.set_request_property`. + +- The static view machinery now raises rather than returns + :class:`pyramid.httpexceptions.HTTPNotFound` and + :class:`pyramid.httpexceptions.HTTPMovedPermanently` exceptions, so these can + be caught by the notfound view (and other exception views). + +- When there is a predicate mismatch exception (seen when no view matches for + a given request due to predicates not working), the exception now contains + a textual description of the predicate which didn't match. + +- An :meth:`pyramid.config.Configurator.add_permission` directive method was + added to the Configurator. This directive registers a free-standing + permission introspectable into the Pyramid introspection system. + Frameworks built atop Pyramid can thus use the the ``permissions`` + introspectable category data to build a comprehensive list of permissions + supported by a running system. Before this method was added, permissions + were already registered in this introspectable category as a side effect of + naming them in an :meth:`pyramid.config.Configurator.add_view` call, this + method just makes it possible to arrange for a permission to be put into + the ``permissions`` introspectable category without naming it along with an + associated view. Here's an example of usage of ``add_permission``:: + + config = Configurator() + config.add_permission('view') + +- The :func:`pyramid.session.UnencryptedCookieSessionFactoryConfig` function + now accepts ``signed_serialize`` and ``signed_deserialize`` hooks which may + be used to influence how the sessions are marshalled (by default this is + done with HMAC+pickle). + +- :class:`pyramid.testing.DummyRequest` now supports methods supplied by the + ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. + +- Request properties and methods added via + :meth:`pyramid.config.Configurator.set_request_property` or + :meth:`pyramid.config.Configurator.add_request_method` are now available to + tweens. + +- Request properties and methods added via + :meth:`pyramid.config.Configurator.set_request_property` or + :meth:`pyramid.config.Configurator.add_request_method` are now available + in the request object returned from :func:`pyramid.paster.bootstrap`. + +- ``request.context`` of environment request during + :func:`pyramid.paster.bootstrap` is now the root object if a context isn't + already set on a provided request. + +- :class:`pyramid.decorator.reify` is now an API, and was added to + the API documentation. + +- Added the :func:`pyramid.testing.testConfig` context manager, which can be + used to generate a configurator in a test, e.g. ``with + testing.testConfig(...):``. + +Backwards Incompatibilities +--------------------------- + +- The Pyramid router no longer adds the values ``bfg.routes.route`` or + ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. + These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven + minor releases ago). If your code depended on these values, use + request.matched_route and request.matchdict instead. + +- It is no longer possible to pass an environ dictionary directly to + ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka + ``ModelGraphTraverser.__call__``). Instead, you must pass a request + object. Passing an environment instead of a request has generated a + deprecation warning since Pyramid 1.1. + +- Pyramid will no longer work properly if you use the + ``webob.request.LegacyRequest`` as a request factory. Instances of the + LegacyRequest class have a ``request.path_info`` which return a string. + This Pyramid release assumes that ``request.path_info`` will + unconditionally be Unicode. + +- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` + named ``get_renderer``, ``get_template``, ``render_template``, and + ``render_template_to_response`` have been removed. These have issued a + deprecation warning upon import since Pyramid 1.0. Use + :func:`pyramid.renderers.get_renderer`, + ``pyramid.renderers.get_renderer().implementation()``, + :func:`pyramid.renderers.render` or + :func:`pyramid.renderers.render_to_response` respectively instead of these + functions. + +- The ``pyramid.configuration`` module was removed. It had been deprecated + since Pyramid 1.0 and printed a deprecation warning upon its use. Use + :mod:`pyramid.config` instead. + +- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been + deprecated since Pyramid 1.1 and issued a warning on import. If your code + depended on this, adjust your code to import + :class:`pyramid.scaffolds.PyramidTemplate` instead. + +- The ``pyramid.settings.get_settings()`` API was removed. It had been + printing a deprecation warning since Pyramid 1.0. If your code depended on + this API, use ``pyramid.threadlocal.get_current_registry().settings`` + instead or use the ``settings`` attribute of the registry available from + the request (``request.registry.settings``). + +- These APIs from the ``pyramid.testing`` module were removed. They have + been printing deprecation warnings since Pyramid 1.0: + + * ``registerDummySecurityPolicy``, use + :meth:`pyramid.config.Configurator.testing_securitypolicy` instead. + + * ``registerResources`` (aka ``registerModels``), use + :meth:`pyramid.config.Configurator.testing_resources` instead. + + * ``registerEventListener``, use + :meth:`pyramid.config.Configurator.testing_add_subscriber` instead. + + * ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use + :meth:`pyramid.config.Configurator.testing_add_template` instead. + + * ``registerView``, use :meth:`pyramid.config.Configurator.add_view` instead. + + * ``registerUtility``, use + :meth:`pyramid.config.Configurator.registry.registerUtility` instead. + + * ``registerAdapter``, use + :meth:`pyramid.config.Configurator.registry.registerAdapter` instead. + + * ``registerSubscriber``, use + :meth:`pyramid.config.Configurator.add_subscriber` instead. + + * ``registerRoute``, use + :meth:`pyramid.config.Configurator.add_route` instead. + + * ``registerSettings``, use + :meth:`pyramid.config.Configurator.add_settings` instead. + +Deprecations +------------ + +- The :meth:`pyramid.config.Configurator.set_request_property` directive has + been documentation-deprecated. The method remains usable but the more + featureful :meth:`pyramid.config.Configurator.add_request_method` should be + used in its place (it has all of the same capabilities but can also extend + the request object with methods). + +Documentation Enhancements +-------------------------- + +- Added an :ref:`upgrading_chapter` chapter to the narrative documentation. + It describes how to cope with deprecations and removals of Pyramid APIs and + how to show Pyramid-generated deprecation warnings while running tests and + while running a server. + +- Many cleanups and improvements to narrative and API docs. + +Dependency Changes +------------------ + +- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on + 1.2dev+). This is to ensure that we obtain a version of WebOb that returns + ``request.path_info`` as text. + -- cgit v1.2.3 From 37d2c224b804dfebe9ee217c7a536364eacdee15 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 03:25:17 -0400 Subject: docs and test --- docs/whatsnew-1.4.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 58a44202c..70d5f12a7 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -65,6 +65,14 @@ Partial Mako and Chameleon Template Renderings defined as ``macroname`` within the ``template.pt`` template instead of the entire templae. +Subrequest Support +~~~~~~~~~~~~~~~~~~ + +- Developers may invoke a subrequest by using the + :meth:`pyramid.request.Request.subrequest` API. This allows a developer to + obtain a response from one view callable by issuing a subrequest from within + a different view callable. + Minor Feature Additions ----------------------- @@ -239,6 +247,8 @@ Documentation Enhancements how to show Pyramid-generated deprecation warnings while running tests and while running a server. +- Added a :ref:`subrequest_chapter` chapter to the narrative documentation. + - Many cleanups and improvements to narrative and API docs. Dependency Changes -- cgit v1.2.3 From 64452edb014423054d1bbc0bb3ed8a3e47b6f611 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 03:54:08 -0400 Subject: rename subrequest to invoke_subrequest --- docs/whatsnew-1.4.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 70d5f12a7..8e333bf5d 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -69,9 +69,9 @@ Subrequest Support ~~~~~~~~~~~~~~~~~~ - Developers may invoke a subrequest by using the - :meth:`pyramid.request.Request.subrequest` API. This allows a developer to - obtain a response from one view callable by issuing a subrequest from within - a different view callable. + :meth:`pyramid.request.Request.invoke_subrequest` API. This allows a + developer to obtain a response from one view callable by issuing a subrequest + from within a different view callable. Minor Feature Additions ----------------------- @@ -230,6 +230,12 @@ Backwards Incompatibilities * ``registerSettings``, use :meth:`pyramid.config.Configurator.add_settings` instead. +- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object + returned by a view was invoked before any finished callbacks were executed. + As of this release, the ``__call__`` method of a Response object is invoked + *after* finished callbacks are executed. This is in support of the + :meth:`pyramid.request.Request.invoke_subrequest` feature. + Deprecations ------------ -- cgit v1.2.3 From 355ed0f0063d37cddfc3d315c7a32cb9e9a2987c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 03:56:42 -0400 Subject: pointer --- docs/whatsnew-1.4.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 8e333bf5d..f57178db1 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -71,7 +71,8 @@ Subrequest Support - Developers may invoke a subrequest by using the :meth:`pyramid.request.Request.invoke_subrequest` API. This allows a developer to obtain a response from one view callable by issuing a subrequest - from within a different view callable. + from within a different view callable. See :ref:`subrequest_chapter` for + more information. Minor Feature Additions ----------------------- -- cgit v1.2.3 From 0436567f2f4bd92e9769890befc77aae54d5ea36 Mon Sep 17 00:00:00 2001 From: Philip Jenvey Date: Tue, 18 Sep 2012 13:54:27 -0700 Subject: mention set_request_property's doc-deprecation up above as well, make add_request_method more prominent --- docs/whatsnew-1.4.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index f57178db1..ddc602271 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -94,10 +94,10 @@ Minor Feature Additions - :meth:`pyramid.config.Configurator.add_request_method` has been introduced to support extending request objects with arbitrary callables. This method - expands on the previous + expands on the now documentation-deprecated :meth:`pyramid.config.Configurator.set_request_property` by supporting - methods as well as properties. This method causes less code to be executed - at request construction time than + methods as well as properties. This method also causes less code to be + executed at request construction time than :meth:`~pyramid.config.Configurator.set_request_property`. - The static view machinery now raises rather than returns @@ -133,13 +133,13 @@ Minor Feature Additions ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. - Request properties and methods added via - :meth:`pyramid.config.Configurator.set_request_property` or - :meth:`pyramid.config.Configurator.add_request_method` are now available to + :meth:`pyramid.config.Configurator.add_request_method` or + :meth:`pyramid.config.Configurator.set_request_property` are now available to tweens. - Request properties and methods added via - :meth:`pyramid.config.Configurator.set_request_property` or - :meth:`pyramid.config.Configurator.add_request_method` are now available + :meth:`pyramid.config.Configurator.add_request_method` or + :meth:`pyramid.config.Configurator.set_request_property` are now available in the request object returned from :func:`pyramid.paster.bootstrap`. - ``request.context`` of environment request during -- cgit v1.2.3 From 68c00de2f71f95571c1876d024c9ad5d4dfeec2c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 19 Sep 2012 03:30:18 -0400 Subject: add check_csrf convenience function --- docs/whatsnew-1.4.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index f57178db1..fc25c415e 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -153,6 +153,9 @@ Minor Feature Additions used to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. +- A new :func:`pyramid.session.check_csrf_token` convenience API function was + added. + Backwards Incompatibilities --------------------------- -- cgit v1.2.3 From 643a83473a6faabd0ff08547a0cbca09e9cdda1c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 19 Sep 2012 04:46:01 -0400 Subject: A ``check_csrf`` view predicate was added. For example, you can now do ``config.add_view(someview, check_csrf=True)``. When the predicate is checked, if the ``csrf_token`` value in ``request.params`` matches the csrf token in the request's session, the view will be permitted to execute. Otherwise, it will not be permitted to execute. --- docs/whatsnew-1.4.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 76320f6e6..86bfc7c0a 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -156,6 +156,12 @@ Minor Feature Additions - A new :func:`pyramid.session.check_csrf_token` convenience API function was added. +- A ``check_csrf`` view predicate was added. For example, you can now do + ``config.add_view(someview, check_csrf=True)``. When the predicate is + checked, if the ``csrf_token`` value in ``request.params`` matches the csrf + token in the request's session, the view will be permitted to execute. + Otherwise, it will not be permitted to execute. + Backwards Incompatibilities --------------------------- -- cgit v1.2.3 From 072cbf7ae84e80185ebc122d0c11a6838ac36093 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Sep 2012 11:40:57 -0400 Subject: prep for 1.4a2 --- docs/whatsnew-1.4.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/whatsnew-1.4.rst') diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 86bfc7c0a..4e64d8162 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -162,6 +162,9 @@ Minor Feature Additions token in the request's session, the view will be permitted to execute. Otherwise, it will not be permitted to execute. +- Add ``Base.metadata.bind = engine`` to ``alchemy`` scaffold, so that tables + defined imperatively will work. + Backwards Incompatibilities --------------------------- -- cgit v1.2.3