view | history | commit | commitdiff
Michael Merickel
2018-10-19 aff6ee3c87a7a3f114e9b611b22c9dd41d79614a
commit | author | age
75a92c 1 What's New in Pyramid 1.8
MM 2 =========================
3
4 This article explains the new features in :app:`Pyramid` version 1.8 as
5 compared to its predecessor, :app:`Pyramid` 1.7. It also documents backwards
6 incompatibilities between the two versions and deprecations added to
7 :app:`Pyramid` 1.8, as well as software dependency changes and notable
8 documentation additions.
9
c22270 10 Major Feature Additions
MM 11 -----------------------
75a92c 12
MM 13 - Added :meth:`pyramid.config.Configurator.add_exception_view` and the
14   :func:`pyramid.view.exception_view_config` decorator. It is now possible
15   using these methods or via the new ``exception_only=True`` option to
16   :meth:`pyramid.config.Configurator.add_view` to add a view which will only
17   be matched when handling an exception. Previously, any exception views were
18   also registered for a traversal context that inherited from the exception
19   class which prevented any exception-only optimizations.
20   See https://github.com/Pylons/pyramid/pull/2660
21
22 - ``pserve --reload`` now uses the
3d3ee8 23   `hupper <http://docs.pylonsproject.org/projects/hupper/en/latest/>`_
75a92c 24   library to monitor file changes. This comes with many improvements:
MM 25
26   - If the `watchdog <http://pythonhosted.org/watchdog/>`_ package is
27     installed then monitoring will be done using inotify instead of
28     cpu and disk-intensive polling.
29
30   - The monitor is now a separate process that will not crash and starts up
31     before any of your code.
32
33   - The monitor will not restart the process after a crash until a file is
34     saved.
35
36   - The monitor works on windows.
37
38   - You can now trigger a reload manually from a pyramid view or any other
39     code via ``hupper.get_reloader().trigger_reload()``. Kind of neat.
40
41   - You can trigger a reload by issuing a ``SIGHUP`` to the monitor process.
42
43   See https://github.com/Pylons/pyramid/pull/2805
44
c22270 45 Minor Feature Additions
MM 46 -----------------------
47
48 - Python 3.6 compatibility.
49   https://github.com/Pylons/pyramid/issues/2835
50
51 - The ``_get_credentials`` private method of
52   :class:`pyramid.authentication.BasicAuthAuthenticationPolicy`
53   has been extracted into standalone function
54   :func:`pyramid.authentication.extract_http_basic_credentials`, this function
55   extracts HTTP Basic credentials from a ``request`` object, and returns them
56   as a named tuple. See https://github.com/Pylons/pyramid/pull/2662
57
58 - Pyramid 1.4 silently dropped a feature of the configurator that has been
59   restored. It's again possible for action discriminators to conflict across
60   different action orders.
61   See https://github.com/Pylons/pyramid/pull/2757
62
63 - :func:`pyramid.paster.bootstrap` and its sibling
64   :func:`pyramid.scripting.prepare` can now be used as context managers to
65   automatically invoke the ``closer`` and pop threadlocals off of the stack
66   to prevent memory leaks. See https://github.com/Pylons/pyramid/pull/2760
67
68 - Added the ``exception_only`` boolean to
69   :class:`pyramid.interfaces.IViewDeriverInfo` which can be used by view
70   derivers to determine if they are wrapping a view which only handles
71   exceptions. This means that it is no longer necessary to perform request-time
72   checks for ``request.exception`` to determine if the view is handling an
73   exception - the pipeline can be optimized at config-time.
74   See https://github.com/Pylons/pyramid/pull/2660
75
e82f3d 76 - ``pcreate`` learned about ``--package-name`` to allow you to create a new
MM 77   project in an existing folder with a different package name than the project
78   name. See https://github.com/Pylons/pyramid/pull/2783
79
c22270 80 - ``pserve`` should now work with ``gevent`` and other workers that need
MM 81   to monkeypatch the process, assuming the server and / or the app do so
82   as soon as possible before importing the rest of pyramid.
83   See https://github.com/Pylons/pyramid/pull/2797
84
85 - Pyramid no longer copies the settings object passed to the
86   ``pyramid.config.Configurator(settings=)``. The original ``dict`` is kept.
87   See https://github.com/Pylons/pyramid/pull/2823
88
89 - The csrf trusted origins setting may now be a whitespace-separated list of
90   domains. Previously only a python list was allowed. Also, it can now be set
91   using the ``PYRAMID_CSRF_TRUSTED_ORIGINS`` environment variable similar to
92   other settings. See https://github.com/Pylons/pyramid/pull/2823
93
75a92c 94 - A new ``[pserve]`` section is supported in your config files with a
MM 95   ``watch_files`` key that can configure ``pserve --reload`` to monitor custom
96   file paths. See https://github.com/Pylons/pyramid/pull/2827
97
98 - Allow streaming responses to be made from subclasses of
99   :class:`pyramid.httpexceptions.HTTPException`. Previously the response would
100   be unrolled while testing for a body, making it impossible to stream
101   a response.
102   See https://github.com/Pylons/pyramid/pull/2863
103
104 - Update starter, alchemy and zodb scaffolds to support IPv6 by using the
105   new ``listen`` directives in waitress.
106   See https://github.com/Pylons/pyramid/pull/2853
107
108 - All p* scripts now use argparse instead of optparse. This improves their
109   ``--help`` output as well as enabling nicer documentation of their options.
110   See https://github.com/Pylons/pyramid/pull/2864
111
1eaf3d 112 - Added an ``override`` option to
67d091 113   :meth:`pyramid.config.Configurator.add_translation_dirs` to allow
bf700d 114   later calls to place translation directories at a higher priority then
MM 115   earlier calls. See https://github.com/Pylons/pyramid/pull/2902
116
66585f 117 - Added a new ``callback`` option to
MM 118   :meth:`pyramid.config.Configurator.set_default_csrf_options`` which
119   can be used to determine per-request whether CSRF checking should be enabled
120   to allow for a mix authentication methods. Only cookie-based methods
121   generally require CSRF checking.
122   See https://github.com/Pylons/pyramid/pull/2778
123
c22270 124 Backwards Incompatibilities
MM 125 ---------------------------
126
127 - Following the Pyramid deprecation period (1.6 -> 1.8),
128   daemon support for pserve has been removed. This includes removing the
129   daemon commands (start, stop, restart, status) as well as the following
130   arguments: ``--daemon``, ``--pid-file``, ``--log-file``,
131   ``--monitor-restart``, ``--status``, ``--user``, ``--group``,
132   ``--stop-daemon``
133
134   To run your server as a daemon you should use a process manager instead of
135   pserve.
136
137   See https://github.com/Pylons/pyramid/pull/2615
138
139 - Change static view to avoid setting the ``Content-Encoding`` response header
140   to an encoding guessed using Python's ``mimetypes`` module. This was causing
141   clients to decode the content of gzipped files when downloading them. The
142   client would end up with a ``foo.txt.gz`` file on disk that was already
143   decoded, thus should really be ``foo.txt``. Also, the ``Content-Encoding``
144   should only have been used if the client itself broadcast support for the
145   encoding via ``Accept-Encoding`` request headers.
146   See https://github.com/Pylons/pyramid/pull/2810
147
148 - ``pcreate`` is now interactive by default. You will be prompted if a file
149   already exists with different content. Previously if there were similar
150   files it would silently skip them unless you specified ``--interactive``
151   or ``--overwrite``.
152   See https://github.com/Pylons/pyramid/pull/2775
153
154 - Support for the ``IContextURL`` interface that was deprecated in Pyramid 1.3
155   has been removed.  See https://github.com/Pylons/pyramid/pull/2822
156
157 - Settings are no longer accessible as attributes on the settings object
158   (e.g. ``request.registry.settings.foo``). This was deprecated in Pyramid 1.2.
159   See https://github.com/Pylons/pyramid/pull/2823
160
161 - Removed undocumented argument ``cachebust_match`` from
162   ``pyramid.static.static_view``. This argument was shipped accidentally
163   in Pyramid 1.6. See https://github.com/Pylons/pyramid/pull/2681
164
75a92c 165 Deprecations
MM 166 ------------
167
8553bd 168 - The ``pcreate`` script and the core scaffolds (``starter``, ``alchemy`` and
MM 169   ``zodb``) have been deprecated.
170
171   They have been replaced with the decision to embrace the popular
172   `cookiecutter <https://cookiecutter.readthedocs.io/en/latest/>`_ project
173   as a best-of-breed project templating solution.
174
175   ``pcreate`` was originally introduced when very few alternatives existed
176   that supported Python 3. Fortunately the situation has improved and
177   with possible tooling support for cookiecutters being discussed by major
178   IDEs, and the simplicity of the jinja2 syntax, it is exciting to embrace
179   the project moving forward!
75a92c 180
6e037c 181   All of Pyramid's official scaffolds as well as the tutorials have been
MM 182   ported to cookiecutters:
75a92c 183
6e037c 184   - `pyramid-cookiecutter-starter
MM 185     <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
186
187   - `pyramid-cookiecutter-alchemy
188     <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_
189
190   - `pyramid-cookiecutter-zodb
191     <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_
192
193   See https://github.com/Pylons/pyramid/pull/2780
75a92c 194
MM 195 Documentation Enhancements
196 --------------------------
197
85b301 198 - Update Typographical Conventions.
75a92c 199   https://github.com/Pylons/pyramid/pull/2838
MM 200
201 - Add `pyramid_nacl_session
202   <http://docs.pylonsproject.org/projects/pyramid-nacl-session/en/latest/>`_
203   to session factories. See https://github.com/Pylons/pyramid/issues/2791
204
205 - Update HACKING.txt from stale branch that was never merged to master.
206   See https://github.com/Pylons/pyramid/pull/2782
207
208 - Updated Windows installation instructions and related bits.
209   See https://github.com/Pylons/pyramid/issues/2661
210
211 - Fix an inconsistency in the documentation between view predicates and
212   route predicates and highlight the differences in their APIs.
213   See https://github.com/Pylons/pyramid/pull/2764
214
215 - Clarify a possible misuse of the ``headers`` kwarg to subclasses of
216   :class:`pyramid.httpexceptions.HTTPException` in which more appropriate
217   kwargs from the parent class :class:`pyramid.response.Response` should be
218   used instead. See https://github.com/Pylons/pyramid/pull/2750
6e037c 219
MM 220 - The SQLAlchemy + URL Dispatch + Jinja2 (``wiki2``) and
221   ZODB + Traversal + Chameleon (``wiki``) tutorials have been updated to
222   utilize the new cookiecutters and drop support for the ``pcreate``
223   scaffolds.
224
225   See https://github.com/Pylons/pyramid/pull/2881 and
226   https://github.com/Pylons/pyramid/pull/2883.
fca6c1 227
SP 228 - Quick Tour, Quick Tutorial, and most files throughout the documentation have
229   been updated to use cookiecutters instead of pcreate and scaffolds.
230   See https://github.com/Pylons/pyramid/pull/2888 and
231   https://github.com/Pylons/pyramid/pull/2889
776666 232
MM 233 - Updated the ``mod_wsgi`` tutorial to use cookiecutters and Apache 2.4+.
234   See https://github.com/Pylons/pyramid/pull/2901