README.rst 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. Requests: HTTP for Humans
  2. =========================
  3. .. image:: https://img.shields.io/pypi/v/requests.svg
  4. :target: https://pypi.python.org/pypi/requests
  5. .. image:: https://img.shields.io/pypi/l/requests.svg
  6. :target: https://pypi.python.org/pypi/requests
  7. .. image:: https://img.shields.io/pypi/pyversions/requests.svg
  8. :target: https://pypi.python.org/pypi/requests
  9. .. image:: https://codecov.io/github/requests/requests/coverage.svg?branch=master
  10. :target: https://codecov.io/github/requests/requests
  11. :alt: codecov.io
  12. .. image:: https://img.shields.io/github/contributors/requests/requests.svg
  13. :target: https://github.com/requests/requests/graphs/contributors
  14. .. image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg
  15. :target: https://saythanks.io/to/kennethreitz
  16. Requests is the only *Non-GMO* HTTP library for Python, safe for human
  17. consumption.
  18. **Warning:** Recreational use of the Python standard library for HTTP may result in dangerous side-effects,
  19. including: security vulnerabilities, verbose code, reinventing the wheel,
  20. constantly reading documentation, depression, headaches, or even death.
  21. Behold, the power of Requests:
  22. .. code-block:: python
  23. >>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
  24. >>> r.status_code
  25. 200
  26. >>> r.headers['content-type']
  27. 'application/json; charset=utf8'
  28. >>> r.encoding
  29. 'utf-8'
  30. >>> r.text
  31. u'{"type":"User"...'
  32. >>> r.json()
  33. {u'disk_usage': 368627, u'private_gists': 484, ...}
  34. See `the similar code, sans Requests <https://gist.github.com/973705>`_.
  35. .. image:: https://raw.githubusercontent.com/requests/requests/master/docs/_static/requests-logo-small.png
  36. :target: http://docs.python-requests.org/
  37. Requests allows you to send *organic, grass-fed* HTTP/1.1 requests, without the
  38. need for manual labor. There's no need to manually add query strings to your
  39. URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling
  40. are 100% automatic, thanks to `urllib3 <https://github.com/shazow/urllib3>`_.
  41. Besides, all the cool kids are doing it. Requests is one of the most
  42. downloaded Python packages of all time, pulling in over 11,000,000 downloads
  43. every month. You don't want to be left out!
  44. Feature Support
  45. ---------------
  46. Requests is ready for today's web.
  47. - International Domains and URLs
  48. - Keep-Alive & Connection Pooling
  49. - Sessions with Cookie Persistence
  50. - Browser-style SSL Verification
  51. - Basic/Digest Authentication
  52. - Elegant Key/Value Cookies
  53. - Automatic Decompression
  54. - Automatic Content Decoding
  55. - Unicode Response Bodies
  56. - Multipart File Uploads
  57. - HTTP(S) Proxy Support
  58. - Connection Timeouts
  59. - Streaming Downloads
  60. - ``.netrc`` Support
  61. - Chunked Requests
  62. Requests officially supports Python 2.6–2.7 & 3.3–3.7, and runs great on PyPy.
  63. Installation
  64. ------------
  65. To install Requests, simply:
  66. .. code-block:: bash
  67. $ pip install requests
  68. ✨🍰✨
  69. Satisfaction guaranteed.
  70. Documentation
  71. -------------
  72. Fantastic documentation is available at http://docs.python-requests.org/, for a limited time only.
  73. How to Contribute
  74. -----------------
  75. #. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a `Contributor Friendly`_ tag for issues that should be ideal for people who are not very familiar with the codebase yet.
  76. #. Fork `the repository`_ on GitHub to start making your changes to the **master** branch (or branch off of it).
  77. #. Write a test which shows that the bug was fixed or that the feature works as expected.
  78. #. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS_.
  79. .. _`the repository`: http://github.com/requests/requests
  80. .. _AUTHORS: https://github.com/requests/requests/blob/master/AUTHORS.rst
  81. .. _Contributor Friendly: https://github.com/requests/requests/issues?direction=desc&labels=Contributor+Friendly&page=1&sort=updated&state=open