Doc/libhttplib.tex

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