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 60The \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[Proxies] 80 If the Socksipy module is installed then httplib2 can handle sock4, sock5 and http proxies. 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 91The \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} 97The amount of debugging information to print. The default is 0. 98\end{datadesc} 99 100\begin{datadesc}{RETRIES} 101A request will be tried 'RETRIES' times if it fails at the socket/connection level. 102The default is 2. 103\end{datadesc} 104 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 111The \module{httplib2} module may raise the following Exceptions. Note that 112there is an option that turns exceptions into 113normal responses with an HTTP status code indicating 114an error occured. See \member{Http.force_exception_to_status_code} 115 116\begin{excdesc}{HttpLib2Error} 117The Base Exception for all exceptions raised by httplib2. 118\end{excdesc} 119 120\begin{excdesc}{RedirectMissingLocation} 121A 3xx redirect response code was provided but no Location: header 122was provided to point to the new location. 123\end{excdesc} 124 125\begin{excdesc}{RedirectLimit} 126The maximum number of redirections was reached without coming to a final URI. 127\end{excdesc} 128 129 130\begin{excdesc}{ServerNotFoundError} 131Unable to resolve the host name given. 132\end{excdesc} 133 134\begin{excdesc}{RelativeURIError} 135A relative, as opposed to an absolute URI, was passed into request(). 136\end{excdesc} 137 138\begin{excdesc}{FailedToDecompressContent} 139The headers claimed that the content of the response was compressed but the 140decompression algorithm applied to the content failed. 141\end{excdesc} 142 143\begin{excdesc}{UnimplementedDigestAuthOptionError} 144The server requested a type of Digest authentication that we 145are unfamiliar with. 146\end{excdesc} 147 148\begin{excdesc}{UnimplementedHmacDigestAuthOptionError} 149The server requested a type of HMACDigest authentication that we 150are unfamiliar with. 151\end{excdesc} 152 153% ---- 3.4. ---- 154% Other standard environments: 155% 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. 166 167\begin{classdesc}{Http}{\optional{cache=None}, \optional{timeout=None}, \optional{proxy_info=None}} 168The class that represents a client HTTP interface. 169The \var{cache} parameter is either the name of a directory 170to be used as a flat file cache, or it must an object that 171implements the required caching interface. 172The \var{timeout} parameter is the socket level timeout. 173The \var{proxy_info} is an instance of \class{ProxyInfo} and is supplied 174if a proxy is to be used. Note that the Socksipy module must be 175installed for proxy support to work. 176\end{classdesc} 177 178\begin{classdesc}{Response}{info} 179Response is a subclass of \class{dict} and instances of this 180class are returned from calls 181to Http.request. The \var{info} parameter is either 182an \class{rfc822.Message} or an \class{httplib.HTTPResponse} object. 183\end{classdesc} 184 185\begin{classdesc}{FileCache}{dir_name, \optional{safe=safename}} 186FileCache implements a Cache as a directory of files. 187The \var{dir_name} parameter is 188the name of the directory to use. If the directory does 189not exist then FileCache attempts to create the directory. 190The optional \var{safe} parameter is a funtion which generates 191the cache filename for each URI. A FileCache object is 192constructed and used for caching when you pass a directory name 193into the constructor of \class{Http}. 194\end{classdesc} 195 196\begin{classdesc}{ProxyInfo}{proxy_type, proxy_host, proxy_port, \optional{proxy_rdns=None}, \optional{proxy_user=None}, \optional{proxy_pass=None}} 197The parameter \var{proxy_type} must be set to one of socks.PROXY_TYPE_XXX 198constants. The \var{proxy_host} and \var{proxy_port} must be set to the location 199of the proxy. The optional \var{proxy_rdns} should be set to True if 200the DNS server on the proxy should be used. The \var{proxy_user} and 201\var{proxy_pass} are supplied when the proxy is protected by authentication. 202\end{classdesc} 203 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 215Http objects have the following methods: 216 217\begin{methoddesc}[Http]{request}{uri, \optional{method="GET", body=None, headers=None, redirections=DEFAULT_MAX_REDIRECTS, connection_type=None}} 218Performs a single HTTP request. 219The \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 221The \var{method} is the HTTP method to perform, such as \code{GET}, \code{POST}, \code{DELETE}, etc. There is no restriction 222on the methods allowed. 223 224The \var{body} is the entity body to be sent with the request. It is a string 225object. 226 227Any extra headers that are to be sent with the request should be provided in the 228\var{headers} dictionary. 229 230The maximum number of redirect to follow before raising an exception is \var{redirections}. The default is 5. 231 232The \var{connection_type} is the type of connection object to use. The supplied class 233should implement the interface of httplib.HTTPConnection. 234 235The 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 239\begin{methoddesc}[Http]{add_credentials}{name, password, \optional{domain=None}} 240Adds a name and password that will be used when a request 241requires authentication. Supplying the optional \var{domain} name will 242restrict these credentials to only be sent to the specified 243domain. If \var{domain} is not specified then the given credentials will 244be used to try to satisfy every HTTP 401 challenge. 245\end{methoddesc} 246 247\begin{methoddesc}[Http]{add_certificate}{key, cert, domain} 248Add a \var{key} and \var{cert} that will be used for an SSL connection 249to the specified domain. \var{keyfile} is the name of a PEM formatted 250file that contains your private key. \var{certfile} is a PEM formatted certificate chain file. 251\end{methoddesc} 252 253\begin{methoddesc}[Http]{clear_credentials}{} 254Remove all the names and passwords used for authentication. 255\end{methoddesc} 256 257\begin{memberdesc}[Http]{follow_redirects} 258If \code{True}, which is the default, safe redirects are followed, where 259safe means that the client is only doing a \code{GET} or \code{HEAD} on the 260URI to which it is being redirected. If \code{False} then no redirects are followed. 261Note that a False 'follow_redirects' takes precedence over a True 'follow_all_redirects'. 262Another way of saying that is for 'follow_all_redirects' to have any affect, 'follow_redirects' 263must be True. 264\end{memberdesc} 265 266\begin{memberdesc}[Http]{forward_authorization_headers} 267If \code{False}, which is the default, then Authorization: headers are 268stripped from redirects. If \code{True} then Authorization: headers are left 269in place when following redirects. This parameter only applies if following 270redirects is turned on. Note that turning this on could cause your credentials 271to leak, so carefully consider the consequences. 272\end{memberdesc} 273 274\begin{memberdesc}[Http]{follow_all_redirects} 275If \code{False}, which is the default, only safe redirects are followed, where 276safe means that the client is only doing a \code{GET} or \code{HEAD} on the 277URI to which it is being redirected. If \code{True} then all redirects are followed. 278Note that a False 'follow_redirects' takes precedence over a True 'follow_all_redirects'. 279Another way of saying that is for 'follow_all_redirects' to have any affect, 'follow_redirects' 280must be True. 281\end{memberdesc} 282 283\begin{memberdesc}[Http]{force_exception_to_status_code} 284If \code{True}, which is the default, then no \module{httplib2} exceptions will be thrown. Instead, 285those error conditions will be turned into \class{Response} objects 286that will be returned normally. 287 288If \code{False}, then exceptions will be thrown. 289\end{memberdesc} 290 291\begin{memberdesc}[Http]{ignore_etag} 292Defaults to \code{False}. If \code{True}, then any etags present in the cached response 293are ignored when processing the current request, i.e. httplib2 does \strong{not} use 294'if-match' for PUT or 'if-none-match' when GET or HEAD requests are made. This 295is mainly to deal with broken servers which supply an etag, but change it capriciously. 296\end{memberdesc} 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 303If you wish to supply your own caching implementation 304then you will need to pass in an object that supports the 305following methods. Note that the \module{memcache} module 306supports this interface natively. 307 308\begin{methoddesc}[Cache]{get}{key} 309Takes a string \var{key} and returns the value as a string. 310\end{methoddesc} 311 312\begin{methoddesc}[Cache]{set}{key, value} 313Takes a string \var{key} and \var{value} and stores it in the cache. 314\end{methoddesc} 315 316\begin{methoddesc}[Cache]{delete}{key} 317Deletes the cached value stored at \var{key}. The value 318of \var{key} is a string. 319\end{methoddesc} 320 321 322 323 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 329Response objects are derived from \class{dict} and map 330header names (lower case with the trailing colon removed) 331to header values. In addition to the dict methods 332a Response object also has: 333 334\begin{memberdesc}[Response]{fromcache} 335If \code{true} the the response was returned from the cache. 336\end{memberdesc} 337 338\begin{memberdesc}[Response]{version} 339The version of HTTP that the server supports. A value 340of 11 means '1.1'. 341\end{memberdesc} 342 343\begin{memberdesc}[Response]{status} 344The numerical HTTP status code returned in the response. 345\end{memberdesc} 346 347\begin{memberdesc}[Response]{reason} 348The human readable component of the HTTP response status code. 349\end{memberdesc} 350 351\begin{memberdesc}[Response]{previous} 352If redirects are followed then the \class{Response} object returned 353is just for the very last HTTP request and \var{previous} points to 354the previous \class{Response} object. In this manner they form a chain 355going back through the responses to the very first response. 356Will be \code{None} if there are no previous respones. 357\end{memberdesc} 358 359The Response object also populates the header \code{content-location}, that 360contains the URI that was ultimately requested. This is useful if 361redirects were encountered, you can determine the ultimate URI that 362the request was sent to. All Response objects contain this key value, 363including \code{previous} responses so you can determine the entire 364chain of redirects. If \member{Http.force_exception_to_status_code} is \code{True} 365and the number of redirects has exceeded the number of allowed number 366of redirects then the \class{Response} object will report the error 367in the status code, but the complete chain of previous responses will 368still be in tact. 369 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 378To do a simple \code{GET} request just supply the absolute URI 379of the resource: 380 381\begin{verbatim} 382import httplib2 383h = httplib2.Http() 384resp, content = h.request("http://bitworking.org/") 385assert resp.status == 200 386assert resp['content-type'] == 'text/html' 387\end{verbatim} 388 389Here is more complex example that does a PUT 390of some text to a resource that requires authentication. 391The Http instance also uses a file cache 392in the directory \code{.cache}. 393 394\begin{verbatim} 395import httplib2 396h = httplib2.Http(".cache") 397h.add_credentials('name', 'password') 398resp, content = h.request("https://example.org/chap/2", 399 "PUT", body="This is text", 400 headers={'content-type':'text/plain'} ) 401\end{verbatim} 402 403Here is an example that connects to a server that 404supports the Atom Publishing Protocol. 405 406\begin{verbatim} 407import httplib2 408h = httplib2.Http() 409h.add_credentials(myname, mypasswd) 410h.follow_all_redirects = True 411headers = {'Content-Type': 'application/atom+xml'} 412body = """<?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""" 421uri = "http://www.example.com/collection/" 422resp, content = h.request(uri, "POST", body=body, headers=headers) 423\end{verbatim} 424% Note that there is no trailing ">>> " prompt shown. 425 426Here is an example of providing data to an HTML form processor. 427In this case we presume this is a POST form. We need to take our 428data and format it as "application/x-www-form-urlencoded" data and use that as a 429body for a POST request. 430 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. 442 443Here is an example of using a proxy server: 444\begin{verbatim} 445import httplib2 446import socks 447 448httplib2.debuglevel=4 449h = httplib2.Http(proxy_info = httplib2.ProxyInfo(socks.PROXY_TYPE_HTTP, 'localhost', 8000)) 450r,c = h.request("http://bitworking.org/news/") 451\end{verbatim} 452 453 454 455