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