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 | |
| 23 | \section{\module{httplib2} |
| 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 | % |
| 30 | \declaremodule{}{httplib2} % not standard, in Python |
| 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 | |
| 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. |
| 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} |
| 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. |
| 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] |
| 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. |
| 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. |
| 79 | \item[Lost update support] |
| 80 | 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 |
| 81 | \end{description} |
| 82 | |
| 83 | % ==== 3. ==== |
| 84 | % List the public functions defined by the module. Begin with a |
| 85 | % standard phrase. You may also list the exceptions and other data |
| 86 | % items defined in the module, insofar as they are important for the |
| 87 | % user. |
| 88 | |
| 89 | The \module{httplib2} module defines the following variables: |
| 90 | % ---- 3.2. ---- |
| 91 | % Data items are described using a ``datadesc'' block. This has only |
| 92 | % one parameter: the item's name. |
| 93 | |
| 94 | \begin{datadesc}{debuglevel} |
| 95 | The amount of debugging information to print. The default is 0. |
| 96 | \end{datadesc} |
| 97 | |
| 98 | % --- 3.3. --- |
| 99 | % Exceptions are described using a ``excdesc'' block. This has only |
| 100 | % one parameter: the exception name. Exceptions defined as classes in |
| 101 | % the source code should be documented using this environment, but |
| 102 | % constructor parameters must be omitted. |
| 103 | |
| 104 | The \module{httplib2} module may raise the following Exceptions: |
| 105 | |
| 106 | \begin{excdesc}{HttpLib2Error} |
| 107 | The Base Exception for all exceptions raised by httplib2. |
| 108 | \end{excdesc} |
| 109 | |
| 110 | \begin{excdesc}{RedirectMissingLocation} |
| 111 | A 3xx redirect response code was provided but no Location: header |
| 112 | was provided to point to the new location. |
| 113 | \end{excdesc} |
| 114 | |
| 115 | |
| 116 | \begin{excdesc}{RedirectLimit} |
| 117 | The maximum number of redirections was reached without coming to a final URI. |
| 118 | \end{excdesc} |
| 119 | |
| 120 | |
| 121 | \begin{excdesc}{FailedToDecompressContent} |
| 122 | The headers claimed that the content of the response was compressed but the |
| 123 | decompression algorithm applied to the content failed. |
| 124 | \end{excdesc} |
| 125 | |
| 126 | |
| 127 | \begin{excdesc}{UnimplementedDigestAuthOptionError} |
| 128 | The server requested a type of Digest authentication that we |
| 129 | are unfamiliar with. |
| 130 | \end{excdesc} |
| 131 | |
| 132 | \begin{excdesc}{UnimplementedHmacDigestAuthOptionError} |
| 133 | The server requested a type of HMACDigest authentication that we |
| 134 | are unfamiliar with. |
| 135 | \end{excdesc} |
| 136 | |
| 137 | % ---- 3.4. ---- |
| 138 | % Other standard environments: |
| 139 | % |
| 140 | % classdesc - Python classes; same arguments are funcdesc |
| 141 | % methoddesc - methods, like funcdesc but has an optional parameter |
| 142 | % to give the type name: \begin{methoddesc}[mytype]{name}{args} |
| 143 | % By default, the type name will be the name of the |
| 144 | % last class defined using classdesc. The type name |
| 145 | % is required if the type is implemented in C (because |
| 146 | % there's no classdesc) or if the class isn't directly |
| 147 | % documented (if it's private). |
| 148 | % memberdesc - data members, like datadesc, but with an optional |
| 149 | % type name like methoddesc. |
| 150 | |
| 151 | \begin{classdesc}{Http}{\optional{cache=None}} |
| 152 | The class that represents a client HTTP interface. |
| 153 | The \var{cache} parameter is either the name of a directory |
| 154 | to be used as a flat file cache, or it must an object that |
| 155 | implements the required caching interface. |
| 156 | \end{classdesc} |
| 157 | |
| 158 | \begin{classdesc}{Response}{info} |
| 159 | Response is a subclass of \class{dict} and instances of this |
| 160 | class are returned from calls |
| 161 | to Http.request. The \var{info} parameter is either |
| 162 | an \class{rfc822.Message} or an \class{httplib.HTTPResponse} object. |
| 163 | \end{classdesc} |
| 164 | |
jcgregorio | ee542cc | 2006-11-16 04:43:19 +0000 | [diff] [blame] | 165 | \begin{classdesc}{FileCache}{dir_name, \optional{safe=safename}} |
| 166 | FileCache implements a Cache as a directory of files. |
| 167 | The \var{dir_name} parameter is |
| 168 | the name of the directory to use. If the directory does |
| 169 | not exist then FileCache attempts to create the directory. |
| 170 | The optional \var{safe} parameter is a funtion which generates |
| 171 | the cache filename for each URI. A FileCache object is |
| 172 | constructed and used for caching when you pass a directory name |
| 173 | into the constructor of \class{Http}. |
| 174 | \end{classdesc} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 175 | |
| 176 | |
| 177 | % If your module defines new object types (for a built-in module) or |
| 178 | % classes (for a module written in Python), you should list the |
| 179 | % methods and instance variables (if any) of each type or class in a |
| 180 | % separate subsection. |
| 181 | |
| 182 | \subsection{Http Objects} |
| 183 | \label{http-objects} |
| 184 | % This label is generally useful for referencing this section, but is |
| 185 | % also used to give a filename when generating HTML. |
| 186 | |
| 187 | Http objects have the following methods: |
| 188 | |
| 189 | \begin{methoddesc}[Http]{request}{uri, \optional{method="GET", body=None, headers=None, redirections=DEFAULT_MAX_REDIRECTS}} |
| 190 | Performs a single HTTP request. |
| 191 | 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. |
| 192 | |
| 193 | The \var{method} is the HTTP method to perform, such as \code{GET}, \code{POST}, \code{DELETE}, etc. There is no restriction |
| 194 | on the methods allowed. |
| 195 | |
| 196 | The \var{body} is the entity body to be sent with the request. It is a string |
| 197 | object. |
| 198 | |
| 199 | Any extra headers that are to be sent with the request should be provided in the |
| 200 | \var{headers} dictionary. |
| 201 | |
| 202 | The maximum number of redirect to follow before raising an exception is \var{redirections}. The default is 5. |
| 203 | |
| 204 | The return value is a tuple of (response, content), the first being and instance of the |
| 205 | \class{Response} class, the second being a string that contains the response entity body. |
| 206 | \end{methoddesc} |
| 207 | |
| 208 | \begin{methoddesc}[Http]{add_credentials}{name, password} |
| 209 | Adds a name and password that will be used when a request |
| 210 | requires authentication. |
| 211 | \end{methoddesc} |
| 212 | |
| 213 | \begin{methoddesc}[Http]{clear_credentials}{} |
| 214 | Remove all the names and passwords used for authentication. |
| 215 | \end{methoddesc} |
| 216 | |
| 217 | \begin{memberdesc}[Http]{follow_all_redirects} |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 218 | If \code{False}, which is the default, only safe redirects are followed, where |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 219 | 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] | 220 | URI to which it is being redirected. If \code{True} then all redirects are followed. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 221 | \end{memberdesc} |
| 222 | |
jcgregorio | 2518562 | 2006-10-28 05:12:34 +0000 | [diff] [blame] | 223 | \begin{memberdesc}[Http]{ignore_etag} |
| 224 | Defaults to \code{False}. If True, then any etags present in the cached response |
| 225 | are ignored when processing the current request, i.e. httplib2 does *not* use |
| 226 | 'if-match' for PUT or 'if-none-match' when GET or HEAD requests are made. This |
| 227 | is mainly to deal with broken servers which supply an etag, but change it capriciously. |
| 228 | \end{memberdesc} |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 229 | |
| 230 | \subsection{Cache Objects} |
| 231 | \label{cache-objects} |
| 232 | % This label is generally useful for referencing this section, but is |
| 233 | % also used to give a filename when generating HTML. |
| 234 | |
| 235 | If you wish to supply your own caching implementation |
| 236 | then you will need to pass in an object that supports the |
| 237 | following methods. Note that the \module{memcache} module |
| 238 | supports this interface natively. |
| 239 | |
| 240 | \begin{methoddesc}[Cache]{get}{key} |
| 241 | Takes a string \var{key} and returns the value as a string. |
| 242 | \end{methoddesc} |
| 243 | |
| 244 | \begin{methoddesc}[Cache]{set}{key, value} |
| 245 | Takes a string \var{key} and \var{value} and stores it in the cache. |
| 246 | \end{methoddesc} |
| 247 | |
| 248 | \begin{methoddesc}[Cache]{delete}{key} |
| 249 | Deletes the cached value stored at \var{key}. The value |
| 250 | of \var{key} is a string. |
| 251 | \end{methoddesc} |
| 252 | |
| 253 | |
| 254 | |
| 255 | |
| 256 | |
| 257 | \subsection{Response Objects} |
| 258 | \label{response-objects} |
| 259 | % This label is generally useful for referencing this section, but is |
| 260 | % also used to give a filename when generating HTML. |
| 261 | |
| 262 | Response objects are derived from \class{dict} and map |
| 263 | header names (lower case with the trailing colon removed) |
| 264 | to header values. In addition to the dict methods |
| 265 | a Response object also has: |
| 266 | |
| 267 | \begin{memberdesc}[Response]{fromcache} |
| 268 | If \code{true} the the response was returned from the cache. |
| 269 | \end{memberdesc} |
| 270 | |
| 271 | \begin{memberdesc}[Response]{version} |
| 272 | The version of HTTP that the server supports. A value |
| 273 | of 11 means '1.1'. |
| 274 | \end{memberdesc} |
| 275 | |
| 276 | \begin{memberdesc}[Response]{status} |
| 277 | The numerical HTTP status code returned in the response. |
| 278 | \end{memberdesc} |
| 279 | |
| 280 | \begin{memberdesc}[Response]{reason} |
| 281 | The human readable component of the HTTP response status code. |
| 282 | \end{memberdesc} |
| 283 | |
| 284 | \begin{memberdesc}[Response]{previous} |
| 285 | If redirects are followed then the \class{Response} object returned |
| 286 | is just for the very last HTTP request and \var{previous} points to |
| 287 | the previous \class{Response} object. In this manner they form a chain |
| 288 | going back through the responses to the very first response. |
| 289 | Will be \code{None} if there are no previous respones. |
| 290 | \end{memberdesc} |
| 291 | |
jcgregorio | 772adc8 | 2006-11-17 21:52:34 +0000 | [diff] [blame] | 292 | The Response object also populates the header \code{content-location}, that |
jcgregorio | f76c951 | 2006-11-07 18:01:50 +0000 | [diff] [blame] | 293 | contains the URI that was ultimately requested. This is useful if |
| 294 | redirects were encountered, you can determine the ultimate URI that |
| 295 | the request was sent to. All Response objects contain this key value, |
| 296 | including \code{previous} responses so you can determine the entire |
| 297 | chain of redirects. |
jcgregorio | 26c0cd7 | 2006-07-03 17:36:17 +0000 | [diff] [blame] | 298 | |
| 299 | % ==== 4. ==== |
| 300 | % Now is probably a good time for a complete example. (Alternatively, |
| 301 | % an example giving the flavor of the module may be given before the |
| 302 | % detailed list of functions.) |
| 303 | |
| 304 | \subsection{Examples \label{httplib2-example}} |
| 305 | |
| 306 | To do a simple \code{GET} request just supply the absolute URI |
| 307 | of the resource: |
| 308 | |
| 309 | \begin{verbatim} |
| 310 | import httplib2 |
| 311 | h = httplib2.Http() |
| 312 | resp, content = h.request("http://bitworking.org/") |
| 313 | assert resp.status == 200 |
| 314 | assert resp['content-type'] == 'text/html' |
| 315 | \end{verbatim} |
| 316 | |
| 317 | Here is more complex example that does a PUT |
| 318 | of some text to a resource that requires authentication. |
| 319 | The Http instance also uses a file cache |
| 320 | in the directory \code{.cache}. |
| 321 | |
| 322 | \begin{verbatim} |
| 323 | import httplib2 |
| 324 | h = httplib2.Http(".cache") |
| 325 | h.add_credentials('name', 'password') |
| 326 | resp, content = h.request("https://example.org/chap/2", |
| 327 | "PUT", body="This is text", |
| 328 | headers={'content-type':'text/plain'} ) |
| 329 | \end{verbatim} |
| 330 | |
| 331 | Here is an example that connects to a server that |
| 332 | supports the Atom Publishing Protocol. |
| 333 | |
| 334 | \begin{verbatim} |
| 335 | import httplib2 |
| 336 | h = httplib2.Http() |
| 337 | h.add_credentials(myname, mypasswd) |
| 338 | h.follow_all_redirects = True |
| 339 | headers = {'Content-Type': 'application/atom+xml'} |
| 340 | body = """<?xml version="1.0" ?> |
| 341 | <entry xmlns="http://www.w3.org/2005/Atom"> |
| 342 | <title>Atom-Powered Robots Run Amok</title> |
| 343 | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |
| 344 | <updated>2003-12-13T18:30:02Z</updated> |
| 345 | <author><name>John Doe</name></author> |
| 346 | <content>Some text.</content> |
| 347 | </entry> |
| 348 | """ |
| 349 | uri = "http://www.example.com/collection/" |
| 350 | resp, content = h.request(uri, "POST", body=body, headers=headers) |
| 351 | \end{verbatim} |
| 352 | % Note that there is no trailing ">>> " prompt shown. |
| 353 | |
| 354 | |