Update v2 migration guide to 2.4.0 (#3621)

* Update v2 migration guide to 2.4.0

* Fix version number deprecation

* Update ssl_version string in tests

* Adjust more test deprecation matches

* Bump 2.5.0 removals to 2.6.0

Author: pquentin

docs/v2-migration-guide.rst

@@ -1,9 +1,9 @@
 v2.0 Migration Guide
 ====================
 
-**urllib3 v2.0 is now available!** Read below for how to get started and what is contained in the new major release.
+**urllib3 2.x is now available!** Read below for how to get started and what is contained in the new major release.
 
-**🚀 Migrating from 1.x to 2.0**
+**🚀 Migrating from 1.x to 2.x**
 --------------------------------
 
 We're maintaining **functional API compatibility for most users** to make the
@@ -13,44 +13,25 @@ So unless you're in a specific situation you should notice no changes! 🎉
 
 .. note::
 
-  If you have difficulty migrating to v2.0 or following this guide
+  If you have difficulty migrating to 2.x or following this guide
   you can `open an issue on GitHub <https://github.com/urllib3/urllib3/issues>`_
   or reach out in `our community Discord channel <https://discord.gg/urllib3>`_.
 
 
-Timeline for deprecations and breaking changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The 2.x initial release schedule will look like this:
-
-* urllib3 ``v2.0.0-alpha1`` will be released in November 2022. This release
-  contains **minor breaking changes and deprecation warnings for other breaking changes**.
-  There may be other pre-releases to address fixes before v2.0.0 is released.
-* urllib3 ``v2.0.0`` will be released in early 2023 after some initial integration testing
-  against dependent packages and fixing of bug reports.
-* urllib3 ``v2.1.0`` will be released in the summer of 2023 with **all breaking changes
-  being warned about in v2.0.0**.
-
-.. warning::
-
-  Please take the ``DeprecationWarnings`` you receive when migrating from v1.x to v2.0 seriously
-  as they will become errors after 2.1.0 is released.
-
-
 What are the important changes?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Here's a short summary of which changes in urllib3 v2.0 are most important:
+Here's a short summary of which changes in urllib3 2.x are most important:
 
-- Python version must be **3.7 or later** (previously supported Python 2.7, 3.5, and 3.6).
+- Python version must be **3.9 or later** (previously supported Python 2.7, and 3.5 to 3.8).
 - Removed support for non-OpenSSL TLS libraries (like LibreSSL and wolfSSL).
 - Removed support for OpenSSL versions older than 1.1.1.
 - Removed support for Python implementations that aren't CPython or PyPy3 (previously supported Google App Engine, Jython).
 - Removed the ``urllib3.contrib.ntlmpool`` module.
-- Deprecated the ``urllib3.contrib.pyopenssl``, ``urllib3.contrib.securetransport`` modules, will be removed in v2.1.0.
-- Deprecated the ``urllib3[secure]`` extra, will be removed in v2.1.0.
-- Deprecated the ``HTTPResponse.getheaders()`` method in favor of ``HTTPResponse.headers``, will be removed in v2.1.0.
-- Deprecated the ``HTTPResponse.getheader(name, default)`` method in favor of ``HTTPResponse.headers.get(name, default)``, will be removed in v2.1.0.
+- Removed the ``urllib3.contrib.securetransport`` module.
+- Removed the ``urllib3[secure]`` extra.
+- Deprecated the ``HTTPResponse.getheaders()`` method in favor of ``HTTPResponse.headers``, will be removed in 2.6.0.
+- Deprecated the ``HTTPResponse.getheader(name, default)`` method in favor of ``HTTPResponse.headers.get(name, default)``, will be removed in 2.6.0.
 - Deprecated URLs without a scheme (ie 'https://') and will be raising an error in a future version of urllib3.
 - Changed the default minimum TLS version to TLS 1.2 (previously was TLS 1.0).
 - Changed the default request body encoding from 'ISO-8859-1' to 'UTF-8'.
@@ -60,129 +41,22 @@ Here's a short summary of which changes in urllib3 v2.0 are most important:
 For a full list of changes you can look at `the changelog <https://github.com/urllib3/urllib3/blob/main/CHANGES.rst>`_.
 
 
-Migrating as a package maintainer?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you're a maintainer of a package that uses urllib3 under the hood then this section is for you.
-You may have already seen an issue opened from someone on our team about the upcoming release.
-
-The primary goal for migrating to urllib3 v2.x should be to ensure your package supports **both urllib3 v1.26.x and v2.0 for some time**.
-This is to reduce the chance that diamond dependencies are introduced into your users' dependencies which will then cause issues
-with them upgrading to the latest version of **your package**.
-
-The first step to supporting urllib3 v2.0 is to make sure the version v2.x not being excluded by ``install_requires``. You should
-ensure your package allows for both urllib3 1.26.x and 2.0 to be used:
-
-.. code-block:: python
-
-  # setup.py (setuptools)
-  setup(
-    ...
-    install_requires=["urllib3>=1.26,<3"]
-  )
-
-  # pyproject.toml (hatch)
-  [project]
-  dependencies = [
-    "urllib3>=1.26,<3"
-  ]
-
-Next you should try installing urllib3 v2.0 locally and run your test suite.
-
-.. code-block:: bash
-
-  $ python -m pip install -U --pre 'urllib3>=2.0.0a1'
-
-
-Because there are many ``DeprecationWarnings`` you should ensure that you're
-able to see those warnings when running your test suite. To do so you can add
-the following to your test setup to ensure even ``DeprecationWarnings`` are
-output to the terminal:
-
-.. code-block:: bash
-
-  # Set PYTHONWARNING=default to show all warnings.
-  $ export PYTHONWARNINGS="default"
-
-  # Run your test suite and look for failures.
-  # Pytest automatically prints all warnings.
-  $ pytest tests/
-
-or you can opt-in within your Python code:
-
-.. code-block:: python
-
-  # You can change warning filters according to the filter rules:
-  # https://docs.python.org/3/library/warnings.html#warning-filter
-  import warnings
-  warnings.filterwarnings("default", category=DeprecationWarning)
-
-Any failures or deprecation warnings you receive should be fixed as urllib3 v2.1.0 will remove all
-deprecated features. Many deprecation warnings will make suggestions about what to do to avoid the deprecated feature.
-
-Warnings will look something like this:
-
-.. code-block:: bash
-
-  DeprecationWarning: 'ssl_version' option is deprecated and will be removed
-  in urllib3 v2.1.0. Instead use 'ssl_minimum_version'
-
-Continue removing deprecation warnings until there are no more. After this you can publish a new release of your package
-that supports both urllib3 v1.26.x and v2.x.
-
-.. note::
-
-  If you're not able to support both 1.26.x and v2.0 of urllib3 at the same time with your package please
-  `open an issue on GitHub <https://github.com/urllib3/urllib3/issues>`_ or reach out in
-  `our community Discord channel <https://discord.gg/urllib3>`_.
-
-
-Migrating as an application developer?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you're someone who writes Python but doesn't ship as a package (things like web services, data science, tools, and more) this section is for you.
-
-Python environments only allow for one version of a dependency to be installed per environment which means
-that **all of your dependencies using urllib3 need to support v2.0 for you to upgrade**.
-
-The best way to visualize relationships between your dependencies is using `pipdeptree <https://pypi.org/project/pipdeptree>`_ and ``$ pipdeptree --reverse``:
-
-.. code-block:: bash
-
-  # From inside your Python environment:
-  $ python -m pip install pipdeptree
-  # We only care about packages requiring urllib3
-  $ pipdeptree --reverse | grep "requires: urllib3"
-
-  - botocore==1.29.8 [requires: urllib3>=1.25.4,<2]
-  - requests==2.28.1 [requires: urllib3>=1.21.1,<2]
-
-Reading the output from above, there are two packages which depend on urllib3: ``botocore`` and ``requests``.
-The versions of these two packages both require urllib3 that is less than v2.0 (ie ``<2``).
-
-Because both of these packages require urllib3 before v2.0 the new version of urllib3 can't be installed
-by default. There are ways to force installing the newer version of urllib3 v2.0 (ie pinning to ``urllib3==2.0.0``)
-which you can do to test your application.
-
-It's important to know that even if you don't upgrade all of your services to 2.x
-immediately you will `receive security fixes on the 1.26.x release stream <#security-fixes-for-urllib3-v1-26-x>` for some time.
-
 
-Security fixes for urllib3 v1.26.x
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sunsetting urllib3 1.26.x
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Thanks to support from `Tidelift <https://tidelift.com/subscription/pkg/pypi-urllib3>`_
-we're able to continue supporting the v1.26.x release stream with
-security fixes for the foreseeable future 💖
+urllib3 1.26.x is not currently maintained. urllib3 2.x is the best version of urllib3
+and is widely supported by the larger Python ecosystem. That said, urllib3 1.26.x still
+sees significant download numbers, mainly because the botocore package still requires
+urllib3 1.26.x for Python 3.9 and earlier. If your organization would benefit from the
+continued support of urllib3 1.26.x, please contact sethmichaellarson@gmail.com to
+discuss sponsorship or contribution opportunities.
 
 However, upgrading is still recommended as **no new feature developments or non-critical
 bug fixes will be shipped to the 1.26.x release stream**.
 
-If your organization relies on urllib3 and is interested in continuing support you can learn
-more about the `Tidelift Subscription for Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>`_.
-
 **🤔 Common upgrading issues**
--------------------------------
+------------------------------
 
 ssl module is compiled with OpenSSL 1.0.2.k-fips
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -194,15 +68,15 @@ ssl module is compiled with OpenSSL 1.0.2.k-fips
 
 Remediation depends on your system:
 
-- **AWS Lambda**: Upgrade to the Python3.10 runtime as it uses OpenSSL 1.1.1. Alternatively, you can
+- **AWS Lambda**: Upgrade to the Python 3.10 (or later) runtime as it uses OpenSSL 1.1.1. Alternatively, you can
   use a `custom Docker image
   <https://aws.amazon.com/blogs/aws/new-for-aws-lambda-container-image-support/>`_ and ensure you
   use a Python build that uses OpenSSL 1.1.1 or later.
 - **Amazon Linux 2**: Upgrade to `Amazon Linux 2023
   <https://aws.amazon.com/linux/amazon-linux-2023/>`_. Alternatively, you can install OpenSSL 1.1.1
   on Amazon Linux 2 using ``yum install openssl11 openssl11-devel`` and then install Python with a
   tool like pyenv.
-- **Red Hat Enterpritse Linux 7 (RHEL 7)**: Upgrade to RHEL 8 or RHEL 9.
+- **Red Hat Enterpritse Linux 7 (RHEL 7)**: Upgrade to RHEL 8 or later.
 - **Read the Docs**: Upgrade your `configuration file to use Ubuntu 22.04
   <https://docs.readthedocs.io/en/stable/config-file/v2.html>`_ by using ``os: ubuntu-22.04`` in the
   ``build`` section. Feel free to use the `urllib3 configuration
@@ -228,12 +102,12 @@ library is unmaintained, but `replacements exist
 This likely happens because you're using botocore which `does not support urllib3 2.0 yet
 <https://github.com/boto/botocore/issues/2921>`_. The good news is that botocore explicitly declares
 in its dependencies that it only supports ``urllib3<2``. Make sure to use a recent pip. That way, pip
-will install urllib3 1.26.x until botocore starts supporting urllib3 2.0.
+will install urllib3 1.26.x for versions of botocore that do not support urllib3 2.0.
 
-If you're deploying to an AWS environment such as Lambda or a host using Amazon Linux 2,
-you'll need to explicitly pin to ``urllib3<2`` in your project to ensure urllib3 2.0 isn't
-brought into your environment. Otherwise, this may result in unintended side effects with
-the default boto3 installation.
+If you're deploying to an AWS environment such as Lambda with the Python 3.9 runtime or a host
+using Amazon Linux 2, you'll need to explicitly pin to ``urllib3<2`` in your project to ensure
+urllib3 2.0 isn't brought into your environment. Otherwise, this may result in unintended side
+effects with the default boto3 installation.
 
 AttributeError: module 'urllib3.connectionpool' has no attribute 'VerifiedHTTPSConnection'
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -251,18 +125,108 @@ AttributeError: 'HTTPResponse' object has no attribute 'strict'
 
 The ``strict`` parameter is unneeded with Python 3 and should be removed.
 
-Pinning urllib3<2
-~~~~~~~~~~~~~~~~~
 
-If the advice from the above sections did not help, you can pin urllib3 to 1.26.x by installing
-``urllib3<2``. Please do **not** specify ``urllib3==1.26.15`` to make sure you continue getting
-1.26.x updates!
 
-While urllib3 1.26.x is still supported, it won't get new features or bug fixes, just security
-updates. Consider opening a tracking issue to unpin urllib3 in the future to not stay on 1.26.x
-indefinitely.  For more details on the recommended way to handle your dependencies in general, see
-`Semantic Versioning Will Not Save You <https://hynek.me/articles/semver-will-not-save-you/>`_. The
-second half even uses urllib3 2.0 as an example!
+Migrating as an application developer?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're someone who writes Python but doesn't ship as a package (things like web services, data science, tools, and more) this section is for you.
+
+Python environments only allow for one version of a dependency to be installed per environment which means
+that **all of your dependencies using urllib3 need to support 2.x for you to upgrade**.
+
+The best way to visualize relationships between your dependencies is using `pipdeptree <https://pypi.org/project/pipdeptree>`_ and ``$ pipdeptree --reverse``:
+
+.. code-block:: bash
+
+  # From inside your Python environment:
+  $ python -m pip install pipdeptree
+  # We only care about packages requiring urllib3
+  $ pipdeptree --reverse | grep "requires: urllib3"
+  ├── botocore==1.38.36 [requires: urllib3>=1.25.4,<1.27]
+  └── requests==2.32.4 [requires: urllib3>=1.21.1,<3]
+
+Reading the output from above, there are two packages which depend on urllib3: ``botocore`` and ``requests``.
+While requests supports urllib3 2.x (with the ``<3`` specified), botocore requires urllib3 1.26.x (with the ``<1.27`` version specifier).
+Note that botocore does support urllib3 2.x, but it only supports it on Python 3.10 and later, which mandates OpenSSL 1.1.1+.
+
+It's important to know `urllib3 does not receive security fixes at the moment <#sunsetting-urllib3-1-26-x>`.
+
+
+Migrating as a package maintainer?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're a maintainer of a package that uses urllib3 under the hood then this section is for you.
+You may have already seen an issue opened from someone on our team about the upcoming release.
+
+The primary goal for migrating to urllib3 2.x should be to ensure your package supports **both urllib3 v1.26.x and 2.x for some time**.
+This is to reduce the chance that diamond dependencies are introduced into your users' dependencies which will then cause issues
+with them upgrading to the latest version of **your package**.
+
+The first step to supporting urllib3 2.x is to make sure the version 2.x not being excluded by ``install_requires``. You should
+ensure your package allows for both urllib3 1.26.x and 2.x to be used:
+
+.. code-block:: python
+
+  # setup.py (setuptools)
+  setup(
+    ...
+    install_requires=["urllib3>=1.26,<3"]
+  )
+
+  # pyproject.toml (hatch)
+  [project]
+  dependencies = [
+    "urllib3>=1.26,<3"
+  ]
+
+Next you should try installing urllib3 v2.0 locally and run your test suite.
+
+.. code-block:: bash
+
+  $ python -m pip install -U 'urllib3>=2'
+
+Because there are new ``DeprecationWarnings`` you should ensure that you're
+able to see those warnings when running your test suite. To do so you can add
+the following to your test setup to ensure even ``DeprecationWarnings`` are
+output to the terminal:
+
+.. code-block:: bash
+
+  # Set PYTHONWARNING=default to show all warnings.
+  $ export PYTHONWARNINGS="default"
+
+  # Run your test suite and look for failures.
+  # Pytest automatically prints all warnings.
+  $ pytest tests/
+
+or you can opt-in within your Python code:
+
+.. code-block:: python
+
+  # You can change warning filters according to the filter rules:
+  # https://docs.python.org/3/library/warnings.html#warning-filter
+  import warnings
+  warnings.filterwarnings("default", category=DeprecationWarning)
+
+Any failures or deprecation warnings you receive should be fixed as urllib3 v2.1.0 will remove all
+deprecated features. Many deprecation warnings will make suggestions about what to do to avoid the deprecated feature.
+
+Warnings will look something like this:
+
+.. code-block:: bash
+
+  DeprecationWarning: 'ssl_version' option is deprecated and will be removed
+  in urllib3 v2.6.0. Instead use 'ssl_minimum_version'
+
+Continue removing deprecation warnings until there are no more. After this you can publish a new release of your package
+that supports both urllib3 1.26.x and 2.x.
+
+.. note::
+
+  If you're not able to support both 1.26.x and 2.x of urllib3 at the same time with your package please
+  `open an issue on GitHub <https://github.com/urllib3/urllib3/issues>`_ or reach out in
+  `our community Discord channel <https://discord.gg/urllib3>`_.
 
 
 **💪 User-friendly features**
@@ -321,15 +285,14 @@ for requests and ``HTTPResponse.json()`` method on responses:
   }
 
 
