index.rst 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  1. urllib3
  2. =======
  3. .. toctree::
  4. :hidden:
  5. :maxdepth: 3
  6. For Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>
  7. v2-roadmap
  8. sponsors
  9. user-guide
  10. advanced-usage
  11. reference/index
  12. contributing
  13. urllib3 is a powerful, *user-friendly* HTTP client for Python.
  14. :ref:`Much of the Python ecosystem already uses <who-uses>` urllib3 and you should too.
  15. urllib3 brings many critical features that are missing from the Python
  16. standard libraries:
  17. - Thread safety.
  18. - Connection pooling.
  19. - Client-side TLS/SSL verification.
  20. - File uploads with multipart encoding.
  21. - Helpers for retrying requests and dealing with HTTP redirects.
  22. - Support for gzip, deflate, and brotli encoding.
  23. - Proxy support for HTTP and SOCKS.
  24. - 100% test coverage.
  25. urllib3 is powerful and easy to use:
  26. .. code-block:: python
  27. >>> import urllib3
  28. >>> http = urllib3.PoolManager()
  29. >>> r = http.request('GET', 'http://httpbin.org/robots.txt')
  30. >>> r.status
  31. 200
  32. >>> r.data
  33. 'User-agent: *\nDisallow: /deny\n'
  34. For Enterprise
  35. --------------
  36. .. |tideliftlogo| image:: https://nedbatchelder.com/pix/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White_small.png
  37. :width: 75
  38. :alt: Tidelift
  39. .. list-table::
  40. :widths: 10 100
  41. * - |tideliftlogo|_
  42. - Professional support for urllib3 is available as part of the `Tidelift
  43. Subscription`_. Tidelift gives software development teams a single source for
  44. purchasing and maintaining their software, with professional grade assurances
  45. from the experts who know it best, while seamlessly integrating with existing
  46. tools.
  47. .. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs
  48. .. _tideliftlogo: https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs
  49. |learn-more|_ |request-a-demo|_
  50. .. |learn-more| image:: https://raw.githubusercontent.com/urllib3/urllib3/master/docs/images/learn-more-button.png
  51. :width: 49%
  52. :alt: Learn more about Tidelift Subscription
  53. .. _learn-more: https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs
  54. .. |request-a-demo| image:: https://raw.githubusercontent.com/urllib3/urllib3/master/docs/images/demo-button.png
  55. :width: 49%
  56. :alt: Request a Demo for the Tidelift Subscription
  57. .. _request-a-demo: https://tidelift.com/subscription/request-a-demo?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs
  58. Installing
  59. ----------
  60. urllib3 can be installed with `pip <https://pip.pypa.io>`_
  61. .. code-block:: bash
  62. $ python -m pip install urllib3
  63. Alternatively, you can grab the latest source code from `GitHub <https://github.com/urllib3/urllib3>`_:
  64. .. code-block:: bash
  65. $ git clone https://github.com/urllib3/urllib3.git
  66. $ cd urllib3
  67. $ git checkout 1.26.x
  68. $ pip install .
  69. Usage
  70. -----
  71. The :doc:`user-guide` is the place to go to learn how to use the library and
  72. accomplish common tasks. The more in-depth :doc:`advanced-usage` guide is the place to go for lower-level tweaking.
  73. The :doc:`reference/index` documentation provides API-level documentation.
  74. .. _who-uses:
  75. Who uses urllib3?
  76. -----------------
  77. `urllib3 is one of the most downloaded packages on PyPI <https://pypistats.org/top>`_
  78. and is a dependency of many popular Python packages like `Requests <https://requests.readthedocs.io>`_,
  79. `Pip <https://pip.pypa.io>`_, and more!
  80. License
  81. -------
  82. urllib3 is made available under the MIT License. For more details, see `LICENSE.txt <https://github.com/urllib3/urllib3/blob/master/LICENSE.txt>`_.
  83. Contributing
  84. ------------
  85. We happily welcome contributions, please see :doc:`contributing` for details.