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