1v2.0 Roadmap 2============ 3 4.. important:: 5 6 We're seeking `sponsors and supporters for urllib3 v2.0 on Open Collective <https://github.com/sponsors/urllib3>`_. 7 There's a lot of work to be done for our small team and we want to make sure 8 development can get completed on-time while also fairly compensating contributors 9 for the additional effort required for a large release like ``v2.0``. 10 11 Additional information available within the :doc:`sponsors` section of our documentation. 12 13 14**�� Functional API Compatibility** 15----------------------------------- 16 17We're maintaining **99% functional API compatibility** to make the 18migration an easy choice for most users. Migration from v1.x to v2.x 19should be the simplest major version upgrade you've ever completed. 20 21Most changes are either to default configurations, supported Python versions, 22and internal implementation details. So unless you're in a specific situation 23you should notice no changes! �� 24 25 26v1.26.x Security and Bug Fixes 27~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 28 29Thanks to support from `Tidelift <https://tidelift.com/subscription/pkg/pypi-urllib3>`_ 30we're able to continue supporting v1.26.x releases with 31both security and bug fixes for the forseeable future �� 32 33If your organization relies on urllib3 and is interested in continuing support you can learn 34more about the `Tidelift Subscription for Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>`_. 35 36 37**�� Modern Security by Default** 38--------------------------------- 39 40HTTPS requires TLS 1.2+ 41~~~~~~~~~~~~~~~~~~~~~~~ 42 43Greater than 95% of websites support TLS 1.2 or above. 44At this point we're comfortable switching the default 45minimum TLS version to be 1.2 to ensure high security 46for users without breaking services. 47 48Dropping TLS 1.0 and 1.1 by default means you 49won't be vulnerable to TLS downgrade attacks 50if a vulnerability in TLS 1.0 or 1.1 were discovered in 51the future. Extra security for free! By dropping TLS 1.0 52and TLS 1.1 we also tighten the list of ciphers we need 53to support to ensure high security for data traveling 54over the wire. 55 56If you still need to use TLS 1.0 or 1.1 in your application 57you can still upgrade to v2.0, you'll only need to set 58``ssl_version`` to the proper values to continue using 59legacy TLS versions. 60 61 62Stop Verifying CommonName in Certificates 63~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 64 65Dropping support the long deprecated ``commonName`` 66field on certificates in favor of only verifying 67``subjectAltName`` to put us in line with browsers and 68other HTTP client libraries and to improve security for our users. 69 70 71Certificate Verification via SSLContext 72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74By default certificate verification is handled by urllib3 75to support legacy Python versions, but now we can 76rely on Python's certificate verification instead! This 77should result in a speedup for verifying certificates 78and means that any improvements made to certificate 79verification in Python or OpenSSL will be immediately 80available. 81 82 83**✨ Optimized for Python 3.6+** 84-------------------------------- 85 86In v2.0 we'll be specifically be targeting 87CPython 3.6+ and PyPy 7.0+ (compatible with CPython 3.6) 88and dropping support Python versions 2.7 and 3.5. 89 90By dropping end-of-life Python versions we're able to optimize 91the codebase for Python 3.6+ by using new features to improve 92performance and reduce the amount of code that needs to be executed 93in order to support legacy versions. 94 95 96**�� Tracing** 97-------------- 98 99Currently with urllib3 it's tough to get low-level insights into what 100how your HTTP client is performing and what your connection information 101looks like. In v2.0 we'll be adding tracing and telemetry information 102to HTTP response objects including: 103 104- Connection ID 105- IP Address resolved by DNS 106- Request Method, Target, and Headers 107- TLS Version and Cipher 108- Certificate Fingerprint, subjectAltName, and Validity Information 109- Timings for DNS, Request Data, First Byte in Response 110 111 112**�� Type-Hinted APIs** 113----------------------- 114 115You'll finally be able to run Mypy or other type-checkers 116on code using urllib3. This also means that for IDEs 117that support type hints you'll receive better suggestions 118from auto-complete. No more confusing with ``**kwargs``! 119 120We'll also add API interfaces to ensure that when 121you're sub-classing an interface you're only using 122supported public APIs to ensure compatibility and 123minimize breakages down the road. 124 125 126**�� ...and many more features!** 127--------------------------------- 128 129- Top-level ``urllib3.request()`` API 130- Open Possibility to Alternate HTTP Implementations 131- Translated Guides 132- Support Zstandard Compression 133- Streaming ``multipart/form-encoded`` Request Data 134- More Powerful and Configurable Retry Logic 135 136If there's a feature you don't see here but would like to see 137in urllib3 v2.0, there's an open GitHub issue for making 138feature suggestions. 139 140 141**�� Release and Migration Schedule** 142------------------------------------- 143 144We're aiming for all ``v2.x`` features to be released in **mid-to-late 2021**. 145 146Here's what the release and migration schedule will look like leading up 147to v2.0 being released: 148 149- Development of ``v2.x`` breaking changes starts. 150- Release ``v1.26.0`` with deprecation warnings for ``v2.0.0`` breaking changes. 151 This will be the last non-patch release within the ``v1.x`` stream. 152- Release ``v2.0.0-alpha1`` once all breaking changes have been completed. 153 We'll wait for users to report issues, bugs, and unexpected 154 breakages at this stage to ensure the release ``v2.0.0`` goes smoothly. 155- Development of remaining ``v2.x`` features starts. 156- Release ``v2.0.0`` which will be identical to ``v2.0.0-alpha1``. 157- Release ``v2.1.0`` with remaining ``v2.x`` features. 158 159Deprecation warnings within ``v1.26.x`` will be opt-in by default. 160 161**More detailed Application Migration Guide coming soon.** 162 163For Package Maintainers 164~~~~~~~~~~~~~~~~~~~~~~~ 165 166Since this is the first major release in almost 9 years some users may 167be caught off-guard by a new major release of urllib3. We're mitigating this by 168trying to make ``v2.x`` API-compatible with ``v1.x``. 169 170If your application or library uses urllib3 and you'd like to be extra 171cautious about not breaking your users, you can pin urllib3 like so 172until you ensure compatibility with ``v2.x``: 173 174.. code-block:: python 175 176 # 'install_requires' or 'requirements.txt' 177 "urllib3>=1.25,<2" 178 179We'd really appreciate testing compatibility 180and providing feedback on ``v2.0.0-alpha1`` once released. 181