commit | author | age
|
41aeac
|
1 |
What's New in Pyramid 1.2 |
a8c81d
|
2 |
========================= |
CM |
3 |
|
|
4 |
This article explains the new features in :app:`Pyramid` version 1.2 as |
|
5 |
compared to its predecessor, :app:`Pyramid` 1.1. It also documents backwards |
|
6 |
incompatibilities between the two versions and deprecations added to Pyramid |
|
7 |
1.2, as well as software dependency changes and notable documentation |
|
8 |
additions. |
|
9 |
|
|
10 |
Major Feature Additions |
|
11 |
----------------------- |
|
12 |
|
|
13 |
The major feature additions in Pyramid 1.2 follow. |
|
14 |
|
6a7931
|
15 |
Debug Toolbar |
CM |
16 |
~~~~~~~~~~~~~ |
|
17 |
|
|
18 |
The scaffolding packages that come with Pyramid now include a debug toolbar |
|
19 |
component which can be used to interactively debug an application. See |
|
20 |
:ref:`debug_toolbar` for more information. |
|
21 |
|
a8c81d
|
22 |
``route_prefix`` Argument to include |
CM |
23 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
24 |
|
|
25 |
The :meth:`pyramid.config.Configurator.include` method now accepts a |
|
26 |
``route_prefix`` argument. This argument allows you to compose URL dispatch |
|
27 |
applications together from disparate packages. See :ref:`route_prefix` for |
|
28 |
more information. |
|
29 |
|
|
30 |
Tweens |
|
31 |
~~~~~~ |
|
32 |
|
|
33 |
A :term:`tween` is used to wrap the Pyramid router's primary request handling |
37607c
|
34 |
function. This is a feature that can be used by Pyramid framework extensions, |
CI |
35 |
to provide, for example, view timing support and can provide a convenient |
a9cdf8
|
36 |
place to hang bookkeeping code. Tweens are a little like :term:`WSGI` |
37607c
|
37 |
:term:`middleware`, but have access to Pyramid functionality such as renderers |
CI |
38 |
and a full-featured request object. |
a8c81d
|
39 |
|
CM |
40 |
To support this feature, a new configurator directive exists named |
|
41 |
:meth:`pyramid.config.Configurator.add_tween`. This directive adds a |
|
42 |
"tween". |
|
43 |
|
|
44 |
Tweens are further described in :ref:`registering_tweens`. |
|
45 |
|
|
46 |
A new paster command now exists: ``paster ptweens``. This command prints the |
|
47 |
current tween configuration for an application. See the section entitled |
|
48 |
:ref:`displaying_tweens` for more info. |
|
49 |
|
|
50 |
Scaffolding Changes |
|
51 |
~~~~~~~~~~~~~~~~~~~ |
|
52 |
|
|
53 |
- All scaffolds now use the ``pyramid_tm`` package rather than the |
37607c
|
54 |
``repoze.tm2`` :term:`middleware` to manage transaction management. |
a8c81d
|
55 |
|
CM |
56 |
- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the |
|
57 |
``repoze.zodbconn`` package to provide ZODB integration. |
|
58 |
|
|
59 |
- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the |
|
60 |
``WebError`` package to provide interactive debugging features. |
|
61 |
|
37607c
|
62 |
- Projects created via a scaffold no longer depend on the ``WebError`` package |
CI |
63 |
at all; configuration in the ``production.ini`` file which used to require |
|
64 |
its ``error_catcher`` :term:`middleware` has been removed. Configuring |
a8c81d
|
65 |
error catching / email sending is now the domain of the ``pyramid_exclog`` |
f75a3f
|
66 |
package (see http://docs.pylonsproject.org/projects/pyramid_exclog/dev/). |
a8c81d
|
67 |
|
d00fa0
|
68 |
- All scaffolds now send the ``cache_max_age`` parameter to the |
CM |
69 |
``add_static_view`` method. |
|
70 |
|
a8c81d
|
71 |
Minor Feature Additions |
CM |
72 |
----------------------- |
|
73 |
|
|
74 |
- The ``[pshell]`` section in an ini configuration file now treats a |
|
75 |
``setup`` key as a dotted name that points to a callable that is passed the |
|
76 |
bootstrap environment. It can mutate the environment as necessary during a |
|
77 |
``paster pshell`` session. This feature is described in |
|
78 |
:ref:`writing_a_script`. |
|
79 |
|
|
80 |
- A new configuration setting named ``pyramid.includes`` is now available. |
|
81 |
It is described in :ref:`including_packages`. |
|
82 |
|
|
83 |
- Added a :data:`pyramid.security.NO_PERMISSION_REQUIRED` constant for use in |
|
84 |
``permission=`` statements to view configuration. This constant has a |
|
85 |
value of the string ``__no_permission_required__``. This string value was |
|
86 |
previously referred to in documentation; now the documentation uses the |
|
87 |
constant. |
|
88 |
|
|
89 |
- Added a decorator-based way to configure a response adapter: |
|
90 |
:class:`pyramid.response.response_adapter`. This decorator has the same |
|
91 |
use as :meth:`pyramid.config.Configurator.add_response_adapter` but it's |
|
92 |
declarative. |
|
93 |
|
|
94 |
- The :class:`pyramid.events.BeforeRender` event now has an attribute named |
|
95 |
``rendering_val``. This can be used to introspect the value returned by a |
|
96 |
view in a BeforeRender subscriber. |
|
97 |
|
|
98 |
- The Pyramid debug logger now uses the standard logging configuration |
|
99 |
(usually set up by Paste as part of startup). This means that output from |
|
100 |
e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the |
|
101 |
normal logging channels. The logger name of the debug logger will be the |
|
102 |
package name of the *caller* of the Configurator's constructor. |
|
103 |
|
|
104 |
- A new attribute is available on request objects: ``exc_info``. Its value |
|
105 |
will be ``None`` until an exception is caught by the Pyramid router, after |
|
106 |
which it will be the result of ``sys.exc_info()``. |
|
107 |
|
|
108 |
- :class:`pyramid.testing.DummyRequest` now implements the |
|
109 |
``add_finished_callback`` and ``add_response_callback`` methods implemented |
|
110 |
by :class:`pyramid.request.Request`. |
|
111 |
|
|
112 |
- New methods of the :class:`pyramid.config.Configurator` class: |
|
113 |
:meth:`~pyramid.config.Configurator.set_authentication_policy` and |
|
114 |
:meth:`~pyramid.config.Configurator.set_authorization_policy`. These are |
|
115 |
meant to be consumed mostly by add-on authors who wish to offer packages |
|
116 |
which register security policies. |
|
117 |
|
|
118 |
- New Configurator method: |
|
119 |
:meth:`pyramid.config.Configurator.set_root_factory`, which can set the |
|
120 |
root factory after the Configurator has been constructed. |
|
121 |
|
|
122 |
- Pyramid no longer eagerly commits some default configuration statements at |
|
123 |
:term:`Configurator` construction time, which permits values passed in as |
|
124 |
constructor arguments (e.g. ``authentication_policy`` and |
|
125 |
``authorization_policy``) to override the same settings obtained via the |
|
126 |
:meth:`pyramid.config.Configurator.include` method. |
|
127 |
|
|
128 |
- Better Mako rendering exceptions; the template line which caused the error |
|
129 |
is now shown when a Mako rendering raises an exception. |
|
130 |
|
|
131 |
- New request methods: :meth:`~pyramid.request.Request.current_route_url`, |
|
132 |
:meth:`~pyramid.request.Request.current_route_path`, and |
|
133 |
:meth:`~pyramid.request.Request.static_path`. |
|
134 |
|
|
135 |
- New functions in the :mod:`pyramid.url` module: |
|
136 |
:func:`~pyramid.url.current_route_path` and |
|
137 |
:func:`~pyramid.url.static_path`. |
|
138 |
|
|
139 |
- The :meth:`pyramid.request.Request.static_url` API (and its brethren |
|
140 |
:meth:`pyramid.request.Request.static_path`, |
|
141 |
:func:`pyramid.url.static_url`, and :func:`pyramid.url.static_path`) now |
f4b088
|
142 |
accept an absolute filename as a "path" argument. This will generate a URL |
a8c81d
|
143 |
to an asset as long as the filename is in a directory which was previously |
CM |
144 |
registered as a static view. Previously, trying to generate a URL to an |
|
145 |
asset using an absolute file path would raise a ValueError. |
|
146 |
|
|
147 |
- The :class:`~pyramid.authentication.RemoteUserAuthenticationPolicy`, |
|
148 |
:class:`~pyramid.authentication.AuthTktAuthenticationPolicy`, and |
|
149 |
:class:`~pyramid.authentication.SessionAuthenticationPolicy` constructors |
|
150 |
now accept an additional keyword argument named ``debug``. By default, |
|
151 |
this keyword argument is ``False``. When it is ``True``, debug information |
|
152 |
will be sent to the Pyramid debug logger (usually on stderr) when the |
|
153 |
``authenticated_userid`` or ``effective_principals`` method is called on |
|
154 |
any of these policies. The output produced can be useful when trying to |
|
155 |
diagnose authentication-related problems. |
|
156 |
|
141f90
|
157 |
- New view predicate: ``match_param``. Example: a view added via |
CM |
158 |
``config.add_view(aview, match_param='action=edit')`` will be called only |
|
159 |
when the ``request.matchdict`` has a value inside it named ``action`` with |
|
160 |
a value of ``edit``. |
|
161 |
|
1aeae3
|
162 |
- Support an ``onerror`` keyword argument to |
50218d
|
163 |
:meth:`pyramid.config.Configurator.scan`. This argument is passed to |
1aeae3
|
164 |
:meth:`venusian.Scanner.scan` to influence error behavior when an exception |
CM |
165 |
is raised during scanning. |
|
166 |
|
49f082
|
167 |
- The ``request_method`` predicate argument to |
CM |
168 |
:meth:`pyramid.config.Configurator.add_view` and |
|
169 |
:meth:`pyramid.config.Configurator.add_route` is now permitted to be a |
|
170 |
tuple of HTTP method names. Previously it was restricted to being a string |
|
171 |
representing a single HTTP method name. |
|
172 |
|
33516a
|
173 |
- Undeprecated ``pyramid.traversal.find_model``, |
CM |
174 |
``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, |
|
175 |
and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. |
|
176 |
There's just not much cost to keeping them around forever as aliases to |
|
177 |
their renamed ``resource_*`` prefixed functions. |
|
178 |
|
|
179 |
- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid |
|
180 |
1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll |
|
181 |
just keep around forever. |
|
182 |
|
acec46
|
183 |
- Route pattern replacement marker names can now begin with an underscore. |
CM |
184 |
See https://github.com/Pylons/pyramid/issues/276. |
|
185 |
|
a8c81d
|
186 |
Deprecations |
CM |
187 |
------------ |
|
188 |
|
|
189 |
- All Pyramid-related :term:`deployment settings` (e.g. ``debug_all``, |
|
190 |
``debug_notfound``) are now meant to be prefixed with the prefix |
|
191 |
``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The |
|
192 |
old non-prefixed settings will continue to work indefinitely but supplying |
|
193 |
them may print a deprecation warning. All scaffolds and tutorials have |
|
194 |
been changed to use prefixed settings. |
|
195 |
|
|
196 |
- The :term:`deployment settings` dictionary now raises a deprecation warning |
|
197 |
when you attempt to access its values via ``__getattr__`` instead of via |
|
198 |
``__getitem__``. |
|
199 |
|
|
200 |
Backwards Incompatibilities |
|
201 |
--------------------------- |
|
202 |
|
|
203 |
- If a string is passed as the ``debug_logger`` parameter to a |
|
204 |
:term:`Configurator`, that string is considered to be the name of a global |
|
205 |
Python logger rather than a dotted name to an instance of a logger. |
|
206 |
|
|
207 |
- The :meth:`pyramid.config.Configurator.include` method now accepts only a |
|
208 |
single ``callable`` argument. A *sequence* of callables used to be |
|
209 |
permitted. If you are passing more than one ``callable`` to |
|
210 |
:meth:`pyramid.config.Configurator.include`, it will break. You now must |
|
211 |
now instead make a separate call to the method for each callable. |
|
212 |
|
04b7ea
|
213 |
- It may be necessary to more strictly order configuration route and view |
CM |
214 |
statements when using an "autocommitting" :term:`Configurator`. In the |
|
215 |
past, it was possible to add a view which named a route name before adding |
|
216 |
a route with that name when you used an autocommitting configurator. For |
|
217 |
example: |
|
218 |
|
|
219 |
.. code-block:: python |
|
220 |
|
|
221 |
config = Configurator(autocommit=True) |
|
222 |
config.add_view('my.pkg.someview', route_name='foo') |
|
223 |
config.add_route('foo', '/foo') |
|
224 |
|
|
225 |
The above will raise an exception when the view attempts to add itself. |
|
226 |
Now you must add the route before adding the view: |
|
227 |
|
|
228 |
.. code-block:: python |
|
229 |
|
|
230 |
config = Configurator(autocommit=True) |
|
231 |
config.add_route('foo', '/foo') |
|
232 |
config.add_view('my.pkg.someview', route_name='foo') |
|
233 |
|
|
234 |
This won't effect "normal" users, only people who have legacy BFG codebases |
|
235 |
that used an autommitting configurator and possibly tests that use the |
|
236 |
configurator API (the configurator returned by |
|
237 |
:func:`pyramid.testing.setUp` is an autocommitting configurator). The |
|
238 |
right way to get around this is to use a default non-autocommitting |
|
239 |
configurator, which does not have these directive ordering requirements: |
|
240 |
|
|
241 |
.. code-block:: python |
|
242 |
|
|
243 |
config = Configurator() |
|
244 |
config.add_view('my.pkg.someview', route_name='foo') |
|
245 |
config.add_route('foo', '/foo') |
|
246 |
|
|
247 |
The above will work fine. |
|
248 |
|
|
249 |
- The :meth:`pyramid.config.Configurator.add_route` directive no longer |
|
250 |
returns a route object. This change was required to make route vs. view |
|
251 |
configuration processing work properly. |
|
252 |
|
d00fa0
|
253 |
Behavior Differences |
CM |
254 |
-------------------- |
|
255 |
|
|
256 |
- An ETag header is no longer set when serving a static file. A |
|
257 |
Last-Modified header is set instead. |
|
258 |
|
|
259 |
- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. |
|
260 |
|
|
261 |
- Instead of returning a ``403 Forbidden`` error when a static file is served |
|
262 |
that cannot be accessed by the Pyramid process' user due to file |
|
263 |
permissions, an IOError (or similar) will be raised. |
|
264 |
|
a8c81d
|
265 |
Documentation Enhancements |
CM |
266 |
-------------------------- |
|
267 |
|
|
268 |
- Narrative and API documentation which used the ``route_url``, |
|
269 |
``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` |
|
270 |
functions in the :mod:`pyramid.url` package have now been changed to use |
|
271 |
eponymous methods of the request instead. |
|
272 |
|
|
273 |
- Added a section entitled :ref:`route_prefix` to the "URL Dispatch" |
|
274 |
narrative documentation chapter. |
|
275 |
|
|
276 |
- Added a new module to the API docs: :mod:`pyramid.tweens`. |
|
277 |
|
|
278 |
- Added a :ref:`registering_tweens` section to the "Hooks" narrative chapter. |
|
279 |
|
|
280 |
- Added a :ref:`displaying_tweens` section to the "Command-Line Pyramid" |
|
281 |
narrative chapter. |
|
282 |
|
|
283 |
- Added documentation for :ref:`explicit_tween_config` and |
|
284 |
:ref:`including_packages` to the "Environment Variables and ``.ini`` Files |
|
285 |
Settings" chapter. |
|
286 |
|
|
287 |
- Added a :ref:`logging_chapter` chapter to the narrative docs. |
|
288 |
|
|
289 |
- All tutorials now use - The ``route_url``, ``route_path``, |
|
290 |
``resource_url``, ``static_url``, and ``current_route_url`` methods of the |
|
291 |
:class:`pyramid.request.Request` rather than the function variants imported |
|
292 |
from ``pyramid.url``. |
|
293 |
|
|
294 |
- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather |
|
295 |
than the ``repoze.zodbconn`` package to provide ZODB integration. |
|
296 |
|
d8fc16
|
297 |
- Added :ref:`what_makes_pyramid_unique` to the Introduction narrative |
CM |
298 |
chapter. |
|
299 |
|
|
300 |
|
a8c81d
|
301 |
Dependency Changes |
CM |
302 |
------------------ |
|
303 |
|
|
304 |
- Pyramid now relies on PasteScript >= 1.7.4. This version contains a |
|
305 |
feature important for allowing flexible logging configuration. |
|
306 |
|
1aeae3
|
307 |
- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` |
CM |
308 |
keyword argument to :meth:`pyramid.config.Configurator.scan`. |
061154
|
309 |
|
CM |
310 |
- The ``zope.configuration`` package is no longer a dependency. |