Doc/lib/libhttplib.tex

   1 \section{\module{httplib} ---
   2          HTTP protocol client}
   3
   4 \declaremodule{standard}{httplib}
   5 \modulesynopsis{HTTP and HTTPS protocol client (requires sockets).}
   6
   7 \indexii{HTTP}{protocol}
   8 \index{HTTP!\module{httplib} (standard module)}
   9
  10 This module defines classes which implement the client side of the
  11 HTTP and HTTPS protocols.  It is normally not used directly --- the
  12 module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs
  13 that use HTTP and HTTPS.  \note{HTTPS support is only
  14 available if the \refmodule{socket} module was compiled with SSL
  15 support.}
  16
  17 The constants defined in this module are:
  18
  19 \begin{datadesc}{HTTP_PORT}
  20   The default port for the HTTP protocol (always \code{80}).
  21 \end{datadesc}
  22
  23 \begin{datadesc}{HTTPS_PORT}
  24   The default port for the HTTPS protocol (always \code{443}).
  25 \end{datadesc}
  26
  27 The module provides the following classes:
  28
  29 \begin{classdesc}{HTTPConnection}{host\optional{, port}}
  30 An \class{HTTPConnection} instance represents one transaction with an HTTP
  31 server.  It should be instantiated passing it a host and optional port number.
  32 If no port number is passed, the port is extracted from the host string if it
  33 has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is
  34 used.  For example, the following calls all create instances that connect to
  35 the server at the same host and port:
  36
  37 \begin{verbatim}
  38 >>> h1 = httplib.HTTPConnection('www.cwi.nl')
  39 >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
  40 >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
  41 \end{verbatim}
  42 \end{classdesc}
  43
  44 \begin{classdesc}{HTTPSConnection}{host\optional{, port}}
  45 A subclass of \class{HTTPConnection} that uses SSL for communication with
  46 secure servers.  Default port is \code{443}.
  47 \end{classdesc}
  48
  49 The following exceptions are raised as appropriate:
  50
  51 \begin{excdesc}{HTTPException}
  52 The base class of the other exceptions in this module.  It is a
  53 subclass of \exception{Exception}.
  54 \end{excdesc}
  55
  56 \begin{excdesc}{NotConnected}
  57 A subclass of \exception{HTTPException}.
  58 \end{excdesc}
  59
  60 \begin{excdesc}{InvalidURL}
  61 A subclass of \exception{HTTPException}, raised if a port is given and is
  62 either non-numeric or empty.
  63 \end{excdesc}
  64
  65 \begin{excdesc}{UnknownProtocol}
  66 A subclass of \exception{HTTPException}.
  67 \end{excdesc}
  68
  69 \begin{excdesc}{UnknownTransferEncoding}
  70 A subclass of \exception{HTTPException}.
  71 \end{excdesc}
  72
  73 \begin{excdesc}{IllegalKeywordArgument}
  74 A subclass of \exception{HTTPException}.
  75 \end{excdesc}
  76
  77 \begin{excdesc}{UnimplementedFileMode}
  78 A subclass of \exception{HTTPException}.
  79 \end{excdesc}
  80
  81 \begin{excdesc}{IncompleteRead}
  82 A subclass of \exception{HTTPException}.
  83 \end{excdesc}
  84
  85 \begin{excdesc}{ImproperConnectionState}
  86 A subclass of \exception{HTTPException}.
  87 \end{excdesc}
  88
  89 \begin{excdesc}{CannotSendRequest}
  90 A subclass of \exception{ImproperConnectionState}.
  91 \end{excdesc}
  92
  93 \begin{excdesc}{CannotSendHeader}
  94 A subclass of \exception{ImproperConnectionState}.
  95 \end{excdesc}
  96
  97 \begin{excdesc}{ResponseNotReady}
  98 A subclass of \exception{ImproperConnectionState}.
  99 \end{excdesc}
 100
 101 \begin{excdesc}{BadStatusLine}
 102 A subclass of \exception{HTTPException}.  Raised if a server responds with a
 103 HTTP status code that we don't understand.
 104 \end{excdesc}
 105
 106
 107 \subsection{HTTPConnection Objects \label{httpconnection-objects}}
 108
 109 \class{HTTPConnection} instances have the following methods:
 110
 111 \begin{methoddesc}{request}{method, url\optional{, body\optional{, headers}}}
 112 This will send a request to the server using the HTTP request method
 113 \var{method} and the selector \var{url}.  If the \var{body} argument is
 114 present, it should be a string of data to send after the headers are finished.
 115 The header Content-Length is automatically set to the correct value.
 116 The \var{headers} argument should be a mapping of extra HTTP headers to send
 117 with the request.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}{getresponse}{}
 121 Should be called after a request is sent to get the response from the server.
 122 Returns an \class{HTTPResponse} instance.
 123 \end{methoddesc}
 124
 125 \begin{methoddesc}{set_debuglevel}{level}
 126 Set the debugging level (the amount of debugging output printed).
 127 The default debug level is \code{0}, meaning no debugging output is
 128 printed.
 129 \end{methoddesc}
 130
 131 \begin{methoddesc}{connect}{}
 132 Connect to the server specified when the object was created.
 133 \end{methoddesc}
 134
 135 \begin{methoddesc}{close}{}
 136 Close the connection to the server.
 137 \end{methoddesc}
 138
 139 \begin{methoddesc}{send}{data}
 140 Send data to the server.  This should be used directly only after the
 141 \method{endheaders()} method has been called and before
 142 \method{getreply()} has been called.
 143 \end{methoddesc}
 144
 145 \begin{methoddesc}{putrequest}{request, selector}
 146 This should be the first call after the connection to the server has
 147 been made.  It sends a line to the server consisting of the
 148 \var{request} string, the \var{selector} string, and the HTTP version
 149 (\code{HTTP/1.1}).
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}{putheader}{header, argument\optional{, ...}}
 153 Send an \rfc{822}-style header to the server.  It sends a line to the
 154 server consisting of the header, a colon and a space, and the first
 155 argument.  If more arguments are given, continuation lines are sent,
 156 each consisting of a tab and an argument.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}{endheaders}{}
 160 Send a blank line to the server, signalling the end of the headers.
 161 \end{methoddesc}
 162
 163
 164 \subsection{HTTPResponse Objects \label{httpresponse-objects}}
 165
 166 \class{HTTPResponse} instances have the following methods and attributes:
 167
 168 \begin{methoddesc}{read}{}
 169 Reads and returns the response body.
 170 \end{methoddesc}
 171
 172 \begin{methoddesc}{getheader}{name\optional{, default}}
 173 Get the contents of the header \var{name}, or \var{default} if there is no
 174 matching header.
 175 \end{methoddesc}
 176
 177 \begin{datadesc}{msg}
 178   A \class{mimetools.Message} instance containing the response headers.
 179 \end{datadesc}
 180
 181 \begin{datadesc}{version}
 182   HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
 183 \end{datadesc}
 184
 185 \begin{datadesc}{status}
 186   Status code returned by server.
 187 \end{datadesc}
 188
 189 \begin{datadesc}{reason}
 190   Reason phrase returned by server.
 191 \end{datadesc}
 192
 193
 194 \subsection{Examples \label{httplib-examples}}
 195
 196 Here is an example session that uses the \samp{GET} method:
 197
 198 \begin{verbatim}
 199 >>> import httplib
 200 >>> conn = httplib.HTTPConnection("www.python.org")
 201 >>> conn.request("GET", "/index.html")
 202 >>> r1 = conn.getresponse()
 203 >>> print r1.status, r1.reason
 204 200 OK
 205 >>> data1 = r1.read()
 206 >>> conn.request("GET", "/parrot.spam")
 207 >>> r2 = conn.getresponse()
 208 >>> print r2.status, r2.reason
 209 404 Not Found
 210 >>> data2 = r2.read()
 211 >>> conn.close()
 212 \end{verbatim}
 213
 214 Here is an example session that shows how to \samp{POST} requests:
 215
 216 \begin{verbatim}
 217 >>> import httplib, urllib
 218 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
 219 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
 220 ...            "Accept": "text/plain"}
 221 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
 222 >>> conn.request("POST", "/cgi-bin/query", params, headers)
 223 >>> response = conn.getresponse()
 224 >>> print response.status, response.reason
 225 200 OK
 226 >>> data = response.read()
 227 >>> conn.close()
 228 \end{verbatim}