v2-roadmap.rst 6.3 KB

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