jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 1 | % Template for a library manual section. |
| 2 | % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE |
| 3 | % |
| 4 | % Complete documentation on the extended LaTeX markup used for Python |
| 5 | % documentation is available in ``Documenting Python'', which is part |
| 6 | % of the standard documentation for Python. It may be found online |
| 7 | % at: |
| 8 | % |
| 9 | % http://www.python.org/doc/current/doc/doc.html |
| 10 | |
| 11 | % ==== 0. ==== |
| 12 | % Copy this file to <mydir>/lib<mymodule>.tex, and edit that file |
| 13 | % according to the instructions below. |
| 14 | |
| 15 | |
| 16 | % ==== 1. ==== |
| 17 | % The section prologue. Give the section a title and provide some |
| 18 | % meta-information. References to the module should use |
| 19 | % \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as |
| 20 | % appropriate. |
| 21 | |
| 22 | |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 23 | \section{\module{httplib2} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 24 | A comprehensive HTTP client library. } |
| 25 | |
| 26 | % Choose one of these to specify the module module name. If there's |
| 27 | % an underscore in the name, use |
| 28 | % \declaremodule[modname]{...}{mod_name} instead. |
| 29 | % |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 30 | \declaremodule{}{httplib2} % not standard, in Python |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 31 | |
| 32 | % Portability statement: Uncomment and fill in the parameter to specify the |
| 33 | % availability of the module. The parameter can be Unix, IRIX, SunOS, Mac, |
| 34 | % Windows, or lots of other stuff. When ``Mac'' is specified, the availability |
| 35 | % statement will say ``Macintosh'' and the Module Index may say ``Mac''. |
| 36 | % Please use a name that has already been used whenever applicable. If this |
| 37 | % is omitted, no availability statement is produced or implied. |
| 38 | % |
| 39 | % \platform{Unix} |
| 40 | |
| 41 | % These apply to all modules, and may be given more than once: |
| 42 | |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 43 | \moduleauthor{Joe Gregorio}{joe@bitworking.org} % Author of the module code; |
| 44 | % omit if not known. |
| 45 | \sectionauthor{Joe Gregorio}{joe@bitworking.org} % Author of the documentation, |
| 46 | % even if not a module section. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 47 | |
| 48 | |
| 49 | % Leave at least one blank line after this, to simplify ad-hoc tools |
| 50 | % that are sometimes used to massage these files. |
| 51 | \modulesynopsis{A comprehensive HTTP client library, \module{httplib2} supports many features left out of other HTTP libraries.} |
| 52 | |
| 53 | |
| 54 | % ==== 2. ==== |
| 55 | % Give a short overview of what the module does. |
| 56 | % If it is platform specific, mention this. |
| 57 | % Mention other important restrictions or general operating principles. |
| 58 | % For example: |
| 59 | |
| 60 | The \module{httplib2} module is a comprehensive HTTP client library with the following features: |
| 61 | |
| 62 | \begin{description} |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 63 | \item[HTTP and HTTPS] HTTPS support is only available if the socket module was compiled with SSL support. |
| 64 | \item[Keep-Alive] Supports HTTP 1.1 Keep-Alive, keeping the socket open and performing multiple requests over the same connection if possible. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 65 | \item[Authentication] The following three types of HTTP Authentication are supported. These can be used over both HTTP and HTTPS. |
| 66 | \begin{itemize} |
| 67 | \item Digest |
| 68 | \item Basic |
| 69 | \item WSSE |
| 70 | \end{itemize} |
| 71 | \item[Caching] |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 72 | The module can optionally operate with a private cache that understands the Cache-Control: header and uses both the ETag and Last-Modified cache validators. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 73 | \item[All Methods] |
| 74 | The module can handle any HTTP request method, not just GET and POST. |
| 75 | \item[Redirects] |
| 76 | Automatically follows 3XX redirects on GETs. |
| 77 | \item[Compression] |
| 78 | Handles both 'deflate' and 'gzip' types of compression. |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 79 | \item[Proxies] |
| 80 | If the Socksipy module is installed then httplib2 can handle sock4, sock5 and http proxies. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 81 | \item[Lost update support] |
| 82 | Automatically adds back ETags into PUT requests to resources we have already cached. This implements Section 3.2 of Detecting the Lost Update Problem Using Unreserved Checkout |
| 83 | \end{description} |
| 84 | |
| 85 | % ==== 3. ==== |
| 86 | % List the public functions defined by the module. Begin with a |
| 87 | % standard phrase. You may also list the exceptions and other data |
| 88 | % items defined in the module, insofar as they are important for the |
| 89 | % user. |
| 90 | |
| 91 | The \module{httplib2} module defines the following variables: |
| 92 | % ---- 3.2. ---- |
| 93 | % Data items are described using a ``datadesc'' block. This has only |
| 94 | % one parameter: the item's name. |
| 95 | |
| 96 | \begin{datadesc}{debuglevel} |
| 97 | The amount of debugging information to print. The default is 0. |
| 98 | \end{datadesc} |
| 99 | |
Joe Gregorio | 3b089c9 | 2012-04-17 12:40:39 -0400 | [diff] [blame] | 100 | \begin{datadesc}{RETRIES} |
| 101 | A request will be tried 'RETRIES' times if it fails at the socket/connection level. |
| 102 | The default is 2. |
| 103 | \end{datadesc} |
| 104 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 105 | % --- 3.3. --- |
| 106 | % Exceptions are described using a ``excdesc'' block. This has only |
| 107 | % one parameter: the exception name. Exceptions defined as classes in |
| 108 | % the source code should be documented using this environment, but |
| 109 | % constructor parameters must be omitted. |
| 110 | |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 111 | The \module{httplib2} module may raise the following Exceptions. Note that |
| 112 | there is an option that turns exceptions into |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 113 | normal responses with an HTTP status code indicating |
| 114 | an error occured. See \member{Http.force_exception_to_status_code} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 115 | |
| 116 | \begin{excdesc}{HttpLib2Error} |
| 117 | The Base Exception for all exceptions raised by httplib2. |
| 118 | \end{excdesc} |
| 119 | |
| 120 | \begin{excdesc}{RedirectMissingLocation} |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 121 | A 3xx redirect response code was provided but no Location: header |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 122 | was provided to point to the new location. |
| 123 | \end{excdesc} |
| 124 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 125 | \begin{excdesc}{RedirectLimit} |
| 126 | The maximum number of redirections was reached without coming to a final URI. |
| 127 | \end{excdesc} |
| 128 | |
| 129 | |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 130 | \begin{excdesc}{ServerNotFoundError} |
| 131 | Unable to resolve the host name given. |
| 132 | \end{excdesc} |
| 133 | |
| 134 | \begin{excdesc}{RelativeURIError} |
| 135 | A relative, as opposed to an absolute URI, was passed into request(). |
| 136 | \end{excdesc} |
| 137 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 138 | \begin{excdesc}{FailedToDecompressContent} |
| 139 | The headers claimed that the content of the response was compressed but the |
| 140 | decompression algorithm applied to the content failed. |
| 141 | \end{excdesc} |
| 142 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 143 | \begin{excdesc}{UnimplementedDigestAuthOptionError} |
| 144 | The server requested a type of Digest authentication that we |
| 145 | are unfamiliar with. |
| 146 | \end{excdesc} |
| 147 | |
| 148 | \begin{excdesc}{UnimplementedHmacDigestAuthOptionError} |
| 149 | The server requested a type of HMACDigest authentication that we |
| 150 | are unfamiliar with. |
| 151 | \end{excdesc} |
| 152 | |
| 153 | % ---- 3.4. ---- |
| 154 | % Other standard environments: |
| 155 | % |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 156 | % classdesc - Python classes; same arguments are funcdesc |
| 157 | % methoddesc - methods, like funcdesc but has an optional parameter |
| 158 | % to give the type name: \begin{methoddesc}[mytype]{name}{args} |
| 159 | % By default, the type name will be the name of the |
| 160 | % last class defined using classdesc. The type name |
| 161 | % is required if the type is implemented in C (because |
| 162 | % there's no classdesc) or if the class isn't directly |
| 163 | % documented (if it's private). |
| 164 | % memberdesc - data members, like datadesc, but with an optional |
| 165 | % type name like methoddesc. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 166 | |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 167 | \begin{classdesc}{Http}{\optional{cache=None}, \optional{timeout=None}, \optional{proxy_info=None}} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 168 | The class that represents a client HTTP interface. |
| 169 | The \var{cache} parameter is either the name of a directory |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 170 | to be used as a flat file cache, or it must an object that |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 171 | implements the required caching interface. |
jcgregorio | afc233d | 2007-03-09 02:30:04 +0000 | [diff] [blame] | 172 | The \var{timeout} parameter is the socket level timeout. |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 173 | The \var{proxy_info} is an instance of \class{ProxyInfo} and is supplied |
| 174 | if a proxy is to be used. Note that the Socksipy module must be |
| 175 | installed for proxy support to work. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 176 | \end{classdesc} |
| 177 | |
| 178 | \begin{classdesc}{Response}{info} |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 179 | Response is a subclass of \class{dict} and instances of this |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 180 | class are returned from calls |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 181 | to Http.request. The \var{info} parameter is either |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 182 | an \class{rfc822.Message} or an \class{httplib.HTTPResponse} object. |
| 183 | \end{classdesc} |
| 184 | |
jcgregorio | ee542cc | 2006-11-16 04:43:19 +0000 | [diff] [blame] | 185 | \begin{classdesc}{FileCache}{dir_name, \optional{safe=safename}} |
| 186 | FileCache implements a Cache as a directory of files. |
| 187 | The \var{dir_name} parameter is |
| 188 | the name of the directory to use. If the directory does |
| 189 | not exist then FileCache attempts to create the directory. |
| 190 | The optional \var{safe} parameter is a funtion which generates |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 191 | the cache filename for each URI. A FileCache object is |
jcgregorio | ee542cc | 2006-11-16 04:43:19 +0000 | [diff] [blame] | 192 | constructed and used for caching when you pass a directory name |
| 193 | into the constructor of \class{Http}. |
| 194 | \end{classdesc} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 195 | |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 196 | \begin{classdesc}{ProxyInfo}{proxy_type, proxy_host, proxy_port, \optional{proxy_rdns=None}, \optional{proxy_user=None}, \optional{proxy_pass=None}} |
| 197 | The parameter \var{proxy_type} must be set to one of socks.PROXY_TYPE_XXX |
| 198 | constants. The \var{proxy_host} and \var{proxy_port} must be set to the location |
| 199 | of the proxy. The optional \var{proxy_rdns} should be set to True if |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 200 | the DNS server on the proxy should be used. The \var{proxy_user} and |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 201 | \var{proxy_pass} are supplied when the proxy is protected by authentication. |
| 202 | \end{classdesc} |
| 203 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 204 | |
| 205 | % If your module defines new object types (for a built-in module) or |
| 206 | % classes (for a module written in Python), you should list the |
| 207 | % methods and instance variables (if any) of each type or class in a |
| 208 | % separate subsection. |
| 209 | |
| 210 | \subsection{Http Objects} |
| 211 | \label{http-objects} |
| 212 | % This label is generally useful for referencing this section, but is |
| 213 | % also used to give a filename when generating HTML. |
| 214 | |
| 215 | Http objects have the following methods: |
| 216 | |
jcgregorio | 1464437 | 2007-07-30 14:13:37 +0000 | [diff] [blame] | 217 | \begin{methoddesc}[Http]{request}{uri, \optional{method="GET", body=None, headers=None, redirections=DEFAULT_MAX_REDIRECTS, connection_type=None}} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 218 | Performs a single HTTP request. |
| 219 | The \var{uri} is the URI of the HTTP resource and can begin with either \code{http} or \code{https}. The value of \var{uri} must be an absolute URI. |
| 220 | |
| 221 | The \var{method} is the HTTP method to perform, such as \code{GET}, \code{POST}, \code{DELETE}, etc. There is no restriction |
| 222 | on the methods allowed. |
| 223 | |
| 224 | The \var{body} is the entity body to be sent with the request. It is a string |
| 225 | object. |
| 226 | |
| 227 | Any extra headers that are to be sent with the request should be provided in the |
| 228 | \var{headers} dictionary. |
| 229 | |
| 230 | The maximum number of redirect to follow before raising an exception is \var{redirections}. The default is 5. |
| 231 | |
jcgregorio | 1464437 | 2007-07-30 14:13:37 +0000 | [diff] [blame] | 232 | The \var{connection_type} is the type of connection object to use. The supplied class |
| 233 | should implement the interface of httplib.HTTPConnection. |
| 234 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 235 | The return value is a tuple of (response, content), the first being and instance of the |
| 236 | \class{Response} class, the second being a string that contains the response entity body. |
| 237 | \end{methoddesc} |
| 238 | |
jcgregorio | e6a0196 | 2007-03-09 02:52:48 +0000 | [diff] [blame] | 239 | \begin{methoddesc}[Http]{add_credentials}{name, password, \optional{domain=None}} |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 240 | Adds a name and password that will be used when a request |
jcgregorio | e6a0196 | 2007-03-09 02:52:48 +0000 | [diff] [blame] | 241 | requires authentication. Supplying the optional \var{domain} name will |
| 242 | restrict these credentials to only be sent to the specified |
| 243 | domain. If \var{domain} is not specified then the given credentials will |
| 244 | be used to try to satisfy every HTTP 401 challenge. |
| 245 | \end{methoddesc} |
| 246 | |
| 247 | \begin{methoddesc}[Http]{add_certificate}{key, cert, domain} |
| 248 | Add a \var{key} and \var{cert} that will be used for an SSL connection |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 249 | to the specified domain. \var{keyfile} is the name of a PEM formatted |
| 250 | file that contains your private key. \var{certfile} is a PEM formatted certificate chain file. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 251 | \end{methoddesc} |
| 252 | |
| 253 | \begin{methoddesc}[Http]{clear_credentials}{} |
| 254 | Remove all the names and passwords used for authentication. |
| 255 | \end{methoddesc} |
| 256 | |
jcgregorio | 2f1e142 | 2007-05-03 13:17:33 +0000 | [diff] [blame] | 257 | \begin{memberdesc}[Http]{follow_redirects} |
| 258 | If \code{True}, which is the default, safe redirects are followed, where |
| 259 | safe means that the client is only doing a \code{GET} or \code{HEAD} on the |
| 260 | URI to which it is being redirected. If \code{False} then no redirects are followed. |
| 261 | Note that a False 'follow_redirects' takes precedence over a True 'follow_all_redirects'. |
| 262 | Another way of saying that is for 'follow_all_redirects' to have any affect, 'follow_redirects' |
jcgregorio | 5dc440b | 2007-05-03 13:23:27 +0000 | [diff] [blame] | 263 | must be True. |
jcgregorio | 2f1e142 | 2007-05-03 13:17:33 +0000 | [diff] [blame] | 264 | \end{memberdesc} |
| 265 | |
Joe Gregorio | 0f0f99d | 2012-07-23 14:45:17 -0400 | [diff] [blame] | 266 | \begin{memberdesc}[Http]{forward_authorization_headers} |
| 267 | If \code{False}, which is the default, then Authorization: headers are |
| 268 | stripped from redirects. If \code{True} then Authorization: headers are left |
| 269 | in place when following redirects. This parameter only applies if following |
| 270 | redirects is turned on. Note that turning this on could cause your credentials |
| 271 | to leak, so carefully consider the consequences. |
| 272 | \end{memberdesc} |
| 273 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 274 | \begin{memberdesc}[Http]{follow_all_redirects} |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 275 | If \code{False}, which is the default, only safe redirects are followed, where |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 276 | safe means that the client is only doing a \code{GET} or \code{HEAD} on the |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 277 | URI to which it is being redirected. If \code{True} then all redirects are followed. |
jcgregorio | 5dc440b | 2007-05-03 13:23:27 +0000 | [diff] [blame] | 278 | Note that a False 'follow_redirects' takes precedence over a True 'follow_all_redirects'. |
| 279 | Another way of saying that is for 'follow_all_redirects' to have any affect, 'follow_redirects' |
| 280 | must be True. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 281 | \end{memberdesc} |
| 282 | |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 283 | \begin{memberdesc}[Http]{force_exception_to_status_code} |
| 284 | If \code{True}, which is the default, then no \module{httplib2} exceptions will be thrown. Instead, |
| 285 | those error conditions will be turned into \class{Response} objects |
| 286 | that will be returned normally. |
| 287 | |
| 288 | If \code{False}, then exceptions will be thrown. |
| 289 | \end{memberdesc} |
| 290 | |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 291 | \begin{memberdesc}[Http]{ignore_etag} |
jcgregorio | 87eee73 | 2007-03-09 03:23:11 +0000 | [diff] [blame] | 292 | Defaults to \code{False}. If \code{True}, then any etags present in the cached response |
| 293 | are ignored when processing the current request, i.e. httplib2 does \strong{not} use |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 294 | 'if-match' for PUT or 'if-none-match' when GET or HEAD requests are made. This |
| 295 | is mainly to deal with broken servers which supply an etag, but change it capriciously. |
| 296 | \end{memberdesc} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 297 | |
| 298 | \subsection{Cache Objects} |
| 299 | \label{cache-objects} |
| 300 | % This label is generally useful for referencing this section, but is |
| 301 | % also used to give a filename when generating HTML. |
| 302 | |
| 303 | If you wish to supply your own caching implementation |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 304 | then you will need to pass in an object that supports the |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 305 | following methods. Note that the \module{memcache} module |
| 306 | supports this interface natively. |
| 307 | |
| 308 | \begin{methoddesc}[Cache]{get}{key} |
| 309 | Takes a string \var{key} and returns the value as a string. |
| 310 | \end{methoddesc} |
| 311 | |
| 312 | \begin{methoddesc}[Cache]{set}{key, value} |
| 313 | Takes a string \var{key} and \var{value} and stores it in the cache. |
| 314 | \end{methoddesc} |
| 315 | |
| 316 | \begin{methoddesc}[Cache]{delete}{key} |
| 317 | Deletes the cached value stored at \var{key}. The value |
| 318 | of \var{key} is a string. |
| 319 | \end{methoddesc} |
| 320 | |
| 321 | |
| 322 | |
| 323 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 324 | \subsection{Response Objects} |
| 325 | \label{response-objects} |
| 326 | % This label is generally useful for referencing this section, but is |
| 327 | % also used to give a filename when generating HTML. |
| 328 | |
| 329 | Response objects are derived from \class{dict} and map |
| 330 | header names (lower case with the trailing colon removed) |
| 331 | to header values. In addition to the dict methods |
| 332 | a Response object also has: |
| 333 | |
| 334 | \begin{memberdesc}[Response]{fromcache} |
| 335 | If \code{true} the the response was returned from the cache. |
| 336 | \end{memberdesc} |
| 337 | |
| 338 | \begin{memberdesc}[Response]{version} |
| 339 | The version of HTTP that the server supports. A value |
| 340 | of 11 means '1.1'. |
| 341 | \end{memberdesc} |
| 342 | |
| 343 | \begin{memberdesc}[Response]{status} |
| 344 | The numerical HTTP status code returned in the response. |
| 345 | \end{memberdesc} |
| 346 | |
| 347 | \begin{memberdesc}[Response]{reason} |
| 348 | The human readable component of the HTTP response status code. |
| 349 | \end{memberdesc} |
| 350 | |
| 351 | \begin{memberdesc}[Response]{previous} |
| 352 | If redirects are followed then the \class{Response} object returned |
| 353 | is just for the very last HTTP request and \var{previous} points to |
| 354 | the previous \class{Response} object. In this manner they form a chain |
| 355 | going back through the responses to the very first response. |
| 356 | Will be \code{None} if there are no previous respones. |
| 357 | \end{memberdesc} |
| 358 | |
jcgregorio | 772adc8 | 2006-11-17 21:52:34 +0000 | [diff] [blame] | 359 | The Response object also populates the header \code{content-location}, that |
jcgregorio | f76c951 | 2006-11-07 18:01:50 +0000 | [diff] [blame] | 360 | contains the URI that was ultimately requested. This is useful if |
| 361 | redirects were encountered, you can determine the ultimate URI that |
| 362 | the request was sent to. All Response objects contain this key value, |
| 363 | including \code{previous} responses so you can determine the entire |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 364 | chain of redirects. If \member{Http.force_exception_to_status_code} is \code{True} |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 365 | and the number of redirects has exceeded the number of allowed number |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 366 | of redirects then the \class{Response} object will report the error |
| 367 | in the status code, but the complete chain of previous responses will |
| 368 | still be in tact. |
| 369 | |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 370 | |
| 371 | % ==== 4. ==== |
| 372 | % Now is probably a good time for a complete example. (Alternatively, |
| 373 | % an example giving the flavor of the module may be given before the |
| 374 | % detailed list of functions.) |
| 375 | |
| 376 | \subsection{Examples \label{httplib2-example}} |
| 377 | |
| 378 | To do a simple \code{GET} request just supply the absolute URI |
| 379 | of the resource: |
| 380 | |
| 381 | \begin{verbatim} |
| 382 | import httplib2 |
| 383 | h = httplib2.Http() |
| 384 | resp, content = h.request("http://bitworking.org/") |
| 385 | assert resp.status == 200 |
| 386 | assert resp['content-type'] == 'text/html' |
| 387 | \end{verbatim} |
| 388 | |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 389 | Here is more complex example that does a PUT |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 390 | of some text to a resource that requires authentication. |
| 391 | The Http instance also uses a file cache |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 392 | in the directory \code{.cache}. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 393 | |
| 394 | \begin{verbatim} |
| 395 | import httplib2 |
| 396 | h = httplib2.Http(".cache") |
| 397 | h.add_credentials('name', 'password') |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 398 | resp, content = h.request("https://example.org/chap/2", |
| 399 | "PUT", body="This is text", |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 400 | headers={'content-type':'text/plain'} ) |
| 401 | \end{verbatim} |
| 402 | |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 403 | Here is an example that connects to a server that |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 404 | supports the Atom Publishing Protocol. |
| 405 | |
| 406 | \begin{verbatim} |
| 407 | import httplib2 |
| 408 | h = httplib2.Http() |
| 409 | h.add_credentials(myname, mypasswd) |
| 410 | h.follow_all_redirects = True |
| 411 | headers = {'Content-Type': 'application/atom+xml'} |
| 412 | body = """<?xml version="1.0" ?> |
| 413 | <entry xmlns="http://www.w3.org/2005/Atom"> |
| 414 | <title>Atom-Powered Robots Run Amok</title> |
| 415 | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |
| 416 | <updated>2003-12-13T18:30:02Z</updated> |
| 417 | <author><name>John Doe</name></author> |
| 418 | <content>Some text.</content> |
| 419 | </entry> |
| 420 | """ |
| 421 | uri = "http://www.example.com/collection/" |
| 422 | resp, content = h.request(uri, "POST", body=body, headers=headers) |
| 423 | \end{verbatim} |
| 424 | % Note that there is no trailing ">>> " prompt shown. |
| 425 | |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 426 | Here is an example of providing data to an HTML form processor. |
Joe Gregorio | 2676371 | 2013-02-19 15:57:37 -0500 | [diff] [blame] | 427 | In this case we presume this is a POST form. We need to take our |
| 428 | data and format it as "application/x-www-form-urlencoded" data and use that as a |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 429 | body for a POST request. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 430 | |
jcgregorio | cde4f09 | 2007-03-08 21:59:04 +0000 | [diff] [blame] | 431 | \begin{verbatim} |
| 432 | >>> import httplib2 |
| 433 | >>> import urllib |
| 434 | >>> data = {'name': 'fred', 'address': '123 shady lane'} |
| 435 | >>> body = urllib.urlencode(data) |
| 436 | >>> body |
| 437 | 'name=fred&address=123+shady+lane' |
| 438 | >>> h = httplib2.Http() |
| 439 | >>> resp, content = h.request("http://example.com", method="POST", body=body) |
| 440 | \end{verbatim} |
| 441 | % Note that there is no trailing ">>> " prompt shown. |
joe.gregorio | 5fcc199 | 2007-10-23 15:12:17 +0000 | [diff] [blame] | 442 | |
| 443 | Here is an example of using a proxy server: |
| 444 | \begin{verbatim} |
| 445 | import httplib2 |
| 446 | import socks |
| 447 | |
| 448 | httplib2.debuglevel=4 |
| 449 | h = httplib2.Http(proxy_info = httplib2.ProxyInfo(socks.PROXY_TYPE_HTTP, 'localhost', 8000)) |
| 450 | r,c = h.request("http://bitworking.org/news/") |
| 451 | \end{verbatim} |
| 452 | |
| 453 | |
| 454 | |