commit | author | age
|
41aeac
|
1 |
What's New in Pyramid 1.3 |
d83b39
|
2 |
========================= |
CM |
3 |
|
|
4 |
This article explains the new features in :app:`Pyramid` version 1.3 as |
|
5 |
compared to its predecessor, :app:`Pyramid` 1.2. It also documents backwards |
|
6 |
incompatibilities between the two versions and deprecations added to |
|
7 |
:app:`Pyramid` 1.3, 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.3 follow. |
|
14 |
|
|
15 |
Python 3 Compatibility |
|
16 |
~~~~~~~~~~~~~~~~~~~~~~ |
|
17 |
|
53c242
|
18 |
.. image:: python-3.png |
CM |
19 |
|
1fc45b
|
20 |
Pyramid continues to run on Python 2, but Pyramid is now also Python 3 |
406402
|
21 |
compatible. To use Pyramid under Python 3, Python 3.3 or better is required. |
ce61d6
|
22 |
|
1fc45b
|
23 |
Many Pyramid add-ons are already Python 3 compatible. For example, |
731d5f
|
24 |
``pyramid_debugtoolbar``, ``pyramid_jinja2``, ``pyramid_exclog``, |
CM |
25 |
``pyramid_tm``, ``pyramid_mailer``, and ``pyramid_handlers`` are all Python |
|
26 |
3-ready. But other add-ons are known to work only under Python 2. Also, |
|
27 |
some scaffolding dependencies (particularly ZODB) do not yet work under |
|
28 |
Python 3. |
005e73
|
29 |
|
1fc45b
|
30 |
Please be patient as we gain full ecosystem support for Python 3. You can |
CM |
31 |
see more details about ongoing porting efforts at |
ce61d6
|
32 |
https://github.com/Pylons/pyramid/wiki/Python-3-Porting . |
CM |
33 |
|
731d5f
|
34 |
Python 3 compatibility required dropping some package dependencies and |
CM |
35 |
support for older Python versions and platforms. See the "Backwards |
|
36 |
Incompatibilities" section below for more information. |
|
37 |
|
1fc45b
|
38 |
The ``paster`` Command Has Been Replaced |
CM |
39 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ce61d6
|
40 |
|
1fc45b
|
41 |
We've replaced the ``paster`` command with Pyramid-specific analogues. Why? |
CM |
42 |
The libraries that supported the ``paster`` command named ``Paste`` and |
|
43 |
``PasteScript`` do not run under Python 3, and we were unwilling to port and |
|
44 |
maintain them ourselves. As a result, we've had to make some changes. |
ce61d6
|
45 |
|
CM |
46 |
Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application |
|
47 |
using ``paster create``, like so:: |
|
48 |
|
f73f0e
|
49 |
$ $VENV/bin/paster create -t pyramid_starter foo |
ce61d6
|
50 |
|
1fc45b
|
51 |
In 1.3, you're now instead required to create an application using |
CM |
52 |
``pcreate`` like so:: |
ce61d6
|
53 |
|
f73f0e
|
54 |
$ $VENV/bin/pcreate -s starter foo |
ce61d6
|
55 |
|
1fc45b
|
56 |
``pcreate`` is required to be used for internal Pyramid scaffolding; |
CM |
57 |
externally distributed scaffolding may allow for both ``pcreate`` and/or |
ce61d6
|
58 |
``paster create``. |
CM |
59 |
|
1fc45b
|
60 |
In previous Pyramid versions, you ran a Pyramid application like so:: |
ce61d6
|
61 |
|
f73f0e
|
62 |
$ $VENV/bin/paster serve development.ini |
1fc45b
|
63 |
|
CM |
64 |
Instead, you now must use the ``pserve`` command in 1.3:: |
|
65 |
|
f73f0e
|
66 |
$ $VENV/bin/pserve development.ini |
ce61d6
|
67 |
|
CM |
68 |
The ``ini`` configuration file format supported by Pyramid has not changed. |
|
69 |
As a result, Python 2-only users can install PasteScript manually and use |
bc08bb
|
70 |
``paster serve`` instead if they like. However, using ``pserve`` will work |
1fc45b
|
71 |
under both Python 2 and Python 3. |
ce61d6
|
72 |
|
c8061e
|
73 |
Analogues of ``paster pshell``, ``paster pviews``, ``paster request`` and |
CM |
74 |
``paster ptweens`` also exist under the respective console script names |
|
75 |
``pshell``, ``pviews``, ``prequest`` and ``ptweens``. |
ce61d6
|
76 |
|
1fc45b
|
77 |
``paste.httpserver`` replaced by ``waitress`` in Scaffolds |
CM |
78 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
79 |
|
|
80 |
Because the ``paste.httpserver`` server we used previously in scaffolds is |
|
81 |
not Python 3 compatible, we've made the default WSGI server used by Pyramid |
|
82 |
scaffolding the :term:`waitress` server. The waitress server is both Python |
|
83 |
2 and Python 3 compatible. |
|
84 |
|
|
85 |
Once you create a project from a scaffold, its ``development.ini`` and |
|
86 |
``production.ini`` will have the following line:: |
ce61d6
|
87 |
|
030d10
|
88 |
use = egg:waitress#main |
ce61d6
|
89 |
|
CM |
90 |
Instead of this (which was the default in older versions):: |
|
91 |
|
|
92 |
use = egg:Paste#http |
|
93 |
|
1fc45b
|
94 |
.. note:: |
6747aa
|
95 |
|
1fc45b
|
96 |
``paste.httpserver`` "helped" by converting header values that were Unicode |
CM |
97 |
into strings, which was a feature that subverted the :term:`WSGI` |
|
98 |
specification. The ``waitress`` server, on the other hand implements the |
|
99 |
WSGI spec more fully. This specifically may affect you if you are modifying |
|
100 |
headers on your responses. The following error might be an indicator of |
|
101 |
this problem: **AssertionError: Header values must be strings, please check |
|
102 |
the type of the header being returned.** A common case would be returning |
|
103 |
Unicode headers instead of string headers. |
|
104 |
|
|
105 |
Compatibility Helper Library |
|
106 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
6747aa
|
107 |
|
ce61d6
|
108 |
A new :mod:`pyramid.compat` module was added which provides Python 2/3 |
CM |
109 |
straddling support for Pyramid add-ons and development environments. |
d83b39
|
110 |
|
CM |
111 |
Introspection |
|
112 |
~~~~~~~~~~~~~ |
|
113 |
|
|
114 |
A configuration introspection system was added; see |
|
115 |
:ref:`using_introspection` and :ref:`introspection` for more information on |
|
116 |
using the introspection system as a developer. |
|
117 |
|
2f624f
|
118 |
The latest release of the pyramid debug toolbar (0.9.7+) provides an |
ce61d6
|
119 |
"Introspection" panel that exposes introspection information to a Pyramid |
CM |
120 |
application developer. |
d83b39
|
121 |
|
CM |
122 |
New APIs were added to support introspection |
|
123 |
:attr:`pyramid.registry.Introspectable`, |
|
124 |
:attr:`pyramid.config.Configurator.introspector`, |
|
125 |
:attr:`pyramid.config.Configurator.introspectable`, |
|
126 |
:attr:`pyramid.registry.Registry.introspector`. |
|
127 |
|
4375cf
|
128 |
``@view_defaults`` Decorator |
CM |
129 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
130 |
|
|
131 |
If you use a class as a view, you can use the new |
|
132 |
:class:`pyramid.view.view_defaults` class decorator on the class to provide |
|
133 |
defaults to the view configuration information used by every ``@view_config`` |
|
134 |
decorator that decorates a method of that class. |
|
135 |
|
|
136 |
For instance, if you've got a class that has methods that represent "REST |
|
137 |
actions", all which are mapped to the same route, but different request |
|
138 |
methods, instead of this: |
|
139 |
|
|
140 |
.. code-block:: python |
|
141 |
:linenos: |
|
142 |
|
|
143 |
from pyramid.view import view_config |
|
144 |
from pyramid.response import Response |
|
145 |
|
|
146 |
class RESTView(object): |
|
147 |
def __init__(self, request): |
|
148 |
self.request = request |
|
149 |
|
|
150 |
@view_config(route_name='rest', request_method='GET') |
|
151 |
def get(self): |
|
152 |
return Response('get') |
|
153 |
|
|
154 |
@view_config(route_name='rest', request_method='POST') |
|
155 |
def post(self): |
|
156 |
return Response('post') |
|
157 |
|
|
158 |
@view_config(route_name='rest', request_method='DELETE') |
|
159 |
def delete(self): |
|
160 |
return Response('delete') |
|
161 |
|
|
162 |
You can do this: |
|
163 |
|
|
164 |
.. code-block:: python |
|
165 |
:linenos: |
|
166 |
|
|
167 |
from pyramid.view import view_defaults |
|
168 |
from pyramid.view import view_config |
|
169 |
from pyramid.response import Response |
|
170 |
|
|
171 |
@view_defaults(route_name='rest') |
|
172 |
class RESTView(object): |
|
173 |
def __init__(self, request): |
|
174 |
self.request = request |
|
175 |
|
|
176 |
@view_config(request_method='GET') |
|
177 |
def get(self): |
|
178 |
return Response('get') |
|
179 |
|
|
180 |
@view_config(request_method='POST') |
|
181 |
def post(self): |
|
182 |
return Response('post') |
|
183 |
|
|
184 |
@view_config(request_method='DELETE') |
|
185 |
def delete(self): |
|
186 |
return Response('delete') |
|
187 |
|
|
188 |
This also works for imperative view configurations that involve a class. |
|
189 |
|
|
190 |
See :ref:`view_defaults` for more information. |
|
191 |
|
b73edc
|
192 |
Extending a Request without Subclassing |
MM |
193 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
194 |
|
|
195 |
It is now possible to extend a :class:`pyramid.request.Request` object |
6c2e8f
|
196 |
with property descriptors without having to create a custom request factory. |
MM |
197 |
The new method :meth:`pyramid.config.Configurator.set_request_property` |
|
198 |
provides an entry point for addons to register properties which will be |
|
199 |
added to each request. New properties may be reified, effectively caching |
|
200 |
the return value for the lifetime of the instance. Common use-cases for this |
|
201 |
would be to get a database connection for the request or identify the current |
|
202 |
user. The new method :meth:`pyramid.request.Request.set_property` has been |
|
203 |
added, as well, but the configurator method should be preferred as it |
|
204 |
provides conflict detection and consistency in the lifetime of the |
|
205 |
properties. |
b73edc
|
206 |
|
a7fe30
|
207 |
Not Found and Forbidden View Helpers |
CM |
208 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
209 |
|
|
210 |
Not Found helpers: |
2d0458
|
211 |
|
CM |
212 |
- New API: :meth:`pyramid.config.Configurator.add_notfound_view`. This is a |
057a6c
|
213 |
wrapper for :meth:`pyramid.config.Configurator.add_view` which provides |
2d0458
|
214 |
support for an "append_slash" feature as well as doing the right thing when |
2f4bde
|
215 |
it comes to permissions (a Not Found View should always be public). It |
2d0458
|
216 |
should be preferred over calling ``add_view`` directly with |
CM |
217 |
``context=HTTPNotFound`` as was previously recommended. |
|
218 |
|
057a6c
|
219 |
- New API: :class:`pyramid.view.notfound_view_config`. This is a decorator |
2d0458
|
220 |
constructor like :class:`pyramid.view.view_config` that calls |
CM |
221 |
:meth:`pyramid.config.Configurator.add_notfound_view` when scanned. It |
|
222 |
should be preferred over using ``pyramid.view.view_config`` with |
|
223 |
``context=HTTPNotFound`` as was previously recommended. |
a7fe30
|
224 |
|
CM |
225 |
Forbidden helpers: |
|
226 |
|
|
227 |
- New API: :meth:`pyramid.config.Configurator.add_forbidden_view`. This is a |
057a6c
|
228 |
wrapper for :meth:`pyramid.config.Configurator.add_view` which does the |
a7fe30
|
229 |
right thing about permissions. It should be preferred over calling |
CM |
230 |
``add_view`` directly with ``context=HTTPForbidden`` as was previously |
|
231 |
recommended. |
|
232 |
|
|
233 |
- New API: :class:`pyramid.view.forbidden_view_config`. This is a decorator |
|
234 |
constructor like :class:`pyramid.view.view_config` that calls |
|
235 |
:meth:`pyramid.config.Configurator.add_forbidden_view` when scanned. It |
|
236 |
should be preferred over using ``pyramid.view.view_config`` with |
|
237 |
``context=HTTPForbidden`` as was previously recommended. |
2d0458
|
238 |
|
d83b39
|
239 |
Minor Feature Additions |
CM |
240 |
----------------------- |
|
241 |
|
56df90
|
242 |
- New APIs: :class:`pyramid.path.AssetResolver` and |
CM |
243 |
:class:`pyramid.path.DottedNameResolver`. The former can be used to |
|
244 |
resolve an :term:`asset specification` to an API that can be used to read |
|
245 |
the asset's data, the latter can be used to resolve a :term:`dotted Python |
|
246 |
name` to a module or a package. |
|
247 |
|
d83b39
|
248 |
- A ``mako.directories`` setting is no longer required to use Mako templates |
CM |
249 |
Rationale: Mako template renderers can be specified using an absolute asset |
|
250 |
spec. An entire application can be written with such asset specs, |
|
251 |
requiring no ordered lookup path. |
|
252 |
|
|
253 |
- ``bpython`` interpreter compatibility in ``pshell``. See |
|
254 |
:ref:`ipython_or_bpython` for more information. |
|
255 |
|
c54498
|
256 |
- Added :func:`pyramid.paster.get_appsettings` API function. This function |
d83b39
|
257 |
returns the settings defined within an ``[app:...]`` section in a |
CM |
258 |
PasteDeploy ``ini`` file. |
|
259 |
|
|
260 |
- Added :func:`pyramid.paster.setup_logging` API function. This function |
|
261 |
sets up Python logging according to the logging configuration in a |
|
262 |
PasteDeploy ``ini`` file. |
|
263 |
|
|
264 |
- Configuration conflict reporting is reported in a more understandable way |
|
265 |
("Line 11 in file..." vs. a repr of a tuple of similar info). |
|
266 |
|
ce61d6
|
267 |
- We allow extra keyword arguments to be passed to the |
d83b39
|
268 |
:meth:`pyramid.config.Configurator.action` method. |
CM |
269 |
|
057a6c
|
270 |
- Responses generated by Pyramid's :class:`pyramid.static.static_view` now use |
a41c8c
|
271 |
a ``wsgi.file_wrapper`` (see |
CM |
272 |
http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling) |
|
273 |
when one is provided by the web server. |
|
274 |
|
e4b8fa
|
275 |
- The :meth:`pyramid.config.Configurator.scan` method can be passed an |
CM |
276 |
``ignore`` argument, which can be a string, a callable, or a list |
|
277 |
consisting of strings and/or callables. This feature allows submodules, |
|
278 |
subpackages, and global objects from being scanned. See |
|
279 |
http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for |
|
280 |
more information about how to use the ``ignore`` argument to ``scan``. |
|
281 |
|
c51896
|
282 |
- Add :meth:`pyramid.config.Configurator.add_traverser` API method. See |
f9bcf4
|
283 |
:ref:`changing_the_traverser` for more information. This is not a new |
CM |
284 |
feature, it just provides an API for adding a traverser without needing to |
|
285 |
use the ZCA API. |
c51896
|
286 |
|
CM |
287 |
- Add :meth:`pyramid.config.Configurator.add_resource_url_adapter` API |
|
288 |
method. See :ref:`changing_resource_url` for more information. This is |
|
289 |
not a new feature, it just provides an API for adding a resource url |
|
290 |
adapter without needing to use the ZCA API. |
f9bcf4
|
291 |
|
CM |
292 |
- Better error messages when a view callable returns a value that cannot be |
|
293 |
converted to a response (for example, when a view callable returns a |
|
294 |
dictionary without a renderer defined, or doesn't return any value at all). |
|
295 |
The error message now contains information about the view callable itself |
|
296 |
as well as the result of calling it. |
|
297 |
|
|
298 |
- Better error message when a .pyc-only module is ``config.include`` -ed. |
|
299 |
This is not permitted due to error reporting requirements, and a better |
|
300 |
error message is shown when it is attempted. Previously it would fail with |
|
301 |
something like "AttributeError: 'NoneType' object has no attribute |
|
302 |
'rfind'". |
|
303 |
|
b2ea4c
|
304 |
- The system value ``req`` is now supplied to renderers as an alias for |
4786ca
|
305 |
``request``. This means that you can now, for example, in a template, do |
b2ea4c
|
306 |
``req.route_url(...)`` instead of ``request.route_url(...)``. This is |
CM |
307 |
purely a change to reduce the amount of typing required to use request |
|
308 |
methods and attributes from within templates. The value ``request`` is |
|
309 |
still available too, this is just an alternative. |
c51896
|
310 |
|
CM |
311 |
- A new interface was added: :class:`pyramid.interfaces.IResourceURL`. An |
|
312 |
adapter implementing its interface can be used to override resource URL |
|
313 |
generation when :meth:`pyramid.request.Request.resource_url` is called. |
|
314 |
This interface replaces the now-deprecated |
|
315 |
``pyramid.interfaces.IContextURL`` interface. |
|
316 |
|
|
317 |
- The dictionary passed to a resource's ``__resource_url__`` method (see |
|
318 |
:ref:`overriding_resource_url_generation`) now contains an ``app_url`` key, |
|
319 |
representing the application URL generated during |
|
320 |
:meth:`pyramid.request.Request.resource_url`. It represents a potentially |
|
321 |
customized URL prefix, containing potentially custom scheme, host and port |
|
322 |
information passed by the user to ``request.resource_url``. It should be |
|
323 |
used instead of ``request.application_url`` where necessary. |
|
324 |
|
|
325 |
- The :meth:`pyramid.request.Request.resource_url` API now accepts these |
|
326 |
arguments: ``app_url``, ``scheme``, ``host``, and ``port``. The app_url |
|
327 |
argument can be used to replace the URL prefix wholesale during url |
|
328 |
generation. The ``scheme``, ``host``, and ``port`` arguments can be used |
|
329 |
to replace the respective default values of ``request.application_url`` |
|
330 |
partially. |
|
331 |
|
|
332 |
- A new API named :meth:`pyramid.request.Request.resource_path` now exists. |
388544
|
333 |
It works like :meth:`pyramid.request.Request.resource_url` but produces a |
c51896
|
334 |
relative URL rather than an absolute one. |
CM |
335 |
|
|
336 |
- The :meth:`pyramid.request.Request.route_url` API now accepts these |
|
337 |
arguments: ``_app_url``, ``_scheme``, ``_host``, and ``_port``. The |
|
338 |
``_app_url`` argument can be used to replace the URL prefix wholesale |
|
339 |
during url generation. The ``_scheme``, ``_host``, and ``_port`` arguments |
|
340 |
can be used to replace the respective default values of |
|
341 |
``request.application_url`` partially. |
4786ca
|
342 |
|
6b3cca
|
343 |
- New APIs: :class:`pyramid.response.FileResponse` and |
CM |
344 |
:class:`pyramid.response.FileIter`, for usage in views that must serve |
|
345 |
files "manually". |
|
346 |
|
d83b39
|
347 |
Backwards Incompatibilities |
CM |
348 |
--------------------------- |
|
349 |
|
1fc45b
|
350 |
- Pyramid no longer runs on Python 2.5. This includes the most recent |
CM |
351 |
release of Jython and the Python 2.5 version of Google App Engine. |
|
352 |
|
|
353 |
The reason? We could not easily "straddle" Python 2 and 3 versions and |
|
354 |
support Python 2 versions older than Python 2.6. You will need Python 2.6 |
|
355 |
or better to run this version of Pyramid. If you need to use Python 2.5, |
|
356 |
you should use the most recent 1.2.X release of Pyramid. |
|
357 |
|
|
358 |
- The names of available scaffolds have changed and the flags supported by |
|
359 |
``pcreate`` are different than those that were supported by ``paster |
|
360 |
create``. For example, ``pyramid_alchemy`` is now just ``alchemy``. |
d83b39
|
361 |
|
CM |
362 |
- The ``paster`` command is no longer the documented way to create projects, |
|
363 |
start the server, or run debugging commands. To create projects from |
|
364 |
scaffolds, ``paster create`` is replaced by the ``pcreate`` console script. |
|
365 |
To serve up a project, ``paster serve`` is replaced by the ``pserve`` |
|
366 |
console script. New console scripts named ``pshell``, ``pviews``, |
|
367 |
``proutes``, and ``ptweens`` do what their ``paster <commandname>`` |
|
368 |
equivalents used to do. All relevant narrative documentation has been |
|
369 |
updated. Rationale: the Paste and PasteScript packages do not run under |
|
370 |
Python 3. |
|
371 |
|
|
372 |
- The default WSGI server run as the result of ``pserve`` from newly rendered |
030d10
|
373 |
scaffolding is now the ``waitress`` WSGI server instead of the |
CM |
374 |
``paste.httpserver`` server. Rationale: the Paste and PasteScript packages |
|
375 |
do not run under Python 3. |
d83b39
|
376 |
|
CM |
377 |
- The ``pshell`` command (see "paster pshell") no longer accepts a |
|
378 |
``--disable-ipython`` command-line argument. Instead, it accepts a ``-p`` |
|
379 |
or ``--python-shell`` argument, which can be any of the values ``python``, |
|
380 |
``ipython`` or ``bpython``. |
|
381 |
|
e307fc
|
382 |
- Removed the ``pyramid.renderers.renderer_from_name`` function. It has been |
CM |
383 |
deprecated since Pyramid 1.0, and was never an API. |
|
384 |
|
b74abe
|
385 |
- To use ZCML with versions of Pyramid >= 1.3, you will need ``pyramid_zcml`` |
CM |
386 |
version >= 0.8 and ``zope.configuration`` version >= 3.8.0. The |
|
387 |
``pyramid_zcml`` package version 0.8 is backwards compatible all the way to |
|
388 |
Pyramid 1.0, so you won't be warned if you have older versions installed |
|
389 |
and upgrade Pyramid itself "in-place"; it may simply break instead |
|
390 |
(particularly if you use ZCML's ``includeOverrides`` directive). |
|
391 |
|
057a6c
|
392 |
- String values passed to :meth:`pyramid.request.Request.route_url` or |
TL |
393 |
:meth:`pyramid.request.Request.route_path` that are meant to replace |
305d23
|
394 |
"remainder" matches will now be URL-quoted except for embedded slashes. For |
CM |
395 |
example:: |
962816
|
396 |
|
CM |
397 |
config.add_route('remain', '/foo*remainder') |
|
398 |
request.route_path('remain', remainder='abc / def') |
|
399 |
# -> '/foo/abc%20/%20def' |
|
400 |
|
|
401 |
Previously string values passed as remainder replacements were tacked on |
|
402 |
untouched, without any URL-quoting. But this doesn't really work logically |
|
403 |
if the value passed is Unicode (raw unicode cannot be placed in a URL or in |
|
404 |
a path) and it is inconsistent with the rest of the URL generation |
|
405 |
machinery if the value is a string (it won't be quoted unless by the |
|
406 |
caller). |
|
407 |
|
|
408 |
Some folks will have been relying on the older behavior to tack on query |
|
409 |
string elements and anchor portions of the URL; sorry, you'll need to |
|
410 |
change your code to use the ``_query`` and/or ``_anchor`` arguments to |
|
411 |
``route_path`` or ``route_url`` to do this now. |
|
412 |
|
|
413 |
- If you pass a bytestring that contains non-ASCII characters to |
305d23
|
414 |
:meth:`pyramid.config.Configurator.add_route` as a pattern, it will now |
CM |
415 |
fail at startup time. Use Unicode instead. |
962816
|
416 |
|
a41c8c
|
417 |
- The ``path_info`` route and view predicates now match against |
CM |
418 |
``request.upath_info`` (Unicode) rather than ``request.path_info`` |
|
419 |
(indeterminate value based on Python 3 vs. Python 2). This has to be done |
|
420 |
to normalize matching on Python 2 and Python 3. |
|
421 |
|
e3f9d0
|
422 |
- The ``match_param`` view predicate no longer accepts a dict. This will have |
CM |
423 |
no negative affect because the implementation was broken for dict-based |
|
424 |
arguments. |
|
425 |
|
c51896
|
426 |
- The ``pyramid.interfaces.IContextURL`` interface has been deprecated. |
CM |
427 |
People have been instructed to use this to register a resource url adapter |
|
428 |
in the "Hooks" chapter to use to influence |
|
429 |
:meth:`pyramid.request.Request.resource_url` URL generation for resources |
|
430 |
found via custom traversers since Pyramid 1.0. |
|
431 |
|
305d23
|
432 |
The interface still exists and registering an adapter using it as |
CM |
433 |
documented in older versions still works, but this interface will be |
|
434 |
removed from the software after a few major Pyramid releases. You should |
|
435 |
replace it with an equivalent :class:`pyramid.interfaces.IResourceURL` |
|
436 |
adapter, registered using the new |
c51896
|
437 |
:meth:`pyramid.config.Configurator.add_resource_url_adapter` API. A |
CM |
438 |
deprecation warning is now emitted when a |
|
439 |
``pyramid.interfaces.IContextURL`` adapter is found when |
|
440 |
:meth:`pyramid.request.Request.resource_url` is called. |
|
441 |
|
2d0458
|
442 |
- Remove ``pyramid.config.Configurator.with_context`` class method. It was |
CM |
443 |
never an API, it is only used by ``pyramid_zcml`` and its functionality has |
|
444 |
been moved to that package's latest release. This means that you'll need |
|
445 |
to use the 0.9.2 or later release of ``pyramid_zcml`` with this release of |
|
446 |
Pyramid. |
|
447 |
|
|
448 |
- The older deprecated ``set_notfound_view`` Configurator method is now an |
a7fe30
|
449 |
alias for the new ``add_notfound_view`` Configurator method. Likewise, the |
CM |
450 |
older deprecated ``set_forbidden_view`` is now an alias for the new |
|
451 |
``add_forbidden_view`` Configurator method. This has the following impact: |
|
452 |
the ``context`` sent to views with a ``(context, request)`` call signature |
|
453 |
registered via the ``set_notfound_view`` or ``set_forbidden_view`` will now |
|
454 |
be an exception object instead of the actual resource context found. Use |
2d0458
|
455 |
``request.context`` to get the actual resource context. It's also |
CM |
456 |
recommended to disuse ``set_notfound_view`` in favor of |
a7fe30
|
457 |
``add_notfound_view``, and disuse ``set_forbidden_view`` in favor of |
CM |
458 |
``add_forbidden_view`` despite the aliasing. |
2d0458
|
459 |
|
CM |
460 |
Deprecations |
|
461 |
------------ |
|
462 |
|
|
463 |
- The API documentation for ``pyramid.view.append_slash_notfound_view`` and |
|
464 |
``pyramid.view.AppendSlashNotFoundViewFactory`` was removed. These names |
|
465 |
still exist and are still importable, but they are no longer APIs. Use |
|
466 |
``pyramid.config.Configurator.add_notfound_view(append_slash=True)`` or |
|
467 |
``pyramid.view.notfound_view_config(append_slash=True)`` to get the same |
|
468 |
behavior. |
|
469 |
|
a7fe30
|
470 |
- The ``set_forbidden_view`` and ``set_notfound_view`` methods of the |
CM |
471 |
Configurator were removed from the documentation. They have been |
|
472 |
deprecated since Pyramid 1.1. |
2d0458
|
473 |
|
01eac9
|
474 |
- All references to the ``tmpl_context`` request variable were removed from |
CM |
475 |
the docs. Its existence in Pyramid is confusing for people who were never |
|
476 |
Pylons users. It was added as a porting convenience for Pylons users in |
|
477 |
Pyramid 1.0, but it never caught on because the Pyramid rendering system is |
|
478 |
a lot different than Pylons' was, and alternate ways exist to do what it |
|
479 |
was designed to offer in Pylons. It will continue to exist "forever" but |
|
480 |
it will not be recommended or mentioned in the docs. |
|
481 |
|
01c76b
|
482 |
- Remove references to do-nothing ``pyramid.debug_templates`` setting in all |
CM |
483 |
Pyramid-provided .ini files. This setting previously told Chameleon to render |
|
484 |
better exceptions; now Chameleon always renders nice exceptions regardless of |
|
485 |
the value of this setting. |
|
486 |
|
1fc45b
|
487 |
Known Issues |
CM |
488 |
------------ |
|
489 |
|
|
490 |
- As of this writing (the release of Pyramid 1.3b2), if you attempt to |
|
491 |
install a Pyramid project that used the ``alchemy`` scaffold via ``setup.py |
|
492 |
develop`` on Python 3.2, it will quit with an installation error while |
|
493 |
trying to install ``Pygments``. If this happens, please just rerun the |
|
494 |
``setup.py develop`` command again, and it will complete successfully. |
c0f937
|
495 |
This is due to a minor bug in SQLAlchemy 0.7.5 under Python 3, and has been |
1fc45b
|
496 |
fixed in a later SQLAlchemy release. Keep an eye on |
CM |
497 |
http://www.sqlalchemy.org/trac/ticket/2421 |
|
498 |
|
d83b39
|
499 |
Documentation Enhancements |
CM |
500 |
-------------------------- |
|
501 |
|
|
502 |
- The :ref:`bfg_sql_wiki_tutorial` has been updated. It now uses |
|
503 |
``@view_config`` decorators and an explicit database population script. |
|
504 |
|
|
505 |
- Minor updates to the :ref:`bfg_wiki_tutorial`. |
|
506 |
|
|
507 |
- A narrative documentation chapter named :ref:`extconfig_narr` was added; it |
|
508 |
describes how to add a custom :term:`configuration directive`, and how use |
|
509 |
the :meth:`pyramid.config.Configurator.action` method within custom |
|
510 |
directives. It also describes how to add :term:`introspectable` objects. |
|
511 |
|
|
512 |
- A narrative documentation chapter named :ref:`using_introspection` was |
|
513 |
added. It describes how to query the introspection system. |
|
514 |
|
bfd4b3
|
515 |
- Added an API docs chapter for :mod:`pyramid.scaffolds`. |
CM |
516 |
|
|
517 |
- Added a narrative docs chapter named :ref:`scaffolding_chapter`. |
|
518 |
|
c8061e
|
519 |
- Added a description of the ``prequest`` command-line script at |
CM |
520 |
:ref:`invoking_a_request`. |
|
521 |
|
61838b
|
522 |
- Added a section to the "Command-Line Pyramid" chapter named |
CM |
523 |
:ref:`making_a_console_script`. |
|
524 |
|
9003a8
|
525 |
- Removed the "Running Pyramid on Google App Engine" tutorial from the main |
34515f
|
526 |
docs. It survives on in the Pyramid Community Cookbook as |
SP |
527 |
:ref:`Pyramid on Google's App Engine (using appengine-monkey) |
|
528 |
<cookbook:appengine_tutorial>`. Rationale: it provides the correct info for |
|
529 |
the Python 2.5 version of GAE only, and this version of Pyramid does not |
|
530 |
support Python 2.5. |
9003a8
|
531 |
|
a7fe30
|
532 |
- Updated the :ref:`changing_the_forbidden_view` section, replacing |
CM |
533 |
explanations of registering a view using ``add_view`` or ``view_config`` |
|
534 |
with ones using ``add_forbidden_view`` or ``forbidden_view_config``. |
|
535 |
|
2d0458
|
536 |
- Updated the :ref:`changing_the_notfound_view` section, replacing |
CM |
537 |
explanations of registering a view using ``add_view`` or ``view_config`` |
|
538 |
with ones using ``add_notfound_view`` or ``notfound_view_config``. |
|
539 |
|
|
540 |
- Updated the :ref:`redirecting_to_slash_appended_routes` section, replacing |
|
541 |
explanations of registering a view using ``add_view`` or ``view_config`` |
|
542 |
with ones using ``add_notfound_view`` or ``notfound_view_config`` |
|
543 |
|
a7fe30
|
544 |
- Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather |
CM |
545 |
than ``pyramid.view.view_config`` with an HTTPForbidden context. |
|
546 |
|
d83b39
|
547 |
Dependency Changes |
CM |
548 |
------------------ |
|
549 |
|
|
550 |
- Pyramid no longer depends on the ``zope.component`` package, except as a |
|
551 |
testing dependency. |
|
552 |
|
|
553 |
- Pyramid now depends on the following package versions: |
|
554 |
zope.interface>=3.8.0, WebOb>=1.2dev, repoze.lru>=0.4, |
|
555 |
zope.deprecation>=3.5.0, translationstring>=0.4 for Python 3 compatibility |
|
556 |
purposes. It also, as a testing dependency, depends on WebTest>=1.3.1 for |
|
557 |
the same reason. |
|
558 |
|
|
559 |
- Pyramid no longer depends on the ``Paste`` or ``PasteScript`` packages. |
|
560 |
These packages are not Python 3 compatible. |
|
561 |
|
f9bcf4
|
562 |
- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support. |
CM |
563 |
|
d83b39
|
564 |
Scaffolding Changes |
CM |
565 |
------------------- |
|
566 |
|
|
567 |
- Rendered scaffolds have now been changed to be more relocatable (fewer |
|
568 |
mentions of the package name within files in the package). |
|
569 |
|
|
570 |
- The ``routesalchemy`` scaffold has been renamed ``alchemy``, replacing the |
|
571 |
older (traversal-based) ``alchemy`` scaffold (which has been retired). |
|
572 |
|
ce61d6
|
573 |
- The ``alchemy`` and ``starter`` scaffolds are Python 3 compatible. |
CM |
574 |
|
d83b39
|
575 |
- The ``starter`` scaffold now uses URL dispatch by default. |