Doc/lib/libhttplib.tex

   1 \section{Built-in 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.
  19
  20 Once an \code{HTTP} instance has been connected to an HTTP server, it
  21 should be used as follows:
  22
  23 \begin{enumerate}
  24
  25 \item[1.] Make exactly one call to the \code{putrequest()} method.
  26
  27 \item[2.] Make zero or more calls to the \code{putheader()} method.
  28
  29 \item[3.] Call the \code{endheaders()} method (this can be omitted if
  30 step 4. makes no calls).
  31
  32 \item[4.] Optional calls to the \code{send()} method.
  33
  34 \item[5.] Call the \code{getreply()} method.
  35
  36 \item[6.] Call the \code{getfile()} method and read the data off the
  37 file object that it returns.
  38
  39 \end{enumerate}
  40
  41 \code{HTTP} instances have the following methods:
  42
  43 \begin{funcdesc}{set_debuglevel}{level}
  44 Set the debugging level (the amount of debugging output printed).
  45 The default debug level is \code{0}, meaning no debugging output is
  46 printed.
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{connect}{host\optional{\, port}}
  50 Connect to the server given by \var{host} and \var{port}.  See the
  51 intro for the default port.  This should be called directly only if
  52 the instance was instantiated without passing a host.
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{send}{data}
  56 Send data to the server.  This should be used directly only after the
  57 \code{endheaders()} method has been called and before
  58 \code{getreply()} has been called.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{putrequest}{request\, selector}
  62 This should be the first call after the connection to the server has
  63 been made.  It sends a line to the server consisting of the
  64 \var{request} string, the \var{selector} string, and the HTTP version
  65 (\code{HTTP/1.0}).
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{putheader}{header\, argument\optional{\, ...}}
  69 Send an RFC-822 style header to the server.  It sends a line to the
  70 server consisting of the header, a colon and a space, and the first
  71 argument.  If more arguments are given, continuation lines are sent,
  72 each consisting of a tab and an argument.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{endheaders}{}
  76 Send a blank line to the server, signalling the end of the headers.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{getreply}{}
  80 Complete the request by shutting down the sending end of the socket,
  81 read the reply from the server, and return a triple (\var{replycode},
  82 \var{message}, \var{headers}).  Here \var{replycode} is the integer
  83 reply code from the request (e.g.\ \code{200} if the request was
  84 handled properly); \var{message} is the message string corresponding
  85 to the reply code; and \var{header} is an instance of the class
  86 \code{rfc822.Message} containing the headers received from the server.
  87 See the description of the \code{rfc822} module.
  88 \stmodindex{rfc822}
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{getfile}{}
  92 Return a file object from which the data returned by the server can be
  93 read, using the \code{read()}, \code{readline()} or \code{readlines()}
  94 methods.
  95 \end{funcdesc}