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