Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame^] | 1 | \section{Standard Module \sectcode{httplib}} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 2 | \stmodindex{httplib} |
| 3 | \index{HTTP} |
| 4 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 5 | \renewcommand{\indexsubitem}{(in module httplib)} |
| 6 | |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 7 | This module defines a class which implements the client side of the |
| 8 | HTTP protocol. It is normally not used directly --- the module |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 9 | \code{urllib} uses it to handle URLs that use HTTP. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 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} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame^] | 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} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame^] | 38 | step 4 makes no calls). |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 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 | \code{HTTP} instances have the following methods: |
| 50 | |
| 51 | \begin{funcdesc}{set_debuglevel}{level} |
| 52 | Set the debugging level (the amount of debugging output printed). |
| 53 | The default debug level is \code{0}, meaning no debugging output is |
| 54 | printed. |
| 55 | \end{funcdesc} |
| 56 | |
| 57 | \begin{funcdesc}{connect}{host\optional{\, port}} |
| 58 | Connect to the server given by \var{host} and \var{port}. See the |
| 59 | intro for the default port. This should be called directly only if |
| 60 | the instance was instantiated without passing a host. |
| 61 | \end{funcdesc} |
| 62 | |
| 63 | \begin{funcdesc}{send}{data} |
| 64 | Send data to the server. This should be used directly only after the |
| 65 | \code{endheaders()} method has been called and before |
| 66 | \code{getreply()} has been called. |
| 67 | \end{funcdesc} |
| 68 | |
| 69 | \begin{funcdesc}{putrequest}{request\, selector} |
| 70 | This should be the first call after the connection to the server has |
| 71 | been made. It sends a line to the server consisting of the |
| 72 | \var{request} string, the \var{selector} string, and the HTTP version |
| 73 | (\code{HTTP/1.0}). |
| 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{putheader}{header\, argument\optional{\, ...}} |
| 77 | Send an RFC-822 style header to the server. It sends a line to the |
| 78 | server consisting of the header, a colon and a space, and the first |
| 79 | argument. If more arguments are given, continuation lines are sent, |
| 80 | each consisting of a tab and an argument. |
| 81 | \end{funcdesc} |
| 82 | |
| 83 | \begin{funcdesc}{endheaders}{} |
| 84 | Send a blank line to the server, signalling the end of the headers. |
| 85 | \end{funcdesc} |
| 86 | |
| 87 | \begin{funcdesc}{getreply}{} |
| 88 | Complete the request by shutting down the sending end of the socket, |
| 89 | read the reply from the server, and return a triple (\var{replycode}, |
| 90 | \var{message}, \var{headers}). Here \var{replycode} is the integer |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 91 | reply code from the request (e.g.\ \code{200} if the request was |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 92 | handled properly); \var{message} is the message string corresponding |
| 93 | to the reply code; and \var{header} is an instance of the class |
| 94 | \code{rfc822.Message} containing the headers received from the server. |
| 95 | See the description of the \code{rfc822} module. |
| 96 | \stmodindex{rfc822} |
| 97 | \end{funcdesc} |
| 98 | |
| 99 | \begin{funcdesc}{getfile}{} |
| 100 | Return a file object from which the data returned by the server can be |
| 101 | read, using the \code{read()}, \code{readline()} or \code{readlines()} |
| 102 | methods. |
| 103 | \end{funcdesc} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame^] | 104 | |
| 105 | \subsection{Example} |
| 106 | |
| 107 | Here is an example session: |
| 108 | |
| 109 | \begin{verbatim} |
| 110 | >>> import httplib |
| 111 | >>> h = httplib.HTTP('www.cwi.nl') |
| 112 | >>> h.putrequest('GET', '/index.html') |
| 113 | >>> h.putheader('Accept', 'text/html') |
| 114 | >>> h.putheader('Accept', 'text/plain') |
| 115 | >>> h.endheaders() |
| 116 | >>> errcode, errmsg, headers = h.getreply() |
| 117 | >>> print errcode # Should be 200 |
| 118 | >>> f = h.getfile() |
| 119 | >>> data f.read() # Get the raw HTML |
| 120 | >>> f.close() |
| 121 | >>> |
| 122 | \end{verbatim} |