cpython-withatomic / Doc / libhttplib.tex

The branch 'legacy-trunk' does not exist.
Full commit
\section{Standard Module \sectcode{httplib}}

\renewcommand{\indexsubitem}{(in module httplib)}

This module defines a class which implements the client side of the
HTTP protocol.  It is normally not used directly --- the module
\code{urllib} uses it to handle URLs that use HTTP.

The module defines one class, \code{HTTP}.  An \code{HTTP} instance
represents one transaction with an HTTP server.  It should be
instantiated passing it a host and optional port number.  If no port
number is passed, the port is extracted from the host string if it has
the form \code{host:port}, else the default HTTP port (80) is used.
If no host is passed, no connection is made, and the \code{connect}
method should be used to connect to a server.  For example, the
following calls all create instances that connect to the server at the
same host and port:

>>> h1 = httplib.HTTP('')
>>> h2 = httplib.HTTP('')
>>> h3 = httplib.HTTP('', 80)

Once an \code{HTTP} instance has been connected to an HTTP server, it
should be used as follows:


\item[1.] Make exactly one call to the \code{putrequest()} method.

\item[2.] Make zero or more calls to the \code{putheader()} method.

\item[3.] Call the \code{endheaders()} method (this can be omitted if
step 4 makes no calls).

\item[4.] Optional calls to the \code{send()} method.

\item[5.] Call the \code{getreply()} method.

\item[6.] Call the \code{getfile()} method and read the data off the
file object that it returns.


\subsection{HTTP Objects}

\code{HTTP} instances have the following methods:

\renewcommand{\indexsubitem}{(HTTP method)}

Set the debugging level (the amount of debugging output printed).
The default debug level is \code{0}, meaning no debugging output is

\begin{funcdesc}{connect}{host\optional{\, port}}
Connect to the server given by \var{host} and \var{port}.  See the
intro for the default port.  This should be called directly only if
the instance was instantiated without passing a host.

Send data to the server.  This should be used directly only after the
\code{endheaders()} method has been called and before
\code{getreply()} has been called.

\begin{funcdesc}{putrequest}{request\, selector}
This should be the first call after the connection to the server has
been made.  It sends a line to the server consisting of the
\var{request} string, the \var{selector} string, and the HTTP version

\begin{funcdesc}{putheader}{header\, argument\optional{\, ...}}
Send an RFC-822 style header to the server.  It sends a line to the
server consisting of the header, a colon and a space, and the first
argument.  If more arguments are given, continuation lines are sent,
each consisting of a tab and an argument.

Send a blank line to the server, signalling the end of the headers.

Complete the request by shutting down the sending end of the socket,
read the reply from the server, and return a triple (\var{replycode},
\var{message}, \var{headers}).  Here \var{replycode} is the integer
reply code from the request (e.g.\ \code{200} if the request was
handled properly); \var{message} is the message string corresponding
to the reply code; and \var{header} is an instance of the class
\code{rfc822.Message} containing the headers received from the server.
See the description of the \code{rfc822} module.

Return a file object from which the data returned by the server can be
read, using the \code{read()}, \code{readline()} or \code{readlines()}

\nodename{HTTP Example}

Here is an example session:

>>> import httplib
>>> h = httplib.HTTP('')
>>> h.putrequest('GET', '/index.html')
>>> h.putheader('Accept', 'text/html')
>>> h.putheader('Accept', 'text/plain')
>>> h.endheaders()
>>> errcode, errmsg, headers = h.getreply()
>>> print errcode # Should be 200
>>> f = h.getfile()
>>> data # Get the raw HTML
>>> f.close()