README 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122
  1. Httplib2
  2. --------------------------------------------------------------------
  3. Introduction
  4. A comprehensive HTTP client library, httplib2.py supports many
  5. features left out of other HTTP libraries.
  6. HTTP and HTTPS
  7. HTTPS support is only available if the socket module was
  8. compiled with SSL support.
  9. Keep-Alive
  10. Supports HTTP 1.1 Keep-Alive, keeping the socket open and
  11. performing multiple requests over the same connection if
  12. possible.
  13. Authentication
  14. The following three types of HTTP Authentication are
  15. supported. These can be used over both HTTP and HTTPS.
  16. * Digest
  17. * Basic
  18. * WSSE
  19. Caching
  20. The module can optionally operate with a private cache that
  21. understands the Cache-Control: header and uses both the ETag
  22. and Last-Modified cache validators.
  23. All Methods
  24. The module can handle any HTTP request method, not just GET
  25. and POST.
  26. Redirects
  27. Automatically follows 3XX redirects on GETs.
  28. Compression
  29. Handles both 'deflate' and 'gzip' types of compression.
  30. Lost update support
  31. Automatically adds back ETags into PUT requests to resources
  32. we have already cached. This implements Section 3.2 of
  33. Detecting the Lost Update Problem Using Unreserved Checkout.
  34. Unit Tested
  35. A large and growing set of unit tests.
  36. For more information on this module, see:
  37. http://bitworking.org/projects/httplib2/
  38. --------------------------------------------------------------------
  39. Installation
  40. The httplib2 module is shipped as a distutils package. To install
  41. the library, unpack the distribution archive, and issue the following
  42. command:
  43. $ python setup.py install
  44. --------------------------------------------------------------------
  45. Usage
  46. A simple retrieval:
  47. import httplib2
  48. h = httplib2.Http(".cache")
  49. (resp_headers, content) = h.request("http://example.org/", "GET")
  50. The 'content' is the content retrieved from the URL. The content
  51. is already decompressed or unzipped if necessary.
  52. To PUT some content to a server that uses SSL and Basic authentication:
  53. import httplib2
  54. h = httplib2.Http(".cache")
  55. h.add_credentials('name', 'password')
  56. (resp, content) = h.request("https://example.org/chapter/2",
  57. "PUT", body="This is text",
  58. headers={'content-type':'text/plain'} )
  59. Use the Cache-Control: header to control how the caching operates.
  60. import httplib2
  61. h = httplib2.Http(".cache")
  62. (resp, content) = h.request("http://bitworking.org/", "GET")
  63. ...
  64. (resp, content) = h.request("http://bitworking.org/", "GET",
  65. headers={'cache-control':'no-cache'})
  66. The first request will be cached and since this is a request
  67. to bitworking.org it will be set to be cached for two hours,
  68. because that is how I have my server configured. Any subsequent
  69. GET to that URI will return the value from the on-disk cache
  70. and no request will be made to the server. You can use the
  71. Cache-Control: header to change the caches behavior and in
  72. this example the second request adds the Cache-Control:
  73. header with a value of 'no-cache' which tells the library
  74. that the cached copy must not be used when handling this request.
  75. --------------------------------------------------------------------
  76. Httplib2 Software License
  77. Copyright (c) 2006 by Joe Gregorio
  78. Permission is hereby granted, free of charge, to any person
  79. obtaining a copy of this software and associated documentation
  80. files (the "Software"), to deal in the Software without restriction,
  81. including without limitation the rights to use, copy, modify, merge,
  82. publish, distribute, sublicense, and/or sell copies of the Software,
  83. and to permit persons to whom the Software is furnished to do so,
  84. subject to the following conditions:
  85. The above copyright notice and this permission notice shall be
  86. included in all copies or substantial portions of the Software.
  87. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  88. EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  89. OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  90. NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  91. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  92. ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  93. CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  94. SOFTWARE.