1.. _upgrading_chapter: 2 3Upgrading Pyramid 4================= 5 6When a new version of Pyramid is released, it will sometimes deprecate a 7feature or remove a feature that was deprecated in an older release. When 8features are removed from Pyramid, applications that depend on those features 9will begin to break. This chapter explains how to ensure your Pyramid 10applications keep working when you upgrade the Pyramid version you're using. 11 12.. sidebar:: About Release Numbering 13 14 Conventionally, application version numbering in Python is described as 15 ``major.minor.micro``. If your Pyramid version is "1.2.3", it means you're 16 running a version of Pyramid with the major version "1", the minor version 17 "2" and the micro version "3". A "major" release is one that increments the 18 first-dot number; 2.X.X might follow 1.X.X. A "minor" release is one that 19 increments the second-dot number; 1.3.X might follow 1.2.X. A "micro" 20 release is one that increments the third-dot number; 1.2.3 might follow 21 1.2.2. In general, micro releases are "bugfix-only", and contain no new 22 features, minor releases contain new features but are largely backwards 23 compatible with older versions, and a major release indicates a large set of 24 backwards incompatibilities. 25 26The Pyramid core team is conservative when it comes to removing features. We 27don't remove features unnecessarily, but we're human and we make mistakes which 28cause some features to be evolutionary dead ends. Though we are willing to 29support dead-end features for some amount of time, some eventually have to be 30removed when the cost of supporting them outweighs the benefit of keeping them 31around, because each feature in Pyramid represents a certain documentation and 32maintenance burden. 33 34Deprecation and removal policy 35------------------------------ 36 37When a feature is scheduled for removal from Pyramid or any of its official 38add-ons, the core development team takes these steps: 39 40- Using the feature will begin to generate a `DeprecationWarning`, indicating 41 the version in which the feature became deprecated. 42 43- A note is added to the documentation indicating that the feature is 44 deprecated. 45 46- A note is added to the :ref:`changelog` about the deprecation. 47 48When a deprecated feature is eventually removed: 49 50- The feature is removed. 51 52- A note is added to the :ref:`changelog` about the removal. 53 54Features are never removed in *micro* releases. They are only removed in minor 55and major releases. Deprecated features are kept around for at least *three* 56minor releases from the time the feature became deprecated. Therefore, if a 57feature is added in Pyramid 1.0, but it's deprecated in Pyramid 1.1, it will be 58kept around through all 1.1.X releases, all 1.2.X releases and all 1.3.X 59releases. It will finally be removed in the first 1.4.X release. 60 61Sometimes features are "docs-deprecated" instead of formally deprecated. This 62means that the feature will be kept around indefinitely, but it will be removed 63from the documentation or a note will be added to the documentation telling 64folks to use some other newer feature. This happens when the cost of keeping 65an old feature around is very minimal and the support and documentation burden 66is very low. For example, we might rename a function that is an API without 67changing the arguments it accepts. In this case, we'll often rename the 68function, and change the docs to point at the new function name, but leave 69around a backwards compatibility alias to the old function name so older code 70doesn't break. 71 72"Docs deprecated" features tend to work "forever", meaning that they won't be 73removed, and they'll never generate a deprecation warning. However, such 74changes are noted in the :ref:`changelog`, so it's possible to know that you 75should change older spellings to newer ones to ensure that people reading your 76code can find the APIs you're using in the Pyramid docs. 77 78 79Python support policy 80~~~~~~~~~~~~~~~~~~~~~ 81 82At the time of a Pyramid version release, each supports all versions of Python 83through the end of their lifespans. The end-of-life for a given version of 84Python is when security updates are no longer released. 85 86- `Python 3.2 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ 87 ends February 2016. 88- `Python 3.3 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ 89 ends September 2017. 90- `Python 3.4 Lifespan <https://www.python.org/dev/peps/pep-0429/>`_ TBD. 91- `Python 3.5 Lifespan <https://www.python.org/dev/peps/pep-0478/>`_ TBD. 92- `Python 3.6 Lifespan <https://www.python.org/dev/peps/pep-0494/#id4>`_ 93 December 2021. 94 95To determine the Python support for a specific release of Pyramid, view its 96``tox.ini`` file at the root of the repository's version. 97 98 99Consulting the change history 100----------------------------- 101 102Your first line of defense against application failures caused by upgrading to 103a newer Pyramid release is always to read the :ref:`changelog` to find the 104deprecations and removals for each release between the release you're currently 105running and the one to which you wish to upgrade. The change history notes 106every deprecation within a ``Deprecation`` section and every removal within a 107``Backwards Incompatibilies`` section for each release. 108 109The change history often contains instructions for changing your code to avoid 110deprecation warnings and how to change docs-deprecated spellings to newer ones. 111You can follow along with each deprecation explanation in the change history, 112simply doing a grep or other code search to your application, using the change 113log examples to remediate each potential problem. 114 115.. _testing_under_new_release: 116 117Testing your application under a new Pyramid release 118---------------------------------------------------- 119 120Once you've upgraded your application to a new Pyramid release and you've 121remediated as much as possible by using the change history notes, you'll want 122to run your application's tests (see :ref:`running_tests`) in such a way that 123you can see DeprecationWarnings printed to the console when the tests run. 124 125.. code-block:: bash 126 127 $ python -Wd setup.py test -q 128 129The ``-Wd`` argument tells Python to print deprecation warnings to the console. 130See `the Python -W flag documentation 131<https://docs.python.org/2/using/cmdline.html#cmdoption-W>`_ for more 132information. 133 134As your tests run, deprecation warnings will be printed to the console 135explaining the deprecation and providing instructions about how to prevent the 136deprecation warning from being issued. For example: 137 138.. code-block:: bash 139 140 $ python -Wd setup.py test -q 141 # .. elided ... 142 running build_ext 143 /home/chrism/projects/pyramid/env27/myproj/myproj/views.py:3: 144 DeprecationWarning: static: The "pyramid.view.static" class is deprecated 145 as of Pyramid 1.1; use the "pyramid.static.static_view" class instead with 146 the "use_subpath" argument set to True. 147 from pyramid.view import static 148 . 149 ---------------------------------------------------------------------- 150 Ran 1 test in 0.014s 151 152 OK 153 154In the above case, it's line #3 in the ``myproj.views`` module (``from 155pyramid.view import static``) that is causing the problem: 156 157.. code-block:: python 158 :linenos: 159 160 from pyramid.view import view_config 161 162 from pyramid.view import static 163 myview = static('static', 'static') 164 165The deprecation warning tells me how to fix it, so I can change the code to do 166things the newer way: 167 168.. code-block:: python 169 :linenos: 170 171 from pyramid.view import view_config 172 173 from pyramid.static import static_view 174 myview = static_view('static', 'static', use_subpath=True) 175 176When I run the tests again, the deprecation warning is no longer printed to my 177console: 178 179.. code-block:: bash 180 181 $ python -Wd setup.py test -q 182 # .. elided ... 183 running build_ext 184 . 185 ---------------------------------------------------------------------- 186 Ran 1 test in 0.014s 187 188 OK 189 190 191My application doesn't have any tests or has few tests 192------------------------------------------------------ 193 194If your application has no tests, or has only moderate test coverage, running 195tests won't tell you very much, because the Pyramid codepaths that generate 196deprecation warnings won't be executed. 197 198In this circumstance, you can start your application interactively under a 199server run with the ``PYTHONWARNINGS`` environment variable set to ``default``. 200On UNIX, you can do that via: 201 202.. code-block:: bash 203 204 $ PYTHONWARNINGS=default $VENV/bin/pserve development.ini 205 206On Windows, you need to issue two commands: 207 208.. code-block:: doscon 209 210 c:\> set PYTHONWARNINGS=default 211 c:\> Scripts/pserve.exe development.ini 212 213At this point, it's ensured that deprecation warnings will be printed to the 214console whenever a codepath is hit that generates one. You can then click 215around in your application interactively to try to generate them, and remediate 216as explained in :ref:`testing_under_new_release`. 217 218See `the PYTHONWARNINGS environment variable documentation 219<https://docs.python.org/2/using/cmdline.html#envvar-PYTHONWARNINGS>`_ or `the 220Python -W flag documentation 221<https://docs.python.org/2/using/cmdline.html#cmdoption-W>`_ for more 222information. 223 224Upgrading to the very latest Pyramid release 225-------------------------------------------- 226 227When you upgrade your application to the most recent Pyramid release, 228it's advisable to upgrade step-wise through each most recent minor release, 229beginning with the one that you know your application currently runs under, 230and ending on the most recent release. For example, if your application is 231running in production on Pyramid 1.2.1, and the most recent Pyramid 1.3 232release is Pyramid 1.3.3, and the most recent Pyramid release is 1.4.4, it's 233advisable to do this: 234 235- Upgrade your environment to the most recent 1.2 release. For example, the 236 most recent 1.2 release might be 1.2.3, so upgrade to it. Then run your 237 application's tests under 1.2.3 as described in 238 :ref:`testing_under_new_release`. Note any deprecation warnings and 239 remediate. 240 241- Upgrade to the most recent 1.3 release, 1.3.3. Run your application's tests, 242 note any deprecation warnings, and remediate. 243 244- Upgrade to 1.4.4. Run your application's tests, note any deprecation 245 warnings, and remediate. 246 247If you skip testing your application under each minor release (for example if 248you upgrade directly from 1.2.1 to 1.4.4), you might miss a deprecation warning 249and waste more time trying to figure out an error caused by a feature removal 250than it would take to upgrade stepwise through each minor release. 251