commit | author | age
|
41aeac
|
1 |
What's New in Pyramid 1.0 |
a9688f
|
2 |
========================= |
CM |
3 |
|
|
4 |
This article explains the new features in Pyramid version 1.0 as compared to |
|
5 |
its predecessor, :mod:`repoze.bfg` 1.3. It also documents backwards |
|
6 |
incompatibilities between the two versions and deprecations added to Pyramid |
|
7 |
1.0, 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.0 are: |
|
14 |
|
|
15 |
- New name and branding association with the Pylons Project. |
|
16 |
|
c88d44
|
17 |
- BFG conversion script |
CM |
18 |
|
758464
|
19 |
- Scaffold improvements |
a9688f
|
20 |
|
CM |
21 |
- Terminology changes |
|
22 |
|
|
23 |
- Better platform compatibility and support |
|
24 |
|
|
25 |
- Direct built-in support for the Mako templating language. |
|
26 |
|
|
27 |
- Built-in support for sessions. |
|
28 |
|
|
29 |
- Updated URL dispatch features |
|
30 |
|
|
31 |
- Better imperative extensibility |
|
32 |
|
|
33 |
- ZCML externalized |
|
34 |
|
|
35 |
- Better support for global template variables during rendering |
|
36 |
|
|
37 |
- View mappers |
|
38 |
|
|
39 |
- Testing system improvements |
|
40 |
|
|
41 |
- Authentication support improvements |
|
42 |
|
|
43 |
- Documentation improvements |
|
44 |
|
|
45 |
New Name and Branding |
|
46 |
~~~~~~~~~~~~~~~~~~~~~ |
|
47 |
|
c88d44
|
48 |
The name of ``repoze.bfg`` has been changed to Pyramid. The project is also |
CM |
49 |
now a subproject of a new entity, "The Pylons Project". The Pylons Project |
a9688f
|
50 |
is the project name for a collection of web-framework-related technologies. |
CM |
51 |
Pyramid was the first package in the Pylons Project. Other packages to the |
|
52 |
collection have been added over time, such as support packages useful for |
|
53 |
Pylons 1 users as well as ex-Zope users. Pyramid is the successor to both |
|
54 |
:mod:`repoze.bfg` and :term:`Pylons` version 1. |
|
55 |
|
|
56 |
The Pyramid codebase is derived almost entirely from :mod:`repoze.bfg` |
|
57 |
with some changes made for the sake of Pylons 1 compatibility. |
|
58 |
|
|
59 |
Pyramid is technically backwards incompatible with :mod:`repoze.bfg`, as it |
|
60 |
has a new package name, so older imports from the ``repoze.bfg`` module will |
|
61 |
fail if you do nothing to your existing :mod:`repoze.bfg` application. |
|
62 |
However, you won't have to do much to use your existing BFG applications on |
|
63 |
Pyramid. There's automation which will change most of your import statements |
|
64 |
and ZCML declarations. See |
39e88a
|
65 |
http://docs.pylonsproject.org/projects/pyramid/current/tutorials/bfg/index.html |
CM |
66 |
for upgrade instructions. |
a9688f
|
67 |
|
CM |
68 |
Pylons 1 users will need to do more work to use Pyramid, as Pyramid shares no |
|
69 |
"DNA" with Pylons. It is hoped that over time documentation and upgrade code |
|
70 |
will be developed to help Pylons 1 users transition to Pyramid more easily. |
|
71 |
|
|
72 |
:mod:`repoze.bfg` version 1.3 will be its last major release. Minor updates |
|
73 |
will be made for critical bug fixes. Pylons version 1 will continue to see |
|
74 |
maintenance releases, as well. |
|
75 |
|
|
76 |
The Repoze project will continue to exist. Repoze will be able to regain its |
|
77 |
original focus: bringing Zope technologies to WSGI. The popularity of |
|
78 |
:mod:`repoze.bfg` as its own web framework hindered this goal. |
|
79 |
|
|
80 |
We hope that people are attracted at first by the spirit of cooperation |
|
81 |
demonstrated by the Pylons Project and the merging of development |
|
82 |
communities. It takes humility to sacrifice a little sovereignty and work |
|
83 |
together. The opposite, forking or splintering of projects, is much more |
|
84 |
common in the open source world. We feel there is a limited amount of oxygen |
|
85 |
in the space of "top-tier" Python web frameworks and we don’t do the Python |
|
86 |
community a service by over-crowding. By merging the :mod:`repoze.bfg` and |
|
87 |
the philosophically-similar Pylons communities, both gain an expanded |
|
88 |
audience and a stronger chance of future success. |
|
89 |
|
c88d44
|
90 |
BFG Conversion Script |
CM |
91 |
~~~~~~~~~~~~~~~~~~~~~ |
|
92 |
|
|
93 |
The ``bfg2pyramid`` conversion script performs a mostly automated conversion |
|
94 |
of an existing :mod:`repoze.bfg` application to Pyramid. The process is |
e75754
|
95 |
described in "Converting a BFG Application to Pyramid". |
c88d44
|
96 |
|
758464
|
97 |
Scaffold Improvements |
a9688f
|
98 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
CM |
99 |
|
758464
|
100 |
- The scaffolds now have much nicer CSS and graphics. |
c88d44
|
101 |
|
391402
|
102 |
- The ``development.ini``, generated by all scaffolds, is now configured to |
CM |
103 |
use the WebError interactive exception debugger by default. |
c88d44
|
104 |
|
758464
|
105 |
- All scaffolds have been normalized: each now uses the name ``main`` |
c88d44
|
106 |
to represent the function that returns a WSGI application, and each now has |
CM |
107 |
roughly the same shape of development.ini style. |
a9688f
|
108 |
|
758464
|
109 |
- All preexisting scaffolds now use "imperative" configuration |
c88d44
|
110 |
(``starter``, ``routesalchemy``, ``alchemy``, ``zodb``) instead of ZCML |
CM |
111 |
configuration. |
a9688f
|
112 |
|
8092b6
|
113 |
- The ``pyramid_zodb``, ``routesalchemy`` and ``pyramid_alchemy`` |
758464
|
114 |
scaffolds now use a default "commit veto" hook when configuring the |
a9688f
|
115 |
``repoze.tm2`` transaction manager in ``development.ini``. This prevents a |
CM |
116 |
transaction from being committed when the response status code is within |
2033ee
|
117 |
the 400 or 500 ranges. |
SP |
118 |
|
|
119 |
.. seealso:: |
|
120 |
|
|
121 |
See also http://docs.repoze.org/tm2/#using-a-commit-veto. |
a9688f
|
122 |
|
CM |
123 |
Terminology Changes |
|
124 |
~~~~~~~~~~~~~~~~~~~ |
|
125 |
|
|
126 |
- The Pyramid concept previously known as "model" is now known as "resource". |
c88d44
|
127 |
As a result, the following API renames have been made. Backwards |
CM |
128 |
compatibility shims for the old names have been left in place in all cases:: |
a9688f
|
129 |
|
CM |
130 |
pyramid.url.model_url -> |
|
131 |
pyramid.url.resource_url |
|
132 |
|
|
133 |
pyramid.traversal.find_model -> |
|
134 |
pyramid.url.find_resource |
|
135 |
|
|
136 |
pyramid.traversal.model_path -> |
|
137 |
pyramid.traversal.resource_path |
|
138 |
|
|
139 |
pyramid.traversal.model_path_tuple -> |
|
140 |
pyramid.traversal.resource_path_tuple |
|
141 |
|
|
142 |
pyramid.traversal.ModelGraphTraverser -> |
|
143 |
pyramid.traversal.ResourceTreeTraverser |
|
144 |
|
|
145 |
pyramid.config.Configurator.testing_models -> |
|
146 |
pyramid.config.Configurator.testing_resources |
|
147 |
|
|
148 |
pyramid.testing.registerModels -> |
|
149 |
pyramid.testing.registerResources |
|
150 |
|
|
151 |
pyramid.testing.DummyModel -> |
|
152 |
pyramid.testing.DummyResource |
|
153 |
|
c88d44
|
154 |
- All documentation which previously referred to "model" now refers to |
CM |
155 |
"resource". |
a9688f
|
156 |
|
758464
|
157 |
- The ``starter`` scaffold now has a ``resources.py`` module instead |
c88d44
|
158 |
of a ``models.py`` module. |
a9688f
|
159 |
|
c88d44
|
160 |
- Positional argument names of various APIs have been changed from |
CM |
161 |
``model`` to ``resource``. |
a9688f
|
162 |
|
CM |
163 |
- The Pyramid concept previously known as "resource" is now known as "asset". |
c88d44
|
164 |
As a result, the following API changes were made. Backwards compatibility |
CM |
165 |
shims have been left in place as necessary:: |
a9688f
|
166 |
|
CM |
167 |
pyramid.config.Configurator.absolute_resource_spec -> |
|
168 |
pyramid.config.Configurator.absolute_asset_spec |
|
169 |
|
|
170 |
pyramid.config.Configurator.override_resource -> |
|
171 |
pyramid.config.Configurator.override_asset |
|
172 |
|
|
173 |
|
c88d44
|
174 |
- The (non-API) module previously known as ``pyramid.resource`` is now |
CM |
175 |
known as ``pyramid.asset``. |
a9688f
|
176 |
|
c88d44
|
177 |
- All docs that previously referred to "resource specification" now refer |
CM |
178 |
to "asset specification". |
|
179 |
|
|
180 |
- The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or |
|
181 |
``reload_resources`` (config file) is now known, respectively, as |
|
182 |
``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. |
758464
|
183 |
|
a9688f
|
184 |
Better Platform Compatibility and Support |
CM |
185 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
186 |
|
c88d44
|
187 |
We've made Pyramid's test suite pass on both Jython and PyPy. However, |
CM |
188 |
Chameleon doesn't work on either, so you'll need to use Mako or Jinja2 |
|
189 |
templates on these platforms. |
a9688f
|
190 |
|
CM |
191 |
Sessions |
|
192 |
~~~~~~~~ |
|
193 |
|
c88d44
|
194 |
Pyramid now has built-in sessioning support, documented in |
CM |
195 |
:ref:`sessions_chapter`. The sessioning implementation is pluggable. It |
|
196 |
also provides flash messaging and cross-site-scripting prevention features. |
a9688f
|
197 |
|
c88d44
|
198 |
Using ``request.session`` now returns a (dictionary-like) session object if |
CM |
199 |
a :term:`session factory` has been configured. |
a9688f
|
200 |
|
c88d44
|
201 |
A new argument to the Configurator constructor exists: ``session_factory`` |
CM |
202 |
and a new method on the configurator exists: |
|
203 |
:meth:`pyramid.config.Configurator.set_session_factory`. |
a9688f
|
204 |
|
CM |
205 |
Mako |
|
206 |
~~~~ |
|
207 |
|
c88d44
|
208 |
In addition to Chameleon templating, Pyramid now also provides built-in |
70784a
|
209 |
support for :term:`Mako` templating. See |
MM |
210 |
:ref:`available_template_system_bindings` for more information. |
a9688f
|
211 |
|
CM |
212 |
URL Dispatch |
|
213 |
~~~~~~~~~~~~ |
|
214 |
|
|
215 |
- URL Dispatch now allows for replacement markers to be located anywhere |
|
216 |
in the pattern, instead of immediately following a ``/``. |
|
217 |
|
|
218 |
- URL Dispatch now uses the form ``{marker}`` to denote a replace marker in |
|
219 |
the route pattern instead of ``:marker``. The old colon-style marker syntax |
|
220 |
is still accepted for backwards compatibility. The new format allows a |
|
221 |
regular expression for that marker location to be used instead of the |
|
222 |
default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the |
|
223 |
marker to be digits. |
|
224 |
|
c88d44
|
225 |
- Addded a new API :func:`pyramid.url.current_route_url`, which computes a |
CM |
226 |
URL based on the "current" route (if any) and its matchdict values. |
a9688f
|
227 |
|
c88d44
|
228 |
- Added a ``paster proute`` command which displays a summary of the routing |
CM |
229 |
table. See the narrative documentation section entitled |
|
230 |
:ref:`displaying_application_routes`. |
a9688f
|
231 |
|
c88d44
|
232 |
- Added ``debug_routematch`` configuration setting (settable in your ``.ini`` |
CM |
233 |
file) that logs matched routes including the matchdict and predicates. |
a9688f
|
234 |
|
c88d44
|
235 |
- Add a :func:`pyramid.url.route_path` API, allowing folks to generate |
CM |
236 |
relative URLs. Calling ``route_path`` is the same as calling |
|
237 |
:func:`pyramid.url.route_url` with the argument ``_app_url`` equal to the |
|
238 |
empty string. |
a9688f
|
239 |
|
c88d44
|
240 |
- Add a :meth:`pyramid.request.Request.route_path` API. This is a |
CM |
241 |
convenience method of the request which calls |
|
242 |
:func:`pyramid.url.route_url`. |
a9688f
|
243 |
|
CM |
244 |
- Added class vars ``matchdict`` and ``matched_route`` to |
c88d44
|
245 |
:class:`pyramid.request.Request`. Each is set to ``None`` when a route |
CM |
246 |
isn't matched during a request. |
a9688f
|
247 |
|
CM |
248 |
ZCML Externalized |
|
249 |
~~~~~~~~~~~~~~~~~ |
|
250 |
|
|
251 |
- The ``load_zcml`` method of a Configurator has been removed from the |
c88d44
|
252 |
Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` |
a9688f
|
253 |
package, which can be downloaded from PyPI. Documentation for the package |
CM |
254 |
should be available via |
8087fb
|
255 |
http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, which describes how to |
c88d44
|
256 |
add a configuration statement to your ``main`` block to reobtain this |
a9688f
|
257 |
method. You will also need to add an ``install_requires`` dependency upon |
c88d44
|
258 |
the ``pyramid_zcml`` distribution to your ``setup.py`` file. |
a9688f
|
259 |
|
CM |
260 |
- The "Declarative Configuration" narrative chapter has been removed (it was |
|
261 |
moved to the ``pyramid_zcml`` package). |
|
262 |
|
|
263 |
- Most references to ZCML in narrative chapters have been removed or |
|
264 |
redirected to ``pyramid_zcml`` locations. |
|
265 |
|
758464
|
266 |
- The ``starter_zcml`` paster scaffold has been moved to the ``pyramid_zcml`` |
a9688f
|
267 |
package. |
CM |
268 |
|
|
269 |
Imperative Two-Phase Configuration |
|
270 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
271 |
|
c88d44
|
272 |
To support application extensibility, the :app:`Pyramid` |
CM |
273 |
:term:`Configurator`, by default, now detects configuration conflicts and |
|
274 |
allows you to include configuration imperatively from other packages or |
|
275 |
modules. It also, by default, performs configuration in two separate phases. |
|
276 |
This allows you to ignore relative configuration statement ordering in some |
|
277 |
circumstances. See :ref:`advconfig_narr` for more information. |
a9688f
|
278 |
|
c88d44
|
279 |
The :meth:`pyramid.config.Configurator.add_directive` allows framework |
CM |
280 |
extenders to add methods to the configurator, which allows extenders to avoid |
|
281 |
subclassing a Configurator just to add methods. See :ref:`add_directive` for |
|
282 |
more info. |
a9688f
|
283 |
|
c88d44
|
284 |
Surrounding application configuration with ``config.begin()`` and |
758464
|
285 |
``config.end()`` is no longer necessary. All scaffolds have been |
c88d44
|
286 |
changed to no longer call these functions. |
a9688f
|
287 |
|
CM |
288 |
Better Support for Global Template Variables During Rendering |
|
289 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
290 |
|
c88d44
|
291 |
A new event type named :class:`pyramid.interfaces.IBeforeRender` is now sent |
CM |
292 |
as an event before a renderer is invoked. Applications may now subscribe to |
|
293 |
the ``IBeforeRender`` event type in order to introspect the and modify the |
|
294 |
set of renderer globals before they are passed to a renderer. The event |
|
295 |
object iself has a dictionary-like interface that can be used for this |
|
296 |
purpose. For example:: |
a9688f
|
297 |
|
CM |
298 |
from repoze.events import subscriber |
|
299 |
from pyramid.interfaces import IRendererGlobalsEvent |
|
300 |
|
|
301 |
@subscriber(IRendererGlobalsEvent) |
|
302 |
def add_global(event): |
|
303 |
event['mykey'] = 'foo' |
|
304 |
|
|
305 |
View Mappers |
|
306 |
~~~~~~~~~~~~ |
|
307 |
|
c88d44
|
308 |
A "view mapper" subsystem has been extracted, which allows framework |
CM |
309 |
extenders to control how view callables are constructed and called. This |
|
310 |
feature is not useful for "civilians", only for extension writers. See |
|
311 |
:ref:`using_a_view_mapper` for more information. |
a9688f
|
312 |
|
CM |
313 |
Testing Support Improvements |
|
314 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
315 |
|
6482f7
|
316 |
The :func:`pyramid.testing.setUp` and :func:`pyramid.testing.tearDown` APIs |
c88d44
|
317 |
have been undeprecated. They are now the canonical setup and teardown APIs |
CM |
318 |
for test configuration, replacing "direct" creation of a Configurator. This |
|
319 |
is a change designed to provide a facade that will protect against any future |
|
320 |
Configurator deprecations. |
a9688f
|
321 |
|
CM |
322 |
Authentication Support Improvements |
|
323 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
324 |
|
c88d44
|
325 |
- The :class:`pyramid.interfaces.IAuthenticationPolicy` interface now |
CM |
326 |
specifies an ``unauthenticated_userid`` method. This method supports an |
|
327 |
important optimization required by people who are using persistent storages |
|
328 |
which do not support object caching and whom want to create a "user object" |
|
329 |
as a request attribute. |
a9688f
|
330 |
|
c88d44
|
331 |
- A new API has been added to the :mod:`pyramid.security` module named |
a9688f
|
332 |
``unauthenticated_userid``. This API function calls the |
CM |
333 |
``unauthenticated_userid`` method of the effective security policy. |
|
334 |
|
c88d44
|
335 |
- The class :class:`pyramid.authentication.AuthTktCookieHelper` is now an |
CM |
336 |
API. This class can be used by third-party authentication policy |
|
337 |
developers to help in the mechanics of authentication cookie-setting. |
a9688f
|
338 |
|
c88d44
|
339 |
- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now accepts |
CM |
340 |
a ``tokens`` parameter via :func:`pyramid.security.remember`. The value |
|
341 |
must be a sequence of strings. Tokens are placed into the auth_tkt |
|
342 |
"tokens" field and returned in the auth_tkt cookie. |
a9688f
|
343 |
|
c88d44
|
344 |
- Added a ``wild_domain`` argument to |
CM |
345 |
:class:`pyramid.authentication.AuthTktAuthenticationPolicy`, which defaults |
ef2ce5
|
346 |
to ``True``. If it is set to ``False``, the feature of the policy which |
CM |
347 |
sets a cookie with a wilcard domain will be turned off. |
|
348 |
|
a9688f
|
349 |
Documentation Improvements |
CM |
350 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
351 |
|
|
352 |
- Casey Duncan, a good friend, and an excellent technical writer has given us |
|
353 |
the gift of professionally editing the entire Pyramid documentation set. |
|
354 |
Any faults in the documentation are the development team's, and all |
|
355 |
improvements are his. |
|
356 |
|
|
357 |
- The "Resource Location and View Lookup" chapter has been replaced with a |
|
358 |
variant of Rob Miller's "Much Ado About Traversal" (originally published at |
|
359 |
http://blog.nonsequitarian.org/2010/much-ado-about-traversal/). |
|
360 |
|
|
361 |
- Many users have contributed documentation fixes and improvements including |
|
362 |
Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, |
|
363 |
Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, |
|
364 |
Joachim Krebs, Xavier Spriet, Reed O'Brien, William Chambers, Charlie |
|
365 |
Choiniere, and Jamaludin Ahmad. |
|
366 |
|
|
367 |
Minor Feature Additions |
|
368 |
----------------------- |
|
369 |
|
c88d44
|
370 |
- The ``settings`` dictionary passed to the Configurator is now available as |
CM |
371 |
``config.registry.settings`` in configuration code and |
|
372 |
``request.registry.settings`` in view code). |
a9688f
|
373 |
|
c88d44
|
374 |
- :meth:`pyramid.config.Configurator.add_view` now accepts a ``decorator`` |
CM |
375 |
keyword argument, a callable which will decorate the view callable before |
|
376 |
it is added to the registry. |
a9688f
|
377 |
|
CM |
378 |
- Allow static renderer provided during view registration to be overridden at |
|
379 |
request time via a request attribute named ``override_renderer``, which |
|
380 |
should be the name of a previously registered renderer. Useful to provide |
|
381 |
"omnipresent" RPC using existing rendered views. |
|
382 |
|
|
383 |
- If a resource implements a ``__resource_url__`` method, it will be called |
c88d44
|
384 |
as the result of invoking the :func:`pyramid.url.resource_url` function to |
CM |
385 |
generate a URL, overriding the default logic. See |
|
386 |
:ref:`generating_the_url_of_a_resource` for more information. |
a9688f
|
387 |
|
CM |
388 |
- The name ``registry`` is now available in a ``pshell`` environment by |
|
389 |
default. It is the application registry object. |
|
390 |
|
c88d44
|
391 |
- Added support for json on Google App Engine by catching |
CM |
392 |
:exc:`NotImplementedError` and importing ``simplejson`` from |
|
393 |
``django.utils``. |
a9688f
|
394 |
|
c88d44
|
395 |
- Added the :mod:`pyramid.httpexceptions` module, which is a facade for the |
a9688f
|
396 |
``webob.exc`` module. |
CM |
397 |
|
c88d44
|
398 |
- New class: :class:`pyramid.response.Response`. This is a pure facade for |
a9688f
|
399 |
``webob.Response`` (old code need not change to use this facade, it's |
CM |
400 |
existence is mostly for vanity and documentation-generation purposes). |
|
401 |
|
|
402 |
- The request now has a new attribute: ``tmpl_context`` for benefit of |
|
403 |
Pylons users. |
|
404 |
|
c88d44
|
405 |
- New API methods for :class:`pyramid.request.Request`: ``model_url``, |
a9688f
|
406 |
``route_url``, and ``static_url``. These are simple passthroughs for their |
c88d44
|
407 |
respective functions in :mod:`pyramid.url`. |
a9688f
|
408 |
|
CM |
409 |
Backwards Incompatibilities |
|
410 |
--------------------------- |
|
411 |
|
c88d44
|
412 |
- When a :class:`pyramid.exceptions.Forbidden` error is raised, its status |
CM |
413 |
code now ``403 Forbidden``. It was previously ``401 Unauthorized``, for |
|
414 |
backwards compatibility purposes with :mod:`repoze.bfg`. This change will |
|
415 |
cause problems for users of Pyramid with :mod:`repoze.who`, which |
|
416 |
intercepts ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to |
|
417 |
pass through. Those deployments will need to configure :mod:`repoze.who` |
d3a028
|
418 |
to also react to ``403 Forbidden``. To do so, use a repoze.who |
CM |
419 |
``challenge_decider`` that looks like this:: |
|
420 |
|
|
421 |
import zope.interface |
|
422 |
from repoze.who.interfaces import IChallengeDecider |
|
423 |
|
|
424 |
def challenge_decider(environ, status, headers): |
|
425 |
return status.startswith('403') or status.startswith('401') |
|
426 |
zope.interface.directlyProvides(challenge_decider, IChallengeDecider) |
a9688f
|
427 |
|
c88d44
|
428 |
- The ``paster bfgshell`` command is now known as ``paster pshell``. |
a9688f
|
429 |
|
c88d44
|
430 |
- There is no longer an ``IDebugLogger`` object registered as a named utility |
a9688f
|
431 |
with the name ``repoze.bfg.debug``. |
CM |
432 |
|
c88d44
|
433 |
- These deprecated APIs have been removed: |
CM |
434 |
``pyramid.testing.registerViewPermission``, |
|
435 |
``pyramid.testing.registerRoutesMapper``, ``pyramid.request.get_request``, |
|
436 |
``pyramid.security.Unauthorized``, |
|
437 |
``pyramid.view.view_execution_permitted``, ``pyramid.view.NotFound`` |
a9688f
|
438 |
|
CM |
439 |
- The Venusian "category" for all built-in Venusian decorators |
|
440 |
(e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now |
|
441 |
``pyramid`` instead of ``bfg``. |
|
442 |
|
c88d44
|
443 |
- The ``pyramid.renderers.rendered_response`` function removed; use |
CM |
444 |
:func:`pyramid.renderers.render_to_response` instead. |
a9688f
|
445 |
|
CM |
446 |
- Renderer factories now accept a *renderer info object* rather than an |
|
447 |
absolute resource specification or an absolute path. The object has the |
|
448 |
following attributes: ``name`` (the ``renderer=`` value), ``package`` (the |
|
449 |
'current package' when the renderer configuration statement was found), |
|
450 |
``type``: the renderer type, ``registry``: the current registry, and |
c88d44
|
451 |
``settings``: the deployment settings dictionary. Third-party |
CM |
452 |
``repoze.bfg`` renderer implementations that must be ported to Pyramid will |
|
453 |
need to account for this. This change was made primarily to support more |
|
454 |
flexible Mako template rendering. |
a9688f
|
455 |
|
CM |
456 |
- The presence of the key ``repoze.bfg.message`` in the WSGI environment when |
|
457 |
an exception occurs is now deprecated. Instead, code which relies on this |
|
458 |
environ value should use the ``exception`` attribute of the request |
|
459 |
(e.g. ``request.exception[0]``) to retrieve the message. |
|
460 |
|
|
461 |
- The values ``bfg_localizer`` and ``bfg_locale_name`` kept on the request |
|
462 |
during internationalization for caching purposes were never APIs. These |
|
463 |
however have changed to ``localizer`` and ``locale_name``, respectively. |
|
464 |
|
|
465 |
- The default ``cookie_name`` value of the |
c88d44
|
466 |
:class:`pyramid.authentication.AuthTktAuthenticationPolicy` now defaults to |
CM |
467 |
``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). |
a9688f
|
468 |
|
c88d44
|
469 |
- The :func:`pyramid.testing.zcml_configure` API has been removed. It had |
CM |
470 |
been advertised as removed since :mod:`repoze.bfg` 1.2a1, but hadn't |
|
471 |
actually been. |
a9688f
|
472 |
|
CM |
473 |
- All environment variables which used to be prefixed with ``BFG_`` are now |
|
474 |
prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now |
|
475 |
``PYRAMID_DEBUG_NOTFOUND``) |
|
476 |
|
c88d44
|
477 |
- Since the :class:`pyramid.interfaces.IAuthenticationPolicy` interface now |
a9688f
|
478 |
specifies that a policy implementation must implement an |
CM |
479 |
``unauthenticated_userid`` method, all third-party custom authentication |
|
480 |
policies now must implement this method. It, however, will only be called |
c88d44
|
481 |
when the global function named |
CM |
482 |
:func:`pyramid.security.unauthenticated_userid` is invoked, so if you're |
|
483 |
not invoking that, you will not notice any issues. |
a9688f
|
484 |
|
CM |
485 |
- The ``configure_zcml`` setting within the deployment settings (within |
|
486 |
``**settings`` passed to a Pyramid ``main`` function) has ceased to have any |
|
487 |
meaning. |
|
488 |
|
c88d44
|
489 |
- The ``make_app`` function has been removed from the :mod:`pyramid.router` |
CM |
490 |
module. It continues life within the ``pyramid_zcml`` package. This |
|
491 |
leaves the :mod:`pyramid.router` module without any API functions. |
|
492 |
|
a9688f
|
493 |
Deprecations and Behavior Differences |
CM |
494 |
------------------------------------- |
|
495 |
|
c88d44
|
496 |
- :class:`pyramid.configuration.Configurator` is now deprecated. Use |
CM |
497 |
:class:`pyramid.config.Configurator`, passing its constructor |
|
498 |
``autocommit=True`` instead. The |
|
499 |
:class:`pyramid.configuration.Configurator` alias will live for a long |
|
500 |
time, as every application uses it, but its import now issues a deprecation |
|
501 |
warning. The :class:`pyramid.config.Configurator` class has the same API |
|
502 |
as the :class:`pyramid.configuration.Configurator` class, which it means to |
|
503 |
replace, except by default it is a *non-autocommitting* configurator. The |
|
504 |
now-deprecated ``pyramid.configuration.Configurator`` will autocommit every |
|
505 |
time a configuration method is called. The :mod:`pyramid.configuration` |
|
506 |
module remains, but it is deprecated. Use :mod:`pyramid.config` instead. |
|
507 |
|
|
508 |
- The :func:`pyramid.settings.get_settings` API is now deprecated. Use |
a9688f
|
509 |
``pyramid.threadlocals.get_current_registry().settings`` instead or use the |
CM |
510 |
``settings`` attribute of the registry available from the request |
|
511 |
(``request.registry.settings``). |
|
512 |
|
c88d44
|
513 |
- The decorator previously known as ``pyramid.view.bfg_view`` is now known |
758464
|
514 |
most formally as :class:`pyramid.view.view_config` in docs and scaffolds. |
a9688f
|
515 |
|
CM |
516 |
- Obtaining the ``settings`` object via |
|
517 |
``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, |
|
518 |
obtain the ``settings`` object via the ``registry.settings`` attribute. A |
|
519 |
backwards compatibility shim was added to the registry object to register |
|
520 |
the settings object as an ISettings utility when ``setattr(registry, |
|
521 |
'settings', foo)`` is called, but it will be removed in a later release. |
|
522 |
|
c88d44
|
523 |
- Obtaining the ``settings`` object via :func:`pyramid.settings.get_settings` |
CM |
524 |
is now deprecated. Obtain it instead as the ``settings`` attribute of the |
|
525 |
registry now (obtain the registry via |
|
526 |
:func:`pyramid.threadlocal.get_registry` or as ``request.registry``). |
a9688f
|
527 |
|
CM |
528 |
Dependency Changes |
|
529 |
------------------ |
|
530 |
|
|
531 |
- Depend on Venusian >= 0.5 (for scanning conflict exception decoration). |
|
532 |
|
|
533 |
Documentation Enhancements |
|
534 |
-------------------------- |
|
535 |
|
c88d44
|
536 |
- Added a :mod:`pyramid.httpexceptions` API documentation chapter. |
a9688f
|
537 |
|
c88d44
|
538 |
- Added a :mod:`pyramid.session` API documentation chapter. |
a9688f
|
539 |
|
c88d44
|
540 |
- Added an API chapter for the :mod:`pyramid.response` module. |
a9688f
|
541 |
|
c88d44
|
542 |
- Added a :ref:`sessions_chapter` narrative documentation chapter. |
a9688f
|
543 |
|
CM |
544 |
- All documentation which previously referred to ``webob.Response`` now uses |
c88d44
|
545 |
:class:`pyramid.response.Response` instead. |
a9688f
|
546 |
|
CM |
547 |
- The documentation has been overhauled to use imperative configuration, |
c88d44
|
548 |
moving declarative configuration (ZCML) explanations to an external |
CM |
549 |
package, :term:`pyramid_zcml`. |
a9688f
|
550 |
|
CM |
551 |
- Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now |
|
552 |
have a SessionFactory abstraction which competes with it, and maintaining |
|
553 |
documentation on both ways to do it is a distraction. |
|
554 |
|
|
555 |
- Added an example of ``WebTest`` functional testing to the testing narrative |
c88d44
|
556 |
chapter at :ref:`functional_tests`. |
a9688f
|
557 |
|
c88d44
|
558 |
- Extended the Resources chapter with examples of calls to resource-related |
CM |
559 |
APIs. |
a9688f
|
560 |
|
CM |
561 |
- Add "Pyramid Provides More Than One Way to Do It" to Design Defense |
|
562 |
documentation. |
|
563 |
|
|
564 |
- The (weak) "Converting a CMF Application to Pyramid" tutorial has been |
|
565 |
removed from the tutorials section. It was moved to the |
a2b9b6
|
566 |
``pyramid_tutorials`` Github repository at |
CM |
567 |
http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/. |
|
568 |
|
|
569 |
- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" |
|
570 |
tutorials out of core documentation and into the Pyramid Tutorials site |
|
571 |
(http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/). |
|
572 |
|
|
573 |
- Removed API documentation for deprecated ``pyramid.testing`` APIs named |
|
574 |
``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, |
|
575 |
``registerEventListener``, ``registerTemplateRenderer``, |
|
576 |
``registerDummyRenderer``, ``registerView``, ``registerUtility``, |
|
577 |
``registerAdapter``, ``registerSubscriber``, ``registerRoute``, and |
|
578 |
``registerSettings``. |
a9688f
|
579 |
|