Mercurial > cpython-lru_cache-weakref
annotate Doc/libhttplib.tex @ 5817:48b94de85bf3 legacy-trunk
Extensive changes by AMK.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Thu, 17 Jul 1997 16:29:42 +0000 |
| parents | fa6d013c942b |
| children | 3468ea8645ca |
| rev | line source |
|---|---|
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
1 \section{Standard Module \sectcode{httplib}} |
| 2449 | 2 \stmodindex{httplib} |
| 3 \index{HTTP} | |
| 4 | |
|
2453
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2449
diff
changeset
|
5 \renewcommand{\indexsubitem}{(in module httplib)} |
|
cdd3a721b40e
a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents:
2449
diff
changeset
|
6 |
| 2449 | 7 This module defines a class which implements the client side of the |
| 8 HTTP protocol. It is normally not used directly --- the module | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
9 \code{urllib} uses it to handle URLs that use HTTP. |
| 2449 | 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} | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
18 method should be used to connect to a server. For example, the |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
19 following calls all create instances that connect to the server at the |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
20 same host and port: |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
21 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
22 \begin{verbatim} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
23 >>> h1 = httplib.HTTP('www.cwi.nl') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
24 >>> h2 = httplib.HTTP('www.cwi.nl:80') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
25 >>> h3 = httplib.HTTP('www.cwi.nl', 80) |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
26 \end{verbatim} |
| 2449 | 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 | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
38 step 4 makes no calls). |
| 2449 | 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 | |
|
2609
7ef72873e4d6
restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
49 \subsection{HTTP Objects} |
|
7ef72873e4d6
restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
50 |
| 2449 | 51 \code{HTTP} instances have the following methods: |
| 52 | |
|
2609
7ef72873e4d6
restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
53 \renewcommand{\indexsubitem}{(HTTP method)} |
|
7ef72873e4d6
restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
2581
diff
changeset
|
54 |
| 2449 | 55 \begin{funcdesc}{set_debuglevel}{level} |
| 56 Set the debugging level (the amount of debugging output printed). | |
| 57 The default debug level is \code{0}, meaning no debugging output is | |
| 58 printed. | |
| 59 \end{funcdesc} | |
| 60 | |
| 61 \begin{funcdesc}{connect}{host\optional{\, port}} | |
| 62 Connect to the server given by \var{host} and \var{port}. See the | |
| 63 intro for the default port. This should be called directly only if | |
| 64 the instance was instantiated without passing a host. | |
| 65 \end{funcdesc} | |
| 66 | |
| 67 \begin{funcdesc}{send}{data} | |
| 68 Send data to the server. This should be used directly only after the | |
| 69 \code{endheaders()} method has been called and before | |
| 70 \code{getreply()} has been called. | |
| 71 \end{funcdesc} | |
| 72 | |
| 73 \begin{funcdesc}{putrequest}{request\, selector} | |
| 74 This should be the first call after the connection to the server has | |
| 75 been made. It sends a line to the server consisting of the | |
| 76 \var{request} string, the \var{selector} string, and the HTTP version | |
| 77 (\code{HTTP/1.0}). | |
| 78 \end{funcdesc} | |
| 79 | |
| 80 \begin{funcdesc}{putheader}{header\, argument\optional{\, ...}} | |
| 81 Send an RFC-822 style header to the server. It sends a line to the | |
| 82 server consisting of the header, a colon and a space, and the first | |
| 83 argument. If more arguments are given, continuation lines are sent, | |
| 84 each consisting of a tab and an argument. | |
| 85 \end{funcdesc} | |
| 86 | |
| 87 \begin{funcdesc}{endheaders}{} | |
| 88 Send a blank line to the server, signalling the end of the headers. | |
| 89 \end{funcdesc} | |
| 90 | |
| 91 \begin{funcdesc}{getreply}{} | |
| 92 Complete the request by shutting down the sending end of the socket, | |
| 93 read the reply from the server, and return a triple (\var{replycode}, | |
| 94 \var{message}, \var{headers}). Here \var{replycode} is the integer | |
|
2491
fb8e08ec88dd
changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents:
2453
diff
changeset
|
95 reply code from the request (e.g.\ \code{200} if the request was |
| 2449 | 96 handled properly); \var{message} is the message string corresponding |
|
5752
fa6d013c942b
fixed typo, "header" ==> "headers"
Fred Drake <fdrake@acm.org>
parents:
5677
diff
changeset
|
97 to the reply code; and \var{headers} is an instance of the class |
|
5677
6fda1e6e2616
It's now using mimetools instead of rfc822
Guido van Rossum <guido@python.org>
parents:
2609
diff
changeset
|
98 \code{mimetools.Message} containing the headers received from the server. |
|
6fda1e6e2616
It's now using mimetools instead of rfc822
Guido van Rossum <guido@python.org>
parents:
2609
diff
changeset
|
99 See the description of the \code{mimetools} module. |
|
6fda1e6e2616
It's now using mimetools instead of rfc822
Guido van Rossum <guido@python.org>
parents:
2609
diff
changeset
|
100 \stmodindex{mimetools} |
| 2449 | 101 \end{funcdesc} |
| 102 | |
| 103 \begin{funcdesc}{getfile}{} | |
| 104 Return a file object from which the data returned by the server can be | |
| 105 read, using the \code{read()}, \code{readline()} or \code{readlines()} | |
| 106 methods. | |
| 107 \end{funcdesc} | |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
108 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
109 \subsection{Example} |
|
2581
4d28b655b728
added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents:
2576
diff
changeset
|
110 \nodename{HTTP Example} |
|
2576
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
111 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
112 Here is an example session: |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
113 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
114 \begin{verbatim} |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
115 >>> import httplib |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
116 >>> h = httplib.HTTP('www.cwi.nl') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
117 >>> h.putrequest('GET', '/index.html') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
118 >>> h.putheader('Accept', 'text/html') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
119 >>> h.putheader('Accept', 'text/plain') |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
120 >>> h.endheaders() |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
121 >>> errcode, errmsg, headers = h.getreply() |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
122 >>> print errcode # Should be 200 |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
123 >>> f = h.getfile() |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
124 >>> data f.read() # Get the raw HTML |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
125 >>> f.close() |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
126 >>> |
|
f47bc5554418
mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents:
2491
diff
changeset
|
127 \end{verbatim} |