| \section{\module{httplib} --- |
| HTTP protocol client} |
| |
| \declaremodule{standard}{httplib} |
| \modulesynopsis{HTTP and HTTPS protocol client (requires sockets).} |
| |
| \indexii{HTTP}{protocol} |
| |
| This module defines classes which implement the client side of the |
| HTTP and HTTPS protocols. It is normally not used directly --- the |
| module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs |
| that use HTTP and HTTPS. \note{HTTPS support is only |
| available if the \refmodule{socket} module was compiled with SSL |
| support.} |
| |
| The module defines one class, \class{HTTP}: |
| |
| \begin{classdesc}{HTTP}{\optional{host\optional{, port}}} |
| An \class{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{\var{host}:\var{port}}, else the default HTTP port (80) |
| is used. If no host is passed, no connection is made, and the |
| \method{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: |
| |
| \begin{verbatim} |
| >>> h1 = httplib.HTTP('www.cwi.nl') |
| >>> h2 = httplib.HTTP('www.cwi.nl:80') |
| >>> h3 = httplib.HTTP('www.cwi.nl', 80) |
| \end{verbatim} |
| |
| Once an \class{HTTP} instance has been connected to an HTTP server, it |
| should be used as follows: |
| |
| \begin{enumerate} |
| |
| \item Make exactly one call to the \method{putrequest()} method. |
| |
| \item Make zero or more calls to the \method{putheader()} method. |
| |
| \item Call the \method{endheaders()} method (this can be omitted if |
| step 4 makes no calls). |
| |
| \item Optional calls to the \method{send()} method. |
| |
| \item Call the \method{getreply()} method. |
| |
| \item Call the \method{getfile()} method and read the data off the |
| file object that it returns. |
| |
| \end{enumerate} |
| \end{classdesc} |
| |
| \begin{datadesc}{HTTP_PORT} |
| The default port for the HTTP protocol (always \code{80}). |
| \end{datadesc} |
| |
| \begin{datadesc}{HTTPS_PORT} |
| The default port for the HTTPS protocol (always \code{443}). |
| \end{datadesc} |
| |
| |
| \subsection{HTTP Objects \label{http-objects}} |
| |
| \class{HTTP} instances have the following methods: |
| |
| |
| \begin{methoddesc}{set_debuglevel}{level} |
| Set the debugging level (the amount of debugging output printed). |
| The default debug level is \code{0}, meaning no debugging output is |
| printed. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{connect}{host\optional{, port}} |
| Connect to the server given by \var{host} and \var{port}. See the |
| introduction to the \refmodule{httplib} module for information on the |
| default ports. This should be called directly only if the instance |
| was instantiated without passing a host. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{send}{data} |
| Send data to the server. This should be used directly only after the |
| \method{endheaders()} method has been called and before |
| \method{getreply()} has been called. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{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 |
| (\code{HTTP/1.0}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}{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. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{endheaders}{} |
| Send a blank line to the server, signalling the end of the headers. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{getreply}{} |
| Complete the request by shutting down the sending end of the socket, |
| read the reply from the server, and return a triple |
| \code{(\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{headers} is |
| an instance of the class \class{mimetools.Message} containing the |
| headers received from the server. See the description of the |
| \refmodule{mimetools}\refstmodindex{mimetools} module. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{getfile}{} |
| Return a file object from which the data returned by the server can be |
| read, using the \method{read()}, \method{readline()} or |
| \method{readlines()} methods. |
| \end{methoddesc} |
| |
| |
| \subsection{Examples \label{httplib-examples}} |
| |
| Here is an example session that uses the \samp{GET} method: |
| |
| \begin{verbatim} |
| >>> import httplib |
| >>> h = httplib.HTTP('www.cwi.nl') |
| >>> h.putrequest('GET', '/index.html') |
| >>> h.putheader('Accept', 'text/html') |
| >>> h.putheader('Accept', 'text/plain') |
| >>> h.putheader('Host', 'www.cwi.nl') |
| >>> h.endheaders() |
| >>> errcode, errmsg, headers = h.getreply() |
| >>> print errcode # Should be 200 |
| >>> f = h.getfile() |
| >>> data = f.read() # Get the raw HTML |
| >>> f.close() |
| \end{verbatim} |
| |
| Here is an example session that shows how to \samp{POST} requests: |
| |
| \begin{verbatim} |
| >>> import httplib, urllib |
| >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) |
| >>> h = httplib.HTTP("www.musi-cal.com:80") |
| >>> h.putrequest("POST", "/cgi-bin/query") |
| >>> h.putheader("Content-type", "application/x-www-form-urlencoded") |
| >>> h.putheader("Content-length", "%d" % len(params)) |
| >>> h.putheader('Accept', 'text/plain') |
| >>> h.putheader('Host', 'www.musi-cal.com') |
| >>> h.endheaders() |
| >>> h.send(params) |
| >>> reply, msg, hdrs = h.getreply() |
| >>> print reply # should be 200 |
| >>> data = h.getfile().read() # get the raw HTML |
| \end{verbatim} |