commit | author | age
|
1464c1
|
1 |
What's New in Pyramid 1.7 |
814bdb
|
2 |
========================= |
MM |
3 |
|
1464c1
|
4 |
This article explains the new features in :app:`Pyramid` version 1.7 as |
MM |
5 |
compared to its predecessor, :app:`Pyramid` 1.6. It also documents backwards |
814bdb
|
6 |
incompatibilities between the two versions and deprecations added to |
1464c1
|
7 |
:app:`Pyramid` 1.7, as well as software dependency changes and notable |
814bdb
|
8 |
documentation additions. |
MM |
9 |
|
|
10 |
Backwards Incompatibilities |
|
11 |
--------------------------- |
|
12 |
|
|
13 |
- The default hash algorithm for |
caf658
|
14 |
:class:`pyramid.authentication.AuthTktAuthenticationPolicy` has changed from |
SP |
15 |
``md5`` to ``sha512``. If you are using the authentication policy and need to |
|
16 |
continue using ``md5``, please explicitly set ``hashalg='md5'``. |
814bdb
|
17 |
|
bf33b2
|
18 |
If you are not currently specifying the ``hashalg`` option in your apps, then |
MM |
19 |
this change means any existing auth tickets (and associated cookies) will no |
|
20 |
longer be valid, users will be logged out, and have to login to their |
caf658
|
21 |
accounts again. |
814bdb
|
22 |
|
MM |
23 |
This change has been issuing a DeprecationWarning since :app:`Pyramid` 1.4. |
|
24 |
|
|
25 |
See https://github.com/Pylons/pyramid/pull/2496 |
|
26 |
|
|
27 |
- Python 2.6 and 3.2 are no longer supported by Pyramid. See |
|
28 |
https://github.com/Pylons/pyramid/issues/2368 and |
|
29 |
https://github.com/Pylons/pyramid/pull/2256 |
|
30 |
|
8ceb14
|
31 |
- The :func:`pyramid.session.check_csrf_token` function no longer validates a |
MM |
32 |
csrf token in the query string of a request. Only headers and request bodies |
|
33 |
are supported. See https://github.com/Pylons/pyramid/pull/2500 |
|
34 |
|
f038c7
|
35 |
- A global permission set via |
MM |
36 |
:meth:`pyramid.config.Configurator.set_default_permission` will no longer |
|
37 |
affect exception views. A permission must be set explicitly on the view for |
|
38 |
it to be enforced. See https://github.com/Pylons/pyramid/pull/2534 |
|
39 |
|
814bdb
|
40 |
Feature Additions |
MM |
41 |
----------------- |
|
42 |
|
|
43 |
- A new :ref:`view_derivers` concept has been added to Pyramid to allow |
|
44 |
framework authors to inject elements into the standard Pyramid view pipeline |
|
45 |
and affect all views in an application. This is similar to a decorator except |
|
46 |
that it has access to options passed to ``config.add_view`` and can affect |
|
47 |
other stages of the pipeline such as the raw response from a view or prior |
|
48 |
to security checks. See https://github.com/Pylons/pyramid/pull/2021 |
|
49 |
|
21d5be
|
50 |
- Added a ``require_csrf`` view option which will enforce CSRF checks on |
1799be
|
51 |
requests with an unsafe method as defined by RFC2616. If the CSRF check fails |
BJR |
52 |
a ``BadCSRFToken`` exception will be raised and may be caught by exception |
|
53 |
views (the default response is a ``400 Bad Request``). This option should be |
|
54 |
used in place of the deprecated ``check_csrf`` view predicate which would |
|
55 |
normally result in unexpected ``404 Not Found`` response to the client |
|
56 |
instead of a catchable exception. See :ref:`auto_csrf_checking`, |
|
57 |
https://github.com/Pylons/pyramid/pull/2413 and |
|
58 |
https://github.com/Pylons/pyramid/pull/2500 |
f038c7
|
59 |
|
MM |
60 |
- Added a new method, |
|
61 |
:meth:`pyramid.config.Configurator.set_csrf_default_options`, |
|
62 |
for configuring CSRF checks used by the ``require_csrf=True`` view option. |
|
63 |
This method can be used to turn on CSRF checks globally for every view |
|
64 |
in the application. This should be considered a good default for websites |
|
65 |
built on Pyramid. It is possible to opt-out of CSRF checks on a per-view |
|
66 |
basis by setting ``require_csrf=False`` on those views. |
|
67 |
See :ref:`auto_csrf_checking` and |
|
68 |
https://github.com/Pylons/pyramid/pull/2413 and |
|
69 |
https://github.com/Pylons/pyramid/pull/2518 |
814bdb
|
70 |
|
8ceb14
|
71 |
- Added an additional CSRF validation that checks the origin/referrer of a |
MM |
72 |
request and makes sure it matches the current ``request.domain``. This |
|
73 |
particular check is only active when accessing a site over HTTPS as otherwise |
|
74 |
browsers don't always send the required information. If this additional CSRF |
|
75 |
validation fails a ``BadCSRFOrigin`` exception will be raised and may be |
|
76 |
caught by exception views (the default response is ``400 Bad Request``). |
|
77 |
Additional allowed origins may be configured by setting |
|
78 |
``pyramid.csrf_trusted_origins`` to a list of domain names (with ports if on |
|
79 |
a non standard port) to allow. Subdomains are not allowed unless the domain |
|
80 |
name has been prefixed with a ``.``. See |
|
81 |
https://github.com/Pylons/pyramid/pull/2501 |
|
82 |
|
|
83 |
- Added a new :func:`pyramid.session.check_csrf_origin` API for validating the |
|
84 |
origin or referrer headers against the request's domain. |
|
85 |
See https://github.com/Pylons/pyramid/pull/2501 |
|
86 |
|
3fc6e7
|
87 |
- Subclasses of :class:`pyramid.httpexceptions.HTTPException` will now take |
MM |
88 |
into account the best match for the clients ``Accept`` header, and depending |
|
89 |
on what is requested will return ``text/html``, ``application/json`` or |
|
90 |
``text/plain``. The default for ``*/*`` is still ``text/html``, but if |
|
91 |
``application/json`` is explicitly mentioned it will now receive a valid |
|
92 |
JSON response. See https://github.com/Pylons/pyramid/pull/2489 |
814bdb
|
93 |
|
MM |
94 |
- A new event, :class:`pyramid.events.BeforeTraversal`, and interface |
|
95 |
:class:`pyramid.interfaces.IBeforeTraversal` have been introduced that will |
|
96 |
notify listeners before traversal starts in the router. |
bf33b2
|
97 |
See :ref:`router_chapter` as well as |
MM |
98 |
https://github.com/Pylons/pyramid/pull/2469 and |
814bdb
|
99 |
https://github.com/Pylons/pyramid/pull/1876 |
MM |
100 |
|
|
101 |
- A new method, :meth:`pyramid.request.Request.invoke_exception_view`, which |
|
102 |
can be used to invoke an exception view and get back a response. This is |
|
103 |
useful for rendering an exception view outside of the context of the |
|
104 |
``EXCVIEW`` tween where you may need more control over the request. |
|
105 |
See https://github.com/Pylons/pyramid/pull/2393 |
|
106 |
|
f038c7
|
107 |
- A global permission set via |
MM |
108 |
:meth:`pyramid.config.Configurator.set_default_permission` will no longer |
|
109 |
affect exception views. A permission must be set explicitly on the view for |
|
110 |
it to be enforced. See https://github.com/Pylons/pyramid/pull/2534 |
|
111 |
|
814bdb
|
112 |
- Allow a leading ``=`` on the key of the request param predicate. |
caf658
|
113 |
For example, ``'=abc=1'`` is equivalent down to |
814bdb
|
114 |
``request.params['=abc'] == '1'``. |
MM |
115 |
See https://github.com/Pylons/pyramid/pull/1370 |
|
116 |
|
|
117 |
- Allow using variable substitutions like ``%(LOGGING_LOGGER_ROOT_LEVEL)s`` |
|
118 |
for logging sections of the .ini file and populate these variables from |
|
119 |
the ``pserve`` command line -- e.g.: |
caf658
|
120 |
|
SP |
121 |
``pserve development.ini LOGGING_LOGGER_ROOT_LEVEL=DEBUG`` |
|
122 |
|
|
123 |
This support is thanks to the new ``global_conf`` option on |
814bdb
|
124 |
:func:`pyramid.paster.setup_logging`. |
MM |
125 |
See https://github.com/Pylons/pyramid/pull/2399 |
|
126 |
|
f038c7
|
127 |
- The :attr:`pyramid.tweens.EXCVIEW` tween will now re-raise the original |
MM |
128 |
exception if no exception view could be found to handle it. This allows |
40ab35
|
129 |
the exception to be handled upstream by another tween or middleware. |
f038c7
|
130 |
See https://github.com/Pylons/pyramid/pull/2567 |
MM |
131 |
|
814bdb
|
132 |
Deprecations |
MM |
133 |
------------ |
|
134 |
|
|
135 |
- The ``check_csrf`` view predicate has been deprecated. Use the |
|
136 |
new ``require_csrf`` option or the ``pyramid.require_default_csrf`` setting |
|
137 |
to ensure that the :class:`pyramid.exceptions.BadCSRFToken` exception is |
|
138 |
raised. See https://github.com/Pylons/pyramid/pull/2413 |
|
139 |
|
|
140 |
- Support for Python 3.3 will be removed in Pyramid 1.8. |
|
141 |
https://github.com/Pylons/pyramid/issues/2477 |
|
142 |
|
|
143 |
Scaffolding Enhancements |
|
144 |
------------------------ |
|
145 |
|
|
146 |
- A complete overhaul of the ``alchemy`` scaffold to show more modern best |
caf658
|
147 |
practices with regards to SQLAlchemy session management, as well as a more |
814bdb
|
148 |
modular approach to configuration, separating routes into a separate module |
MM |
149 |
to illustrate uses of :meth:`pyramid.config.Configurator.include`. |
091c27
|
150 |
See https://github.com/Pylons/pyramid/pull/2024 |
814bdb
|
151 |
|
MM |
152 |
Documentation Enhancements |
|
153 |
-------------------------- |
|
154 |
|
|
155 |
A massive overhaul of the packaging and tools used in the documentation |
|
156 |
was completed in https://github.com/Pylons/pyramid/pull/2468. A summary |
|
157 |
follows: |
|
158 |
|
|
159 |
- All docs now recommend using ``pip`` instead of ``easy_install``. |
|
160 |
|
|
161 |
- The installation docs now expect the user to be using Python 3.4 or |
|
162 |
greater with access to the ``python3 -m venv`` tool to create virtual |
|
163 |
environments. |
|
164 |
|
caf658
|
165 |
- Tutorials now use ``py.test`` and ``pytest-cov`` instead of ``nose`` and |
SP |
166 |
``coverage``. |
814bdb
|
167 |
|
MM |
168 |
- Further updates to the scaffolds as well as tutorials and their src files. |
|
169 |
|
|
170 |
Along with the overhaul of the ``alchemy`` scaffold came a total overhaul |
|
171 |
of the :ref:`bfg_sql_wiki_tutorial` tutorial to introduce more modern |
|
172 |
features into the usage of SQLAlchemy with Pyramid and provide a better |
|
173 |
starting point for new projects. See |
|
174 |
https://github.com/Pylons/pyramid/pull/2024 for more. Highlights were: |
|
175 |
|
|
176 |
- New SQLAlchemy session management without any global ``DBSession``. Replaced |
|
177 |
by a per-request ``request.dbsession`` property. |
|
178 |
|
|
179 |
- A new authentication chapter demonstrating how to get simple authentication |
|
180 |
bootstrapped quickly in an application. |
|
181 |
|
|
182 |
- Authorization was overhauled to show the use of per-route context factories |
|
183 |
which demonstrate object-level authorization on top of simple group-level |
|
184 |
authorization. Did you want to restrict page edits to only the owner but |
caf658
|
185 |
couldn't figure it out before? Here you go! |
814bdb
|
186 |
|
MM |
187 |
- The users and groups are stored in the database now instead of within |
|
188 |
tutorial-specific global variables. |
|
189 |
|
|
190 |
- User passwords are stored using ``bcrypt``. |