-**✨ Optimized for Python 3.7+**
+**✨ Optimized for Python 3.9+**
 --------------------------------
 
-In v2.0 we'll be specifically targeting
-CPython 3.7+ and PyPy 7.0+ (compatible with CPython 3.7)
-and dropping support for Python versions 2.7, 3.5, and 3.6.
-
+urllib3 2.x specifically targets CPython 3.9+ and PyPy 7.3.17+ (compatible with CPython 3.10)
+and dropping support for Python versions 2.7, and 3.5 to 3.8.
+  
 By dropping end-of-life Python versions we're able to optimize
-the codebase for Python 3.7+ by using new features to improve
+the codebase for Python 3.9+ by using new features to improve
 performance and reduce the amount of code that needs to be executed
 in order to support legacy versions.
 

src/urllib3/response.py

@@ -543,7 +543,7 @@ def readinto(self, b: bytearray) -> int:
     def getheaders(self) -> HTTPHeaderDict:
         warnings.warn(
             "HTTPResponse.getheaders() is deprecated and will be removed "
-            "in urllib3 v2.1.0. Instead access HTTPResponse.headers directly.",
+            "in urllib3 v2.6.0. Instead access HTTPResponse.headers directly.",
             category=DeprecationWarning,
             stacklevel=2,
         )
@@ -552,7 +552,7 @@ def getheaders(self) -> HTTPHeaderDict:
     def getheader(self, name: str, default: str | None = None) -> str | None:
         warnings.warn(
             "HTTPResponse.getheader() is deprecated and will be removed "
-            "in urllib3 v2.1.0. Instead use HTTPResponse.headers.get(name, default).",
+            "in urllib3 v2.6.0. Instead use HTTPResponse.headers.get(name, default).",
             category=DeprecationWarning,
             stacklevel=2,
         )