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.
  14
  15 \begin{notice}
  16   HTTPS support is only available if the \refmodule{socket} module was
  17   compiled with SSL support.
  18 \end{notice}
  19
  20 \begin{notice}
  21   The public interface for this module changed substantially in Python
  22   2.0.  The \class{HTTP} class is retained only for backward
  23   compatibility with 1.5.2.  It should not be used in new code.  Refer
  24   to the online docstrings for usage.
  25 \end{notice}
  26
  27 The constants defined in this module are:
  28
  29 \begin{datadesc}{HTTP_PORT}
  30   The default port for the HTTP protocol (always \code{80}).
  31 \end{datadesc}
  32
  33 \begin{datadesc}{HTTPS_PORT}
  34   The default port for the HTTPS protocol (always \code{443}).
  35 \end{datadesc}
  36
  37 The module provides the following classes:
  38
  39 \begin{classdesc}{HTTPConnection}{host\optional{, port}}
  40 An \class{HTTPConnection} instance represents one transaction with an HTTP
  41 server.  It should be instantiated passing it a host and optional port number.
  42 If no port number is passed, the port is extracted from the host string if it
  43 has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is
  44 used.  For example, the following calls all create instances that connect to
  45 the server at the same host and port:
  46
  47 \begin{verbatim}
  48 >>> h1 = httplib.HTTPConnection('www.cwi.nl')
  49 >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
  50 >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
  51 \end{verbatim}
  52 \versionadded{2.0}
  53 \end{classdesc}
  54
  55 \begin{classdesc}{HTTPSConnection}{host\optional{, port, key_file, cert_file}}
  56 A subclass of \class{HTTPConnection} that uses SSL for communication with
  57 secure servers.  Default port is \code{443}.
  58 \var{key_file} is
  59 the name of a PEM formatted file that contains your private
  60 key. \var{cert_file} is a PEM formatted certificate chain file.
  61
  62 \warning{This does not do any certificate verification!}
  63
  64 \versionadded{2.0}
  65 \end{classdesc}
  66
  67 \begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}}
  68 Class whose instances are returned upon successful connection.  Not
  69 instantiated directly by user.
  70 \versionadded{2.0}
  71 \end{classdesc}
  72
  73 The following exceptions are raised as appropriate:
  74
  75 \begin{excdesc}{HTTPException}
  76 The base class of the other exceptions in this module.  It is a
  77 subclass of \exception{Exception}.
  78 \versionadded{2.0}
  79 \end{excdesc}
  80
  81 \begin{excdesc}{NotConnected}
  82 A subclass of \exception{HTTPException}.
  83 \versionadded{2.0}
  84 \end{excdesc}
  85
  86 \begin{excdesc}{InvalidURL}
  87 A subclass of \exception{HTTPException}, raised if a port is given and is
  88 either non-numeric or empty.
  89 \versionadded{2.3}
  90 \end{excdesc}
  91
  92 \begin{excdesc}{UnknownProtocol}
  93 A subclass of \exception{HTTPException}.
  94 \versionadded{2.0}
  95 \end{excdesc}
  96
  97 \begin{excdesc}{UnknownTransferEncoding}
  98 A subclass of \exception{HTTPException}.
  99 \versionadded{2.0}
 100 \end{excdesc}
 101
 102 \begin{excdesc}{UnimplementedFileMode}
 103 A subclass of \exception{HTTPException}.
 104 \versionadded{2.0}
 105 \end{excdesc}
 106
 107 \begin{excdesc}{IncompleteRead}
 108 A subclass of \exception{HTTPException}.
 109 \versionadded{2.0}
 110 \end{excdesc}
 111
 112 \begin{excdesc}{ImproperConnectionState}
 113 A subclass of \exception{HTTPException}.
 114 \versionadded{2.0}
 115 \end{excdesc}
 116
 117 \begin{excdesc}{CannotSendRequest}
 118 A subclass of \exception{ImproperConnectionState}.
 119 \versionadded{2.0}
 120 \end{excdesc}
 121
 122 \begin{excdesc}{CannotSendHeader}
 123 A subclass of \exception{ImproperConnectionState}.
 124 \versionadded{2.0}
 125 \end{excdesc}
 126
 127 \begin{excdesc}{ResponseNotReady}
 128 A subclass of \exception{ImproperConnectionState}.
 129 \versionadded{2.0}
 130 \end{excdesc}
 131
 132 \begin{excdesc}{BadStatusLine}
 133 A subclass of \exception{HTTPException}.  Raised if a server responds with a
 134 HTTP status code that we don't understand.
 135 \versionadded{2.0}
 136 \end{excdesc}
 137
 138
 139 \subsection{HTTPConnection Objects \label{httpconnection-objects}}
 140
 141 \class{HTTPConnection} instances have the following methods:
 142
 143 \begin{methoddesc}{request}{method, url\optional{, body\optional{, headers}}}
 144 This will send a request to the server using the HTTP request method
 145 \var{method} and the selector \var{url}.  If the \var{body} argument is
 146 present, it should be a string of data to send after the headers are finished.
 147 The header Content-Length is automatically set to the correct value.
 148 The \var{headers} argument should be a mapping of extra HTTP headers to send
 149 with the request.
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}{getresponse}{}
 153 Should be called after a request is sent to get the response from the server.
 154 Returns an \class{HTTPResponse} instance.
 155 \end{methoddesc}
 156
 157 \begin{methoddesc}{set_debuglevel}{level}
 158 Set the debugging level (the amount of debugging output printed).
 159 The default debug level is \code{0}, meaning no debugging output is
 160 printed.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}{connect}{}
 164 Connect to the server specified when the object was created.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}{close}{}
 168 Close the connection to the server.
 169 \end{methoddesc}
 170
 171 \begin{methoddesc}{send}{data}
 172 Send data to the server.  This should be used directly only after the
 173 \method{endheaders()} method has been called and before
 174 \method{getreply()} has been called.
 175 \end{methoddesc}
 176
 177 \begin{methoddesc}{putrequest}{request, selector\optional{,
 178 skip\_host\optional{, skip_accept_encoding}}}
 179 This should be the first call after the connection to the server has
 180 been made.  It sends a line to the server consisting of the
 181 \var{request} string, the \var{selector} string, and the HTTP version
 182 (\code{HTTP/1.1}).  To disable automatic sending of \code{Host:} or
 183 \code{Accept-Encoding:} headers (for example to accept additional
 184 content encodings), specify \var{skip_host} or \var{skip_accept_encoding}
 185 with non-False values.
 186 \versionchanged[\var{skip_accept_encoding} argument added]{2.4}
 187 \end{methoddesc}
 188
 189 \begin{methoddesc}{putheader}{header, argument\optional{, ...}}
 190 Send an \rfc{822}-style header to the server.  It sends a line to the
 191 server consisting of the header, a colon and a space, and the first
 192 argument.  If more arguments are given, continuation lines are sent,
 193 each consisting of a tab and an argument.
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}{endheaders}{}
 197 Send a blank line to the server, signalling the end of the headers.
 198 \end{methoddesc}
 199
 200
 201 \subsection{HTTPResponse Objects \label{httpresponse-objects}}
 202
 203 \class{HTTPResponse} instances have the following methods and attributes:
 204
 205 \begin{methoddesc}{read}{\optional{amt}}
 206 Reads and returns the response body, or up to the next \var{amt} bytes.
 207 \end{methoddesc}
 208
 209 \begin{methoddesc}{getheader}{name\optional{, default}}
 210 Get the contents of the header \var{name}, or \var{default} if there is no
 211 matching header.
 212 \end{methoddesc}
 213
 214 \begin{datadesc}{msg}
 215   A \class{mimetools.Message} instance containing the response headers.
 216 \end{datadesc}
 217
 218 \begin{datadesc}{version}
 219   HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
 220 \end{datadesc}
 221
 222 \begin{datadesc}{status}
 223   Status code returned by server.
 224 \end{datadesc}
 225
 226 \begin{datadesc}{reason}
 227   Reason phrase returned by server.
 228 \end{datadesc}
 229
 230
 231 \subsection{Examples \label{httplib-examples}}
 232
 233 Here is an example session that uses the \samp{GET} method:
 234
 235 \begin{verbatim}
 236 >>> import httplib
 237 >>> conn = httplib.HTTPConnection("www.python.org")
 238 >>> conn.request("GET", "/index.html")
 239 >>> r1 = conn.getresponse()
 240 >>> print r1.status, r1.reason
 241 200 OK
 242 >>> data1 = r1.read()
 243 >>> conn.request("GET", "/parrot.spam")
 244 >>> r2 = conn.getresponse()
 245 >>> print r2.status, r2.reason
 246 404 Not Found
 247 >>> data2 = r2.read()
 248 >>> conn.close()
 249 \end{verbatim}
 250
 251 Here is an example session that shows how to \samp{POST} requests:
 252
 253 \begin{verbatim}
 254 >>> import httplib, urllib
 255 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
 256 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
 257 ...            "Accept": "text/plain"}
 258 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
 259 >>> conn.request("POST", "/cgi-bin/query", params, headers)
 260 >>> response = conn.getresponse()
 261 >>> print response.status, response.reason
 262 200 OK
 263 >>> data = response.read()
 264 >>> conn.close()
 265 \end{verbatim}