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