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