| commit | author | age | ||
| a46b07 | 1 | What's New in Pyramid 1.6 |
| bfe000 | 2 | ========================= |
| CM | 3 | |
| 4 | This article explains the new features in :app:`Pyramid` version 1.6 as | |
| a46b07 | 5 | compared to its predecessor, :app:`Pyramid` 1.5. It also documents backwards |
| bfe000 | 6 | incompatibilities between the two versions and deprecations added to |
| CM | 7 | :app:`Pyramid` 1.6, as well as software dependency changes and notable |
| 8 | documentation additions. | |
| 9 | ||
| 50d88b | 10 | Bug Fix Releases |
| MM | 11 | ---------------- |
| 12 | Pyramid 1.6 was released on 2016-01-03. | |
| 13 | ||
| 14 | The following bug fix releases were made since then. Bug fix releases also | |
| 15 | include documentation improvements and other minor feature changes. | |
| 16 | ||
| 17 | - :ref:`changes_1.6.1` | |
| ade954 | 18 | - :ref:`changes_1.6.2` |
| 73dd39 | 19 | - :ref:`changes_1.6.3` |
| 37ff1a | 20 | - :ref:`changes_1.6.4` |
| a46b07 | 21 | |
| bfe000 | 22 | Backwards Incompatibilities |
| CM | 23 | --------------------------- |
| 24 | ||
| a46b07 | 25 | - IPython and BPython support have been removed from pshell in the core. To |
| SP | 26 | continue using them on Pyramid 1.6+, you must install the binding packages |
| 27 | explicitly. One way to do this is by adding ``pyramid_ipython`` (or | |
| 28 | ``pyramid_bpython``) to the ``install_requires`` section of your package's | |
| 29 | ``setup.py`` file, then re-running ``setup.py develop``:: | |
| 850f3f | 30 | |
| MM | 31 | setup( |
| 32 | #... | |
| 33 | install_requires=[ | |
| 34 | 'pyramid_ipython', # new dependency | |
| 35 | 'pyramid', | |
| 36 | #... | |
| 37 | ], | |
| 38 | ) | |
| 39 | ||
| bfe000 | 40 | - ``request.response`` will no longer be mutated when using the |
| a46b07 | 41 | :func:`~pyramid.renderers.render_to_response` API. It is now necessary to |
| SP | 42 | pass in a ``response=`` argument to |
| 43 | :func:`~pyramid.renderers.render_to_response` if you wish to supply the | |
| 44 | renderer with a custom response object. If you do not pass one, then a | |
| 45 | response object will be created using the current response factory. Almost | |
| 46 | all renderers mutate the ``request.response`` response object (for example, | |
| 47 | the JSON renderer sets ``request.response.content_type`` to | |
| 48 | ``application/json``). However, when invoking ``render_to_response``, it is | |
| 49 | not expected that the response object being returned would be the same one | |
| 50 | used later in the request. The response object returned from | |
| 51 | ``render_to_response`` is now explicitly different from ``request.response``. | |
| 52 | This does not change the API of a renderer. See | |
| bfe000 | 53 | https://github.com/Pylons/pyramid/pull/1563 |
| CM | 54 | |
| acc007 | 55 | - In an effort to combat a common issue it is now a |
| MM | 56 | :class:`~pyramid.exceptions.ConfigurationError` to register a view |
| 57 | callable that is actually an unbound method when using the default view | |
| 58 | mapper. As unbound methods do not exist in PY3+ possible errors are detected | |
| 59 | by checking if the first parameter is named ``self``. For example, | |
| 60 | `config.add_view(ViewClass.some_method, ...)` should actually be | |
| 61 | `config.add_view(ViewClass, attr='some_method)'`. This was always an issue | |
| 62 | in Pyramid on PY2 but the backward incompatibility is on PY3+ where you may | |
| 63 | not use a function with the first parameter named ``self``. In this case | |
| 64 | it looks too much like a common error and the exception will be raised. | |
| 65 | See https://github.com/Pylons/pyramid/pull/1498 | |
| 66 | ||
| bfe000 | 67 | |
| CM | 68 | Feature Additions |
| 69 | ----------------- | |
| 70 | ||
| a46b07 | 71 | - Python 3.5 and pypy3 compatibility. |
| SP | 72 | |
| 73 | - ``pserve --reload`` will no longer crash on syntax errors. See | |
| 74 | https://github.com/Pylons/pyramid/pull/2044 | |
| 850f3f | 75 | |
| MM | 76 | - Cache busting for static resources has been added and is available via a new |
| a46b07 | 77 | :meth:`pyramid.config.Configurator.add_cache_buster` API. Core APIs are |
| SP | 78 | shipped for both cache busting via query strings and via asset manifests for |
| 79 | integrating into custom asset pipelines. See | |
| 80 | https://github.com/Pylons/pyramid/pull/1380 and | |
| 850f3f | 81 | https://github.com/Pylons/pyramid/pull/1583 and |
| MM | 82 | https://github.com/Pylons/pyramid/pull/2171 |
| bfe000 | 83 | |
| CM | 84 | - Assets can now be overidden by an absolute path on the filesystem when using |
| 85 | the :meth:`~pyramid.config.Configurator.override_asset` API. This makes it | |
| 86 | possible to fully support serving up static content from a mutable directory | |
| 87 | while still being able to use the :meth:`~pyramid.request.Request.static_url` | |
| 88 | API and :meth:`~pyramid.config.Configurator.add_static_view`. Previously it | |
| 89 | was not possible to use :meth:`~pyramid.config.Configurator.add_static_view` | |
| 90 | with an absolute path **and** generate urls to the content. This change | |
| 91 | replaces the call, ``config.add_static_view('/abs/path', 'static')``, with | |
| 92 | ``config.add_static_view('myapp:static', 'static')`` and | |
| 93 | ``config.override_asset(to_override='myapp:static/', | |
| 94 | override_with='/abs/path/')``. The ``myapp:static`` asset spec is completely | |
| a46b07 | 95 | made up and does not need to exist—it is used for generating URLs via |
| SP | 96 | ``request.static_url('myapp:static/foo.png')``. See |
| bfe000 | 97 | https://github.com/Pylons/pyramid/issues/1252 |
| CM | 98 | |
| 99 | - Added :meth:`~pyramid.config.Configurator.set_response_factory` and the | |
| 100 | ``response_factory`` keyword argument to the constructor of | |
| 101 | :class:`~pyramid.config.Configurator` for defining a factory that will return | |
| a46b07 | 102 | a custom ``Response`` class. See https://github.com/Pylons/pyramid/pull/1499 |
| bfe000 | 103 | |
| a46b07 | 104 | - Added :attr:`pyramid.config.Configurator.root_package` attribute and init |
| SP | 105 | parameter to assist with includible packages that wish to resolve resources |
| 106 | relative to the package in which the configurator was created. This is | |
| 107 | especially useful for add-ons that need to load asset specs from settings, in | |
| 108 | which case it may be natural for a developer to define imports or assets | |
| 109 | relative to the top-level package. See | |
| 110 | https://github.com/Pylons/pyramid/pull/1337 | |
| bfe000 | 111 | |
| 41843e | 112 | - Overall improvements for the ``proutes`` command. Added ``--format`` and |
| bfe000 | 113 | ``--glob`` arguments to the command, introduced the ``method`` |
| CM | 114 | column for displaying available request methods, and improved the ``view`` |
| a46b07 | 115 | output by showing the module instead of just ``__repr__``. See |
| SP | 116 | https://github.com/Pylons/pyramid/pull/1488 |
| bfe000 | 117 | |
| CM | 118 | - ``pserve`` can now take a ``-b`` or ``--browser`` option to open the server |
| 119 | URL in a web browser. See https://github.com/Pylons/pyramid/pull/1533 | |
| 120 | ||
| a46b07 | 121 | - Support keyword-only arguments and function annotations in views in Python 3. |
| SP | 122 | See https://github.com/Pylons/pyramid/pull/1556 |
| bfe000 | 123 | |
| CM | 124 | - The ``append_slash`` argument of |
| 125 | :meth:`~pyramid.config.Configurator.add_notfound_view()` will now accept | |
| 126 | anything that implements the :class:`~pyramid.interfaces.IResponse` interface | |
| 127 | and will use that as the response class instead of the default | |
| a46b07 | 128 | :class:`~pyramid.httpexceptions.HTTPFound`. See |
| bfe000 | 129 | https://github.com/Pylons/pyramid/pull/1610 |
| CM | 130 | |
| 131 | - The :class:`~pyramid.config.Configurator` has grown the ability to allow | |
| a46b07 | 132 | actions to call other actions during a commit cycle. This enables much more |
| bfe000 | 133 | logic to be placed into actions, such as the ability to invoke other actions |
| CM | 134 | or group them for improved conflict detection. We have also exposed and |
| a46b07 | 135 | documented the configuration phases that Pyramid uses in order to further |
| SP | 136 | assist in building conforming add-ons. See |
| 137 | https://github.com/Pylons/pyramid/pull/1513 | |
| bfe000 | 138 | |
| CM | 139 | - Allow an iterator to be returned from a renderer. Previously it was only |
| a46b07 | 140 | possible to return bytes or unicode. See |
| SP | 141 | https://github.com/Pylons/pyramid/pull/1417 |
| bfe000 | 142 | |
| CM | 143 | - Improve robustness to timing attacks in the |
| 144 | :class:`~pyramid.authentication.AuthTktCookieHelper` and the | |
| 145 | :class:`~pyramid.session.SignedCookieSessionFactory` classes by using the | |
| a46b07 | 146 | stdlib's ``hmac.compare_digest`` if it is available (such as Python 2.7.7+ |
| SP | 147 | and 3.3+). See https://github.com/Pylons/pyramid/pull/1457 |
| bfe000 | 148 | |
| a46b07 | 149 | - Improve the readability of the ``pcreate`` shell script output. See |
| SP | 150 | https://github.com/Pylons/pyramid/pull/1453 |
| bfe000 | 151 | |
| a46b07 | 152 | - Make it simple to define ``notfound`` and ``forbidden`` views that wish to |
| SP | 153 | use the default exception-response view, but with altered predicates and |
| 154 | other configuration options. The ``view`` argument is now optional in | |
| bfe000 | 155 | :meth:`~pyramid.config.Configurator.add_notfound_view` and |
| CM | 156 | :meth:`~pyramid.config.Configurator.add_forbidden_view` See |
| 157 | https://github.com/Pylons/pyramid/issues/494 | |
| 158 | ||
| 159 | - The ``pshell`` script will now load a ``PYTHONSTARTUP`` file if one is | |
| a46b07 | 160 | defined in the environment prior to launching the interpreter. See |
| SP | 161 | https://github.com/Pylons/pyramid/pull/1448 |
| bfe000 | 162 | |
| a46b07 | 163 | - Add new HTTP exception objects for status codes ``428 Precondition |
| SP | 164 | Required``, ``429 Too Many Requests`` and ``431 Request Header Fields Too |
| 165 | Large`` in ``pyramid.httpexceptions``. See | |
| 166 | https://github.com/Pylons/pyramid/pull/1372/files | |
| bfe000 | 167 | |
| CM | 168 | - ``pcreate`` when run without a scaffold argument will now print information |
| a46b07 | 169 | on the missing flag, as well as a list of available scaffolds. See |
| bfe000 | 170 | https://github.com/Pylons/pyramid/pull/1566 and |
| CM | 171 | https://github.com/Pylons/pyramid/issues/1297 |
| 172 | ||
| 850f3f | 173 | - ``pcreate`` will now ask for confirmation if invoked with an argument for a |
| MM | 174 | project name that already exists or is importable in the current environment. |
| 175 | See https://github.com/Pylons/pyramid/issues/1357 and | |
| 176 | https://github.com/Pylons/pyramid/pull/1837 | |
| 177 | ||
| bfe000 | 178 | - Add :func:`pyramid.request.apply_request_extensions` function which can be |
| CM | 179 | used in testing to apply any request extensions configured via |
| 180 | ``config.add_request_method``. Previously it was only possible to test the | |
| a46b07 | 181 | extensions by going through Pyramid's router. See |
| bfe000 | 182 | https://github.com/Pylons/pyramid/pull/1581 |
| CM | 183 | |
| 184 | - Make it possible to subclass ``pyramid.request.Request`` and also use | |
| a46b07 | 185 | ``pyramid.request.Request.add_request.method``. See |
| bfe000 | 186 | https://github.com/Pylons/pyramid/issues/1529 |
| CM | 187 | |
| a46b07 | 188 | - Additional shells for ``pshell`` can now be registered as entry points. See |
| 850f3f | 189 | https://github.com/Pylons/pyramid/pull/1891 and |
| MM | 190 | https://github.com/Pylons/pyramid/pull/2012 |
| 191 | ||
| 192 | - The variables injected into ``pshell`` are now displayed with their | |
| a46b07 | 193 | docstrings instead of the default ``str(obj)`` when possible. See |
| SP | 194 | https://github.com/Pylons/pyramid/pull/1929 |
| 195 | ||
| 850f3f | 196 | |
| bfe000 | 197 | Deprecations |
| CM | 198 | ------------ |
| 850f3f | 199 | |
| a46b07 | 200 | - The ``pserve`` command's daemonization features, as well as |
| SP | 201 | ``--monitor-restart``, have been deprecated. This includes the |
| 202 | ``[start,stop,restart,status]`` subcommands, as well as the ``--daemon``, | |
| 5c704e | 203 | ``--stop-daemon``, ``--pid-file``, ``--status``, ``--user``, ``--group``, and |
| BJR | 204 | ``--log-file`` flags. See https://github.com/Pylons/pyramid/pull/2120 and |
| a46b07 | 205 | https://github.com/Pylons/pyramid/pull/2189 and |
| 5c704e | 206 | https://github.com/Pylons/pyramid/pull/1641 and |
| BJR | 207 | https://github.com/Pylons/pyramid/pull/2329 |
| 850f3f | 208 | |
| a46b07 | 209 | Please use a real process manager in the future instead of relying on |
| SP | 210 | ``pserve`` to daemonize itself. Many options exist, including your operating |
| 211 | system's services, such as Systemd or Upstart, as well as Python-based | |
| 850f3f | 212 | solutions like Circus and Supervisor. |
| MM | 213 | |
| a46b07 | 214 | See https://github.com/Pylons/pyramid/pull/1641 and |
| SP | 215 | https://github.com/Pylons/pyramid/pull/2120 |
| bfe000 | 216 | |
| CM | 217 | - The ``principal`` argument to :func:`pyramid.security.remember` was renamed |
| a46b07 | 218 | to ``userid``. Using ``principal`` as the argument name still works and will |
| bfe000 | 219 | continue to work for the next few releases, but a deprecation warning is |
| CM | 220 | printed. |
| 221 | ||
| 222 | ||
| 223 | Scaffolding Enhancements | |
| 224 | ------------------------ | |
| 225 | ||
| 226 | - Added line numbers to the log formatters in the scaffolds to assist with | |
| 227 | debugging. See https://github.com/Pylons/pyramid/pull/1326 | |
| 228 | ||
| a46b07 | 229 | - Updated scaffold generating machinery to return the version of :app:`Pyramid` |
| SP | 230 | and its documentation for use in scaffolds. Updated ``starter``, ``alchemy`` |
| 231 | and ``zodb`` templates to have links to correctly versioned documentation, | |
| 232 | and to reflect which :app:`Pyramid` was used to generate the scaffold. | |
| 978135 | 233 | |
| a46b07 | 234 | - Removed non-ASCII copyright symbol from templates, as this was causing the |
| SP | 235 | scaffolds to fail for project generation. |
| 236 | ||
| 978135 | 237 | |
| CM | 238 | Documentation Enhancements |
| 239 | -------------------------- | |
| 240 | ||
| a46b07 | 241 | - Removed logging configuration from Quick Tutorial ``ini`` files, except for |
| SP | 242 | scaffolding- and logging-related chapters, to avoid needing to explain it too |
| 978135 | 243 | early. |
| CM | 244 | |
| a46b07 | 245 | - Improve and clarify the documentation on what :app:`Pyramid` defines as a |
| SP | 246 | ``principal`` and a ``userid`` in its security APIs. See |
| 247 | https://github.com/Pylons/pyramid/pull/1399 | |
| 850f3f | 248 | |
| MM | 249 | - Moved the documentation for ``accept`` on |
| 250 | :meth:`pyramid.config.Configurator.add_view` to no longer be part of the | |
| 251 | predicate list. See https://github.com/Pylons/pyramid/issues/1391 for a bug | |
| 252 | report stating ``not_`` was failing on ``accept``. Discussion with @mcdonc | |
| 253 | led to the conclusion that it should not be documented as a predicate. | |
| a46b07 | 254 | See https://github.com/Pylons/pyramid/pull/1487 for this PR. |
| 850f3f | 255 | |
| MM | 256 | - Clarify a previously-implied detail of the ``ISession.invalidate`` API |
| 257 | documentation. | |
| a46b07 | 258 | |
| SP | 259 | - Add documentation of command line programs (``p*`` scripts). See |
| 260 | https://github.com/Pylons/pyramid/pull/2191 | |
