index.rst 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  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 an :ref:`Apache2 Licensed <apache2>` HTTP library, written in Python, for human beings.
  9. Python's standard **urllib2** module provides most of
  10. the HTTP capabilities you need, but the API is thoroughly **broken**.
  11. It was built for a different time — and a different web. It requires an *enormous* amount of work (even method overrides) to perform the simplest of tasks.
  12. Things shouldn’t be this way. Not in Python.
  13. ::
  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, without Requests <https://gist.github.com/973705>`_.
  26. Requests takes all of the work out of Python HTTP/1.1 — making your integration with web services seamless. There's no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by `urllib3 <https://github.com/shazow/urllib3>`_, which is embedded within Requests.
  27. Testimonials
  28. ------------
  29. Her Majesty's Government, Amazon, Google, Twilio, Runscope, Mozilla, Heroku, PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington Post, Twitter, SoundCloud, Kippt, Readability, and Federal US Institutions use Requests internally. It has been downloaded over 5,000,000 times from PyPI.
  30. **Armin Ronacher**
  31. Requests is the perfect example how beautiful an API can be with the
  32. right level of abstraction.
  33. **Matt DeBoard**
  34. I'm going to get @kennethreitz's Python requests module tattooed
  35. on my body, somehow. The whole thing.
  36. **Daniel Greenfeld**
  37. Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to
  38. @kennethreitz's request library. Today has been AWESOME.
  39. **Kenny Meyers**
  40. Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful,
  41. simple, Pythonic.
  42. Feature Support
  43. ---------------
  44. Requests is ready for today's web.
  45. - International Domains and URLs
  46. - Keep-Alive & Connection Pooling
  47. - Sessions with Cookie Persistence
  48. - Browser-style SSL Verification
  49. - Basic/Digest Authentication
  50. - Elegant Key/Value Cookies
  51. - Automatic Decompression
  52. - Unicode Response Bodies
  53. - Multipart File Uploads
  54. - Connection Timeouts
  55. - ``.netrc`` support
  56. - Python 2.6—3.3
  57. - Thread-safe.
  58. User Guide
  59. ----------
  60. This part of the documentation, which is mostly prose, begins with some
  61. background information about Requests, then focuses on step-by-step
  62. instructions for getting the most out of Requests.
  63. .. toctree::
  64. :maxdepth: 2
  65. user/intro
  66. user/install
  67. user/quickstart
  68. user/advanced
  69. user/authentication
  70. Community Guide
  71. -----------------
  72. This part of the documentation, which is mostly prose, details the
  73. Requests ecosystem and community.
  74. .. toctree::
  75. :maxdepth: 1
  76. community/faq
  77. community/out-there.rst
  78. community/support
  79. community/updates
  80. API Documentation
  81. -----------------
  82. If you are looking for information on a specific function, class or method,
  83. this part of the documentation is for you.
  84. .. toctree::
  85. :maxdepth: 2
  86. api
  87. Contributor Guide
  88. -----------------
  89. If you want to contribute to the project, this part of the documentation is for
  90. you.
  91. .. toctree::
  92. :maxdepth: 1
  93. dev/philosophy
  94. dev/internals
  95. dev/todo
  96. dev/authors