Doc/lib/libhttplib.tex

   1 \section{\module{httplib} ---
   2          HTTP protocol client}
   3
   4 \declaremodule{standard}{httplib}
   5 \modulesynopsis{HTTP protocol client (requires sockets).}
   6
   7 \indexii{HTTP}{protocol}
   8
   9 This module defines a class which implements the client side of the
  10 HTTP protocol.  It is normally not used directly --- the module
  11 \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs that
  12 use HTTP.
  13
  14 The module defines one class, \class{HTTP}:
  15
  16 \begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
  17 An \class{HTTP} instance
  18 represents one transaction with an HTTP server.  It should be
  19 instantiated passing it a host and optional port number.  If no port
  20 number is passed, the port is extracted from the host string if it has
  21 the form \code{\var{host}:\var{port}}, else the default HTTP port (80)
  22 is used.  If no host is passed, no connection is made, and the
  23 \method{connect()} method should be used to connect to a server.  For
  24 example, the following calls all create instances that connect to the
  25 server at the same host and port:
  26
  27 \begin{verbatim}
  28 >>> h1 = httplib.HTTP('www.cwi.nl')
  29 >>> h2 = httplib.HTTP('www.cwi.nl:80')
  30 >>> h3 = httplib.HTTP('www.cwi.nl', 80)
  31 \end{verbatim}
  32
  33 Once an \class{HTTP} instance has been connected to an HTTP server, it
  34 should be used as follows:
  35
  36 \begin{enumerate}
  37
  38 \item[1.] Make exactly one call to the \method{putrequest()} method.
  39
  40 \item[2.] Make zero or more calls to the \method{putheader()} method.
  41
  42 \item[3.] Call the \method{endheaders()} method (this can be omitted if
  43 step 4 makes no calls).
  44
  45 \item[4.] Optional calls to the \method{send()} method.
  46
  47 \item[5.] Call the \method{getreply()} method.
  48
  49 \item[6.] Call the \method{getfile()} method and read the data off the
  50 file object that it returns.
  51
  52 \end{enumerate}
  53 \end{classdesc}
  54
  55 \subsection{HTTP Objects}
  56
  57 \class{HTTP} instances have the following methods:
  58
  59
  60 \begin{methoddesc}{set_debuglevel}{level}
  61 Set the debugging level (the amount of debugging output printed).
  62 The default debug level is \code{0}, meaning no debugging output is
  63 printed.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}{connect}{host\optional{, port}}
  67 Connect to the server given by \var{host} and \var{port}.  See the
  68 intro for the default port.  This should be called directly only if
  69 the instance was instantiated without passing a host.
  70 \end{methoddesc}
  71
  72 \begin{methoddesc}{send}{data}
  73 Send data to the server.  This should be used directly only after the
  74 \method{endheaders()} method has been called and before
  75 \method{getreply()} has been called.
  76 \end{methoddesc}
  77
  78 \begin{methoddesc}{putrequest}{request, selector}
  79 This should be the first call after the connection to the server has
  80 been made.  It sends a line to the server consisting of the
  81 \var{request} string, the \var{selector} string, and the HTTP version
  82 (\code{HTTP/1.0}).
  83 \end{methoddesc}
  84
  85 \begin{methoddesc}{putheader}{header, argument\optional{, ...}}
  86 Send an \rfc{822} style header to the server.  It sends a line to the
  87 server consisting of the header, a colon and a space, and the first
  88 argument.  If more arguments are given, continuation lines are sent,
  89 each consisting of a tab and an argument.
  90 \end{methoddesc}
  91
  92 \begin{methoddesc}{endheaders}{}
  93 Send a blank line to the server, signalling the end of the headers.
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}{getreply}{}
  97 Complete the request by shutting down the sending end of the socket,
  98 read the reply from the server, and return a triple
  99 \code{(\var{replycode}, \var{message}, \var{headers})}.  Here,
 100 \var{replycode} is the integer reply code from the request (e.g.,
 101 \code{200} if the request was handled properly); \var{message} is the
 102 message string corresponding to the reply code; and \var{headers} is
 103 an instance of the class \class{mimetools.Message} containing the
 104 headers received from the server.  See the description of the
 105 \refmodule{mimetools}\refstmodindex{mimetools} module.
 106 \end{methoddesc}
 107
 108 \begin{methoddesc}{getfile}{}
 109 Return a file object from which the data returned by the server can be
 110 read, using the \method{read()}, \method{readline()} or
 111 \method{readlines()} methods.
 112 \end{methoddesc}
 113
 114 \subsection{Examples}
 115 \nodename{HTTP Examples}
 116
 117 Here is an example session that uses the \samp{GET} method:
 118
 119 \begin{verbatim}
 120 >>> import httplib
 121 >>> h = httplib.HTTP('www.cwi.nl')
 122 >>> h.putrequest('GET', '/index.html')
 123 >>> h.putheader('Accept', 'text/html')
 124 >>> h.putheader('Accept', 'text/plain')
 125 >>> h.endheaders()
 126 >>> errcode, errmsg, headers = h.getreply()
 127 >>> print errcode # Should be 200
 128 >>> f = h.getfile()
 129 >>> data = f.read() # Get the raw HTML
 130 >>> f.close()
 131 \end{verbatim}
 132
 133 Here is an example session that shows how to \samp{POST} requests:
 134
 135 \begin{verbatim}
 136 >>> import httplib, urllib
 137 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
 138 >>> h = httplib.HTTP("www.musi-cal.com:80")
 139 >>> h.putrequest("POST", "/cgi-bin/query")
 140 >>> h.putheader("Content-length", "%d" % len(params))
 141 >>> h.putheader('Accept', 'text/plain')
 142 >>> h.putheader('Host', 'www.musi-cal.com')
 143 >>> h.endheaders()
 144 >>> h.send(paramstring)
 145 >>> reply, msg, hdrs = h.getreply()
 146 >>> print errcode # should be 200
 147 >>> data = h.getfile().read() # get the raw HTML
 148 \end{verbatim}