cpython-lru_cache-weakref: Doc/lib/libhttplib.tex annotate

annotate Doc/lib/libhttplib.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	8d0c106d9099
children	326d9972f6f6

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	1 \section{\module{httplib} ---
10689 9b7d8ec9b910 Make some module references hyperlinks. Fred Drake <fdrake@acm.org> parents: 9550 diff changeset	2 HTTP protocol client}
9b7d8ec9b910 Make some module references hyperlinks. Fred Drake <fdrake@acm.org> parents: 9550 diff changeset	3
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7875 diff changeset	4 \declaremodule{standard}{httplib}
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	5 \modulesynopsis{HTTP and HTTPS protocol client (requires sockets).}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7875 diff changeset	6
7657 f017c4858ba8 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	7 \indexii{HTTP}{protocol}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	8
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	9 This module defines classes which implement the client side of the
dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	10 HTTP and HTTPS protocols. It is normally not used directly --- the
dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	11 module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20086 diff changeset	12 that use HTTP and HTTPS. \note{HTTPS support is only
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	13 available if the \refmodule{socket} module was compiled with SSL
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20086 diff changeset	14 support.}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	15
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	16 The constants defined in this module are:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	17
20919 b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	18 \begin{datadesc}{HTTP_PORT}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	19 The default port for the HTTP protocol (always \code{80}).
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	20 \end{datadesc}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	21
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	22 \begin{datadesc}{HTTPS_PORT}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	23 The default port for the HTTPS protocol (always \code{443}).
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	24 \end{datadesc}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	25
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	26 The module provides the following classes:
20919 b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	27
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	28 \begin{classdesc}{HTTPConnection}{host\optional{, port}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	29 An \class{HTTPConnection} instance represents one transaction with an HTTP
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	30 server. It should be instantiated passing it a host and optional port number.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	31 If no port number is passed, the port is extracted from the host string if it
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	32 has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	33 used. For example, the following calls all create instances that connect to
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	34 the server at the same host and port:
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	35
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	36 \begin{verbatim}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	37 >>> h1 = httplib.HTTPConnection('www.cwi.nl')
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	38 >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	39 >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	40 \end{verbatim}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	41 \end{classdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	42
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	43 \begin{classdesc}{HTTPSConnection}{host\optional{, port}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	44 A subclass of \class{HTTPConnection} that uses SSL for communication with
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	45 secure servers. Default port is \code{443}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	46 \end{classdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	47
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	48 The following exceptions are raised as appropriate:
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	49
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	50 \begin{excdesc}{HTTPException}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	51 The base class of the other exceptions in this module. It is a
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	52 subclass of \exception{Exception}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	53 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	54
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	55 \begin{excdesc}{NotConnected}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	56 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	57 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	58
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	59 \begin{excdesc}{UnknownProtocol}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	60 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	61 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	62
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	63 \begin{excdesc}{UnknownTransferEncoding}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	64 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	65 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	66
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	67 \begin{excdesc}{IllegalKeywordArgument}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	68 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	69 \end{excdesc}
2609 7ef72873e4d6 restructured library manual accordiung to functional group Guido van Rossum <guido@python.org> parents: 2581 diff changeset	70
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	71 \begin{excdesc}{UnimplementedFileMode}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	72 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	73 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	74
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	75 \begin{excdesc}{IncompleteRead}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	76 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	77 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	78
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	79 \begin{excdesc}{ImproperConnectionState}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	80 A subclass of \exception{HTTPException}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	81 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	82
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	83 \begin{excdesc}{CannotSendRequest}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	84 A subclass of \exception{ImproperConnectionState}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	85 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	86
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	87 \begin{excdesc}{CannotSendHeader}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	88 A subclass of \exception{ImproperConnectionState}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	89 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	90
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	91 \begin{excdesc}{ResponseNotReady}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	92 A subclass of \exception{ImproperConnectionState}.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	93 \end{excdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	94
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	95 \begin{excdesc}{BadStatusLine}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	96 A subclass of \exception{HTTPException}. Raised if a server responds with a
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	97 HTTP status code that we don't understand.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	98 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	99
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	100
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	101 \subsection{HTTPConnection Objects \label{httpconnection-objects}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	102
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	103 \class{HTTPConnection} instances have the following methods:
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	104
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	105 \begin{methoddesc}{request}{method, url\optional{, body\optional{, headers}}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	106 This will send a request to the server using the HTTP request method
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	107 \var{method} and the selector \var{url}. If the \var{body} argument is
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	108 present, it should be a string of data to send after the headers are finished.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	109 The header Content-Length is automatically set to the correct value.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	110 The \var{headers} argument should be a mapping of extra HTTP headers to send
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	111 with the request.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	112 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	113
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	114 \begin{methoddesc}{getresponse}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	115 Should be called after a request is sent to get the response from the server.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	116 Returns an \class{HTTPResponse} instance.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	117 \end{methoddesc}
2609 7ef72873e4d6 restructured library manual accordiung to functional group Guido van Rossum <guido@python.org> parents: 2581 diff changeset	118
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	119 \begin{methoddesc}{set_debuglevel}{level}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	120 Set the debugging level (the amount of debugging output printed).
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	121 The default debug level is \code{0}, meaning no debugging output is
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	122 printed.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	123 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	124
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	125 \begin{methoddesc}{connect}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	126 Connect to the server specified when the object was created.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	127 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	128
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	129 \begin{methoddesc}{close}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	130 Close the connection to the server.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	131 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	132
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	133 \begin{methoddesc}{send}{data}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	134 Send data to the server. This should be used directly only after the
7657 f017c4858ba8 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	135 \method{endheaders()} method has been called and before
f017c4858ba8 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	136 \method{getreply()} has been called.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	137 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	138
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	139 \begin{methoddesc}{putrequest}{request, selector}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	140 This should be the first call after the connection to the server has
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	141 been made. It sends a line to the server consisting of the
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	142 \var{request} string, the \var{selector} string, and the HTTP version
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	143 (\code{HTTP/1.1}).
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	144 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	145
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	146 \begin{methoddesc}{putheader}{header, argument\optional{, ...}}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	147 Send an \rfc{822}-style header to the server. It sends a line to the
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	148 server consisting of the header, a colon and a space, and the first
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	149 argument. If more arguments are given, continuation lines are sent,
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	150 each consisting of a tab and an argument.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	151 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	152
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	153 \begin{methoddesc}{endheaders}{}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	154 Send a blank line to the server, signalling the end of the headers.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	155 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	156
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	157
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	158 \subsection{HTTPResponse Objects \label{httpresponse-objects}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	159
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	160 \class{HTTPResponse} instances have the following methods and attributes:
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	161
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	162 \begin{methoddesc}{read}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	163 Reads and returns the response body.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	164 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	165
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	166 \begin{methoddesc}{getheader}{name\optional{, default}}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	167 Get the contents of the header \var{name}, or \var{default} if there is no
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	168 matching header.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	169 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	170
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	171 \begin{datadesc}{msg}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	172 A \class{mimetools.Message} instance containing the response headers.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	173 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	174
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	175 \begin{datadesc}{version}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	176 HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	177 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	178
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	179 \begin{datadesc}{status}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	180 Status code returned by server.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	181 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	182
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	183 \begin{datadesc}{reason}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	184 Reason phrase returned by server.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	185 \end{datadesc}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	186
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	187
16115 3e13524ed86c Minor markup adjustment. Fred Drake <fdrake@acm.org> parents: 15413 diff changeset	188 \subsection{Examples \label{httplib-examples}}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	189
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	190 Here is an example session that uses the \samp{GET} method:
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	191
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7219 diff changeset	192 \begin{verbatim}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	193 >>> import httplib
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	194 >>> conn = httplib.HTTPConnection("www.python.org")
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	195 >>> conn.request("GET", "/index.html")
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	196 >>> r1 = conn.getresponse()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	197 >>> print r1.status, r1.reason
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	198 200 OK
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	199 >>> data1 = r1.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	200 >>> conn.request("GET", "/parrot.spam")
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	201 >>> r2 = conn.getresponse()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	202 >>> print r2.status, r2.reason
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	203 404 Not Found
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	204 >>> data2 = r2.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	205 >>> conn.close()
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7219 diff changeset	206 \end{verbatim}
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	207
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	208 Here is an example session that shows how to \samp{POST} requests:
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	209
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	210 \begin{verbatim}
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	211 >>> import httplib, urllib
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	212 >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	213 >>> headers = {"Content-type": "application/x-www-form-urlencoded",
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	214 ... "Accept": "text/plain"}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	215 >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	216 >>> conn.request("POST", "/cgi-bin/query", params, headers)
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	217 >>> response = h.getresponse()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	218 >>> print response.status, response.reason
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	219 200 OK
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	220 >>> data = response.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	221 >>> conn.close()
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	222 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libhttplib.tex @ 21467:4e35fa5d5708 legacy-trunk