index.rst 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. .. Requests documentation master file, created by
  2. sphinx-quickstart on Sun Feb 13 23:54:25 2011.
  3. You can adapt this file completely to your liking, but it should at least
  4. contain the root `toctree` directive.
  5. Requests: HTTP for Humans
  6. =========================
  7. Release v\ |version|. (:ref:`Installation <install>`)
  8. Requests is the only *Non-GMO* HTTP library for Python, safe for human
  9. consumption.
  10. **Warning:** Recreational use of other HTTP libraries may result in dangerous side-effects,
  11. including: security vulnerabilities, verbose code, reinventing the wheel,
  12. constantly reading documentation, depression, headaches, or even death.
  13. Behold, the power of Requests::
  14. >>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
  15. >>> r.status_code
  16. 200
  17. >>> r.headers['content-type']
  18. 'application/json; charset=utf8'
  19. >>> r.encoding
  20. 'utf-8'
  21. >>> r.text
  22. u'{"type":"User"...'
  23. >>> r.json()
  24. {u'private_gists': 419, u'total_private_repos': 77, ...}
  25. See `similar code, sans Requests <https://gist.github.com/973705>`_.
  26. Requests allows you to send *organic, grass-fed* HTTP/1.1 requests, without the
  27. need for manual labor. There's no need to manually add query strings to your
  28. URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling
  29. are 100% automatic, powered by `urllib3 <https://github.com/shazow/urllib3>`_,
  30. which is embedded within Requests.
  31. User Testimonials
  32. -----------------
  33. Her Majesty's Government, Amazon, Google, Twilio, Runscope, Mozilla, Heroku,
  34. PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington
  35. Post, Twitter, SoundCloud, Kippt, Readability, Sony, and Federal U.S.
  36. Institutions that prefer to be unnamed claim to use Requests internally.
  37. **Armin Ronacher**
  38. Requests is the perfect example how beautiful an API can be with the
  39. right level of abstraction.
  40. **Matt DeBoard**
  41. I'm going to get @kennethreitz's Python requests module tattooed
  42. on my body, somehow. The whole thing.
  43. **Daniel Greenfeld**
  44. Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to
  45. @kennethreitz's request library. Today has been AWESOME.
  46. **Kenny Meyers**
  47. Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful,
  48. simple, Pythonic.
  49. Requests is one of the most downloaded Python packages of all time, pulling in
  50. over 7,000,000 downloads every month. All the cool kids are doing it!
  51. Supported Features
  52. ------------------
  53. Requests is ready for today's web.
  54. - International Domains and URLs
  55. - Keep-Alive & Connection Pooling
  56. - Sessions with Cookie Persistence
  57. - Browser-style SSL Verification
  58. - Basic/Digest Authentication
  59. - Elegant Key/Value Cookies
  60. - Automatic Decompression
  61. - Automatic Content Decoding
  62. - Unicode Response Bodies
  63. - Multipart File Uploads
  64. - HTTP(S) Proxy Support
  65. - Connection Timeouts
  66. - Streaming Downloads
  67. - ``.netrc`` Support
  68. - Chunked Requests
  69. - Thread-safety
  70. Requests supports Python 2.6 — 3.5, and runs great on PyPy.
  71. The User Guide
  72. --------------
  73. This part of the documentation, which is mostly prose, begins with some
  74. background information about Requests, then focuses on step-by-step
  75. instructions for getting the most out of Requests.
  76. .. toctree::
  77. :maxdepth: 2
  78. user/intro
  79. user/install
  80. user/quickstart
  81. user/advanced
  82. user/authentication
  83. The Community Guide
  84. -------------------
  85. This part of the documentation, which is mostly prose, details the
  86. Requests ecosystem and community.
  87. .. toctree::
  88. :maxdepth: 1
  89. community/faq
  90. community/recommended
  91. community/out-there
  92. community/support
  93. community/vulnerabilities
  94. community/updates
  95. community/release-process
  96. The API Documentation / Guide
  97. -----------------------------
  98. If you are looking for information on a specific function, class, or method,
  99. this part of the documentation is for you.
  100. .. toctree::
  101. :maxdepth: 2
  102. api
  103. The Contributor Guide
  104. ---------------------
  105. If you want to contribute to the project, this part of the documentation is for
  106. you.
  107. .. toctree::
  108. :maxdepth: 3
  109. dev/contributing
  110. dev/philosophy
  111. dev/todo
  112. dev/authors
  113. There are no more guides. You are now guideless.
  114. Good luck.