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