commit | author | age
|
41aeac
|
1 |
What's New in Pyramid 1.4 |
fcd704
|
2 |
========================= |
CM |
3 |
|
|
4 |
This article explains the new features in :app:`Pyramid` version 1.4 as |
|
5 |
compared to its predecessor, :app:`Pyramid` 1.3. It also documents backwards |
|
6 |
incompatibilities between the two versions and deprecations added to |
|
7 |
:app:`Pyramid` 1.4, as well as software dependency changes and notable |
|
8 |
documentation additions. |
|
9 |
|
|
10 |
Major Feature Additions |
|
11 |
----------------------- |
|
12 |
|
|
13 |
The major feature additions in Pyramid 1.4 follow. |
|
14 |
|
|
15 |
Third-Party Predicates |
|
16 |
~~~~~~~~~~~~~~~~~~~~~~~ |
|
17 |
|
|
18 |
- Third-party custom view, route, and subscriber predicates can now be added |
|
19 |
for use by view authors via |
|
20 |
:meth:`pyramid.config.Configurator.add_view_predicate`, |
|
21 |
:meth:`pyramid.config.Configurator.add_route_predicate` and |
|
22 |
:meth:`pyramid.config.Configurator.add_subscriber_predicate`. So, for |
|
23 |
example, doing this:: |
|
24 |
|
|
25 |
config.add_view_predicate('abc', my.package.ABCPredicate) |
|
26 |
|
|
27 |
Might allow a view author to do this in an application that configured that |
|
28 |
predicate:: |
|
29 |
|
|
30 |
@view_config(abc=1) |
|
31 |
|
|
32 |
Similar features exist for :meth:`pyramid.config.Configurator.add_route`, |
|
33 |
and :meth:`pyramid.config.Configurator.add_subscriber`. See |
|
34 |
:ref:`registering_thirdparty_predicates` for more information. |
|
35 |
|
|
36 |
Easy Custom JSON Serialization |
|
37 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
38 |
|
|
39 |
- Views can now return custom objects which will be serialized to JSON by a |
|
40 |
JSON renderer by defining a ``__json__`` method on the object's class. This |
|
41 |
method should return values natively serializable by ``json.dumps`` (such |
|
42 |
as ints, lists, dictionaries, strings, and so forth). See |
|
43 |
:ref:`json_serializing_custom_objects` for more information. The JSON |
|
44 |
renderer now also allows for the definition of custom type adapters to |
|
45 |
convert unknown objects to JSON serializations, in case you can't add a |
|
46 |
``__json__`` method to returned objects. |
|
47 |
|
|
48 |
Partial Mako and Chameleon Template Renderings |
|
49 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
50 |
|
|
51 |
- The Mako renderer now supports using a def name in an asset spec. When the |
|
52 |
def name is present in the asset spec, the system will render the template |
|
53 |
named def within the template instead of rendering the entire template. An |
|
54 |
example asset spec which names a def is |
|
55 |
``package:path/to/template#defname.mako``. This will render the def named |
|
56 |
``defname`` inside the ``template.mako`` template instead of rendering the |
|
57 |
entire template. The old way of returning a tuple in the form |
|
58 |
``('defname', {})`` from the view is supported for backward compatibility. |
|
59 |
|
|
60 |
- The Chameleon ZPT renderer now supports using a macro name in an asset |
|
61 |
spec. When the macro name is present in the asset spec, the system will |
|
62 |
render the macro listed as a ``define-macro`` and return the result instead |
|
63 |
of rendering the entire template. An example asset spec: |
|
64 |
``package:path/to/template#macroname.pt``. This will render the macro |
|
65 |
defined as ``macroname`` within the ``template.pt`` template instead of the |
1affe4
|
66 |
entire template. |
fcd704
|
67 |
|
37d2c2
|
68 |
Subrequest Support |
CM |
69 |
~~~~~~~~~~~~~~~~~~ |
|
70 |
|
|
71 |
- Developers may invoke a subrequest by using the |
64452e
|
72 |
:meth:`pyramid.request.Request.invoke_subrequest` API. This allows a |
CM |
73 |
developer to obtain a response from one view callable by issuing a subrequest |
355ed0
|
74 |
from within a different view callable. See :ref:`subrequest_chapter` for |
CM |
75 |
more information. |
37d2c2
|
76 |
|
fcd704
|
77 |
Minor Feature Additions |
CM |
78 |
----------------------- |
|
79 |
|
2063ed
|
80 |
- :class:`pyramid.authentication.AuthTktAuthenticationPolicy` has been updated |
CM |
81 |
to support newer hashing algorithms such as ``sha512``. Existing applications |
|
82 |
should consider updating if possible for improved security over the default |
|
83 |
md5 hashing. |
|
84 |
|
fcd704
|
85 |
- :meth:`pyramid.config.Configurator.add_directive` now accepts arbitrary |
1affe4
|
86 |
callables like partials or objects implementing ``__call__`` which don't |
fcd704
|
87 |
have ``__name__`` and ``__doc__`` attributes. See |
CM |
88 |
https://github.com/Pylons/pyramid/issues/621 and |
|
89 |
https://github.com/Pylons/pyramid/pull/647. |
|
90 |
|
|
91 |
- As of this release, the ``request_method`` view/route predicate, when used, |
|
92 |
will also imply that ``HEAD`` is implied when you use ``GET``. For |
|
93 |
example, using ``@view_config(request_method='GET')`` is equivalent to |
|
94 |
using ``@view_config(request_method=('GET', 'HEAD'))``. Using |
|
95 |
``@view_config(request_method=('GET', 'POST')`` is equivalent to using |
|
96 |
``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because |
|
97 |
HEAD is a variant of GET that omits the body, and WebOb has special support |
|
98 |
to return an empty body when a HEAD is used. |
|
99 |
|
|
100 |
- :meth:`pyramid.config.Configurator.add_request_method` has been introduced |
|
101 |
to support extending request objects with arbitrary callables. This method |
043656
|
102 |
expands on the now documentation-deprecated |
fcd704
|
103 |
:meth:`pyramid.config.Configurator.set_request_property` by supporting |
043656
|
104 |
methods as well as properties. This method also causes less code to be |
PJ |
105 |
executed at request construction time than |
fcd704
|
106 |
:meth:`~pyramid.config.Configurator.set_request_property`. |
CM |
107 |
|
|
108 |
- The static view machinery now raises rather than returns |
|
109 |
:class:`pyramid.httpexceptions.HTTPNotFound` and |
|
110 |
:class:`pyramid.httpexceptions.HTTPMovedPermanently` exceptions, so these can |
cec2b0
|
111 |
be caught by the Not Found View (and other exception views). |
fcd704
|
112 |
|
CM |
113 |
- When there is a predicate mismatch exception (seen when no view matches for |
|
114 |
a given request due to predicates not working), the exception now contains |
|
115 |
a textual description of the predicate which didn't match. |
|
116 |
|
|
117 |
- An :meth:`pyramid.config.Configurator.add_permission` directive method was |
|
118 |
added to the Configurator. This directive registers a free-standing |
|
119 |
permission introspectable into the Pyramid introspection system. |
1affe4
|
120 |
Frameworks built atop Pyramid can thus use the ``permissions`` |
fcd704
|
121 |
introspectable category data to build a comprehensive list of permissions |
CM |
122 |
supported by a running system. Before this method was added, permissions |
|
123 |
were already registered in this introspectable category as a side effect of |
|
124 |
naming them in an :meth:`pyramid.config.Configurator.add_view` call, this |
|
125 |
method just makes it possible to arrange for a permission to be put into |
|
126 |
the ``permissions`` introspectable category without naming it along with an |
|
127 |
associated view. Here's an example of usage of ``add_permission``:: |
|
128 |
|
|
129 |
config = Configurator() |
|
130 |
config.add_permission('view') |
|
131 |
|
|
132 |
- The :func:`pyramid.session.UnencryptedCookieSessionFactoryConfig` function |
|
133 |
now accepts ``signed_serialize`` and ``signed_deserialize`` hooks which may |
|
134 |
be used to influence how the sessions are marshalled (by default this is |
|
135 |
done with HMAC+pickle). |
|
136 |
|
|
137 |
- :class:`pyramid.testing.DummyRequest` now supports methods supplied by the |
|
138 |
``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. |
|
139 |
|
|
140 |
- Request properties and methods added via |
043656
|
141 |
:meth:`pyramid.config.Configurator.add_request_method` or |
PJ |
142 |
:meth:`pyramid.config.Configurator.set_request_property` are now available to |
fcd704
|
143 |
tweens. |
CM |
144 |
|
|
145 |
- Request properties and methods added via |
043656
|
146 |
:meth:`pyramid.config.Configurator.add_request_method` or |
PJ |
147 |
:meth:`pyramid.config.Configurator.set_request_property` are now available |
fcd704
|
148 |
in the request object returned from :func:`pyramid.paster.bootstrap`. |
CM |
149 |
|
|
150 |
- ``request.context`` of environment request during |
|
151 |
:func:`pyramid.paster.bootstrap` is now the root object if a context isn't |
|
152 |
already set on a provided request. |
|
153 |
|
|
154 |
- :class:`pyramid.decorator.reify` is now an API, and was added to |
|
155 |
the API documentation. |
|
156 |
|
|
157 |
- Added the :func:`pyramid.testing.testConfig` context manager, which can be |
|
158 |
used to generate a configurator in a test, e.g. ``with |
|
159 |
testing.testConfig(...):``. |
|
160 |
|
68c00d
|
161 |
- A new :func:`pyramid.session.check_csrf_token` convenience API function was |
CM |
162 |
added. |
|
163 |
|
643a83
|
164 |
- A ``check_csrf`` view predicate was added. For example, you can now do |
CM |
165 |
``config.add_view(someview, check_csrf=True)``. When the predicate is |
|
166 |
checked, if the ``csrf_token`` value in ``request.params`` matches the csrf |
|
167 |
token in the request's session, the view will be permitted to execute. |
|
168 |
Otherwise, it will not be permitted to execute. |
|
169 |
|
072cbf
|
170 |
- Add ``Base.metadata.bind = engine`` to ``alchemy`` scaffold, so that tables |
CM |
171 |
defined imperatively will work. |
|
172 |
|
4a6cca
|
173 |
- Comments with references to documentation sections placed in scaffold |
CM |
174 |
``.ini`` files. |
|
175 |
|
|
176 |
- Allow multiple values to be specified to the ``request_param`` view/route |
|
177 |
predicate as a sequence. Previously only a single string value was allowed. |
|
178 |
See https://github.com/Pylons/pyramid/pull/705 |
|
179 |
|
|
180 |
- Added an HTTP Basic authentication policy |
|
181 |
at :class:`pyramid.authentication.BasicAuthAuthenticationPolicy`. |
|
182 |
|
|
183 |
- The :meth:`pyramid.config.Configurator.testing_securitypolicy` method now |
|
184 |
returns the policy object it creates. |
|
185 |
|
|
186 |
- The DummySecurityPolicy created by |
50218d
|
187 |
:meth:`pyramid.config.Configurator.testing_securitypolicy` now sets a |
TL |
188 |
``forgotten`` value on the policy (the value ``True``) when its ``forget`` |
|
189 |
method is called. |
4a6cca
|
190 |
|
CM |
191 |
- The DummySecurityPolicy created by |
50218d
|
192 |
:meth:`pyramid.config.Configurator.testing_securitypolicy` now sets a |
4a6cca
|
193 |
``remembered`` value on the policy, which is the value of the ``principal`` |
CM |
194 |
argument it's called with when its ``remember`` method is called. |
|
195 |
|
|
196 |
- New ``physical_path`` view predicate. If specified, this value should be a |
|
197 |
string or a tuple representing the physical traversal path of the context |
|
198 |
found via traversal for this predicate to match as true. For example: |
|
199 |
``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', |
|
200 |
'a', 'b', 'c')``. It's useful when you want to always potentially show a |
|
201 |
view when some object is traversed to, but you can't be sure about what kind |
|
202 |
of object it will be, so you can't use the ``context`` predicate. |
2063ed
|
203 |
|
CM |
204 |
- Added an ``effective_principals`` route and view predicate. |
|
205 |
|
|
206 |
- Do not allow the userid returned from the |
|
207 |
:func:`pyramid.security.authenticated_userid` or the userid that is one of the |
|
208 |
list of principals returned by :func:`pyramid.security.effective_principals` |
|
209 |
to be either of the strings ``system.Everyone`` or ``system.Authenticated`` |
|
210 |
when any of the built-in authorization policies that live in |
|
211 |
:mod:`pyramid.authentication` are in use. These two strings are reserved for |
|
212 |
internal usage by Pyramid and they will no longer be accepted as valid |
|
213 |
userids. |
|
214 |
|
|
215 |
- Allow a ``_depth`` argument to :class:`pyramid.view.view_config`, which will |
|
216 |
permit limited composition reuse of the decorator by other software that |
|
217 |
wants to provide custom decorators that are much like view_config. |
|
218 |
|
|
219 |
- Allow an iterable of decorators to be passed to |
|
220 |
:meth:`pyramid.config.Configurator.add_view`. This allows views to be wrapped |
|
221 |
by more than one decorator without requiring combining the decorators |
|
222 |
yourself. |
|
223 |
|
|
224 |
- :func:`pyramid.security.view_execution_permitted` used to return `True` if no |
|
225 |
view could be found. It now raises a :exc:`TypeError` exception in that case, |
|
226 |
as it doesn't make sense to assert that a nonexistent view is |
|
227 |
execution-permitted. See https://github.com/Pylons/pyramid/issues/299. |
4a6cca
|
228 |
|
50fdf8
|
229 |
- Small microspeed enhancement which anticipates that a |
CM |
230 |
:class:`pyramid.response.Response` object is likely to be returned from a |
|
231 |
view. Some code is shortcut if the class of the object returned by a view is |
|
232 |
this class. A similar microoptimization was done to |
|
233 |
:func:`pyramid.request.Request.is_response`. |
|
234 |
|
|
235 |
- Make it possible to use variable arguments on all ``p*`` commands |
|
236 |
(``pserve``, ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can |
|
237 |
fill in values in parameterized ``.ini`` file, e.g. ``pshell |
|
238 |
etc/development.ini http_port=8080``. |
|
239 |
|
|
240 |
- In order to allow people to ignore unused arguments to subscriber callables |
|
241 |
and to normalize the relationship between event subscribers and subscriber |
|
242 |
predicates, we now allow both subscribers and subscriber predicates to accept |
|
243 |
only a single ``event`` argument even if they've been subscribed for |
|
244 |
notifications that involve multiple interfaces. |
|
245 |
|
fcd704
|
246 |
Backwards Incompatibilities |
CM |
247 |
--------------------------- |
|
248 |
|
|
249 |
- The Pyramid router no longer adds the values ``bfg.routes.route`` or |
|
250 |
``bfg.routes.matchdict`` to the request's WSGI environment dictionary. |
|
251 |
These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven |
|
252 |
minor releases ago). If your code depended on these values, use |
1affe4
|
253 |
``request.matched_route`` and ``request.matchdict`` instead. |
fcd704
|
254 |
|
CM |
255 |
- It is no longer possible to pass an environ dictionary directly to |
|
256 |
``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka |
|
257 |
``ModelGraphTraverser.__call__``). Instead, you must pass a request |
|
258 |
object. Passing an environment instead of a request has generated a |
|
259 |
deprecation warning since Pyramid 1.1. |
|
260 |
|
|
261 |
- Pyramid will no longer work properly if you use the |
|
262 |
``webob.request.LegacyRequest`` as a request factory. Instances of the |
|
263 |
LegacyRequest class have a ``request.path_info`` which return a string. |
|
264 |
This Pyramid release assumes that ``request.path_info`` will |
|
265 |
unconditionally be Unicode. |
|
266 |
|
|
267 |
- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` |
|
268 |
named ``get_renderer``, ``get_template``, ``render_template``, and |
|
269 |
``render_template_to_response`` have been removed. These have issued a |
|
270 |
deprecation warning upon import since Pyramid 1.0. Use |
|
271 |
:func:`pyramid.renderers.get_renderer`, |
|
272 |
``pyramid.renderers.get_renderer().implementation()``, |
|
273 |
:func:`pyramid.renderers.render` or |
|
274 |
:func:`pyramid.renderers.render_to_response` respectively instead of these |
|
275 |
functions. |
|
276 |
|
|
277 |
- The ``pyramid.configuration`` module was removed. It had been deprecated |
|
278 |
since Pyramid 1.0 and printed a deprecation warning upon its use. Use |
|
279 |
:mod:`pyramid.config` instead. |
|
280 |
|
|
281 |
- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been |
|
282 |
deprecated since Pyramid 1.1 and issued a warning on import. If your code |
|
283 |
depended on this, adjust your code to import |
|
284 |
:class:`pyramid.scaffolds.PyramidTemplate` instead. |
|
285 |
|
|
286 |
- The ``pyramid.settings.get_settings()`` API was removed. It had been |
|
287 |
printing a deprecation warning since Pyramid 1.0. If your code depended on |
|
288 |
this API, use ``pyramid.threadlocal.get_current_registry().settings`` |
|
289 |
instead or use the ``settings`` attribute of the registry available from |
|
290 |
the request (``request.registry.settings``). |
|
291 |
|
|
292 |
- These APIs from the ``pyramid.testing`` module were removed. They have |
|
293 |
been printing deprecation warnings since Pyramid 1.0: |
|
294 |
|
|
295 |
* ``registerDummySecurityPolicy``, use |
|
296 |
:meth:`pyramid.config.Configurator.testing_securitypolicy` instead. |
|
297 |
|
|
298 |
* ``registerResources`` (aka ``registerModels``), use |
|
299 |
:meth:`pyramid.config.Configurator.testing_resources` instead. |
|
300 |
|
|
301 |
* ``registerEventListener``, use |
|
302 |
:meth:`pyramid.config.Configurator.testing_add_subscriber` instead. |
|
303 |
|
1affe4
|
304 |
* ``registerTemplateRenderer`` (aka ``registerDummyRenderer``), use |
50218d
|
305 |
:meth:`pyramid.config.Configurator.testing_add_renderer` instead. |
fcd704
|
306 |
|
CM |
307 |
* ``registerView``, use :meth:`pyramid.config.Configurator.add_view` instead. |
|
308 |
|
|
309 |
* ``registerUtility``, use |
|
310 |
:meth:`pyramid.config.Configurator.registry.registerUtility` instead. |
|
311 |
|
|
312 |
* ``registerAdapter``, use |
|
313 |
:meth:`pyramid.config.Configurator.registry.registerAdapter` instead. |
|
314 |
|
|
315 |
* ``registerSubscriber``, use |
|
316 |
:meth:`pyramid.config.Configurator.add_subscriber` instead. |
|
317 |
|
|
318 |
* ``registerRoute``, use |
|
319 |
:meth:`pyramid.config.Configurator.add_route` instead. |
|
320 |
|
|
321 |
* ``registerSettings``, use |
|
322 |
:meth:`pyramid.config.Configurator.add_settings` instead. |
|
323 |
|
64452e
|
324 |
- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object |
CM |
325 |
returned by a view was invoked before any finished callbacks were executed. |
|
326 |
As of this release, the ``__call__`` method of a Response object is invoked |
|
327 |
*after* finished callbacks are executed. This is in support of the |
|
328 |
:meth:`pyramid.request.Request.invoke_subrequest` feature. |
|
329 |
|
fcd704
|
330 |
Deprecations |
CM |
331 |
------------ |
|
332 |
|
|
333 |
- The :meth:`pyramid.config.Configurator.set_request_property` directive has |
|
334 |
been documentation-deprecated. The method remains usable but the more |
|
335 |
featureful :meth:`pyramid.config.Configurator.add_request_method` should be |
|
336 |
used in its place (it has all of the same capabilities but can also extend |
|
337 |
the request object with methods). |
|
338 |
|
2063ed
|
339 |
- :class:`pyramid.authentication.AuthTktAuthenticationPolicy` will emit a |
CM |
340 |
deprecation warning if an application is using the policy without explicitly |
|
341 |
passing a ``hashalg`` argument. This is because the default is "md5" which is |
|
342 |
considered theoretically subject to collision attacks. If you really want |
|
343 |
"md5" then you must specify it explicitly to get rid of the warning. |
|
344 |
|
fcd704
|
345 |
Documentation Enhancements |
CM |
346 |
-------------------------- |
|
347 |
|
|
348 |
- Added an :ref:`upgrading_chapter` chapter to the narrative documentation. |
|
349 |
It describes how to cope with deprecations and removals of Pyramid APIs and |
|
350 |
how to show Pyramid-generated deprecation warnings while running tests and |
|
351 |
while running a server. |
|
352 |
|
37d2c2
|
353 |
- Added a :ref:`subrequest_chapter` chapter to the narrative documentation. |
CM |
354 |
|
2063ed
|
355 |
- All of the tutorials that use |
CM |
356 |
:class:`pyramid.authentication.AuthTktAuthenticationPolicy` now explicitly |
|
357 |
pass ``sha512`` as a ``hashalg`` argument. |
|
358 |
|
fcd704
|
359 |
- Many cleanups and improvements to narrative and API docs. |
CM |
360 |
|
|
361 |
Dependency Changes |
|
362 |
------------------ |
|
363 |
|
|
364 |
- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on |
|
365 |
1.2dev+). This is to ensure that we obtain a version of WebOb that returns |
|
366 |
``request.path_info`` as text. |
|
367 |
|