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

annotate Doc/lib/libhttplib.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	009f3abbf726
children	4f531cdf242e

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}
21540 0af9ac87ffbc More index entries. Fred Drake <fdrake@acm.org> parents: 21512 diff changeset	8 \index{HTTP!\module{httplib} (standard module)}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	9
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	10 This module defines classes which implement the client side of the
dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	11 HTTP and HTTPS protocols. It is normally not used directly --- the
dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	12 module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs
27418 009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	13 that use HTTP and HTTPS.
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	14
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	15 \begin{notice}
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	16 HTTPS support is only available if the \refmodule{socket} module was
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	17 compiled with SSL support.
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	18 \end{notice}
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	19
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	20 \begin{notice}
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	21 The public interface for this module changed substantially in Python
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	22 2.0. The \class{HTTP} class is retained only for backward
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	23 compatibility with 1.5.2. It should not be used in new code. Refer
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	24 to the online docstrings for usage.
009f3abbf726 Adjust some of Skip's latest changes slightly; these really are things Fred Drake <fdrake@acm.org> parents: 27413 diff changeset	25 \end{notice}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	26
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	27 The constants defined in this module are:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	28
20919 b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	29 \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	30 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	31 \end{datadesc}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	32
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	33 \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	34 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	35 \end{datadesc}
b21b42330e40 Cleaned up some markup stupidity and a usage problem reported by Detlef Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	36
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	37 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	38
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	39 \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	40 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	41 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	42 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	43 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	44 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	45 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	46
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	47 \begin{verbatim}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	48 >>> 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	49 >>> 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	50 >>> 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	51 \end{verbatim}
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	52 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	53 \end{classdesc}
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{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	56 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	57 secure servers. Default port is \code{443}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	58 \versionadded{2.0}
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	59 \end{classdesc}
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	60
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	61 \begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}}
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	62 Class whose instances are returned upon successful connection. Not
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	63 instantiated directly by user.
5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	64 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	65 \end{classdesc}
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 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	68
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	69 \begin{excdesc}{HTTPException}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	70 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	71 subclass of \exception{Exception}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	72 \versionadded{2.0}
21111 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}{NotConnected}
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}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	77 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	78 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	79
22497 393b0c3d9773 document InvalidURL exception Skip Montanaro <skip@pobox.com> parents: 21540 diff changeset	80 \begin{excdesc}{InvalidURL}
393b0c3d9773 document InvalidURL exception Skip Montanaro <skip@pobox.com> parents: 21540 diff changeset	81 A subclass of \exception{HTTPException}, raised if a port is given and is
393b0c3d9773 document InvalidURL exception Skip Montanaro <skip@pobox.com> parents: 21540 diff changeset	82 either non-numeric or empty.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	83 \versionadded{2.3}
22497 393b0c3d9773 document InvalidURL exception Skip Montanaro <skip@pobox.com> parents: 21540 diff changeset	84 \end{excdesc}
393b0c3d9773 document InvalidURL exception Skip Montanaro <skip@pobox.com> parents: 21540 diff changeset	85
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	86 \begin{excdesc}{UnknownProtocol}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	87 A subclass of \exception{HTTPException}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	88 \versionadded{2.0}
21111 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}{UnknownTransferEncoding}
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{HTTPException}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	93 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	94 \end{excdesc}
2609 7ef72873e4d6 restructured library manual accordiung to functional group Guido van Rossum <guido@python.org> parents: 2581 diff changeset	95
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	96 \begin{excdesc}{UnimplementedFileMode}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	97 A subclass of \exception{HTTPException}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	98 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	99 \end{excdesc}
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 \begin{excdesc}{IncompleteRead}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	102 A subclass of \exception{HTTPException}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	103 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	104 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	105
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	106 \begin{excdesc}{ImproperConnectionState}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	107 A subclass of \exception{HTTPException}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	108 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	109 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	110
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	111 \begin{excdesc}{CannotSendRequest}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	112 A subclass of \exception{ImproperConnectionState}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	113 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	114 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	115
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	116 \begin{excdesc}{CannotSendHeader}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	117 A subclass of \exception{ImproperConnectionState}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	118 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	119 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	120
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	121 \begin{excdesc}{ResponseNotReady}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	122 A subclass of \exception{ImproperConnectionState}.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	123 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	124 \end{excdesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	125
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	126 \begin{excdesc}{BadStatusLine}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	127 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	128 HTTP status code that we don't understand.
27413 5c133d13f325 * add \versionadded{} strings as appropriate Skip Montanaro <skip@pobox.com> parents: 22497 diff changeset	129 \versionadded{2.0}
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	130 \end{excdesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	131
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	132
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	133 \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	134
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	135 \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	136
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	137 \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	138 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	139 \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	140 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	141 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	142 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	143 with the request.
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	144 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	145
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	146 \begin{methoddesc}{getresponse}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	147 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	148 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	149 \end{methoddesc}
2609 7ef72873e4d6 restructured library manual accordiung to functional group Guido van Rossum <guido@python.org> parents: 2581 diff changeset	150
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	151 \begin{methoddesc}{set_debuglevel}{level}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	152 Set the debugging level (the amount of debugging output printed).
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	153 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	154 printed.
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 \begin{methoddesc}{connect}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	158 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	159 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	160
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	161 \begin{methoddesc}{close}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	162 Close the connection to the server.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	163 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	164
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	165 \begin{methoddesc}{send}{data}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	166 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	167 \method{endheaders()} method has been called and before
f017c4858ba8 Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	168 \method{getreply()} has been called.
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
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	171 \begin{methoddesc}{putrequest}{request, selector}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	172 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	173 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	174 \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	175 (\code{HTTP/1.1}).
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	176 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	177
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	178 \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	179 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	180 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	181 argument. If more arguments are given, continuation lines are sent,
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	182 each consisting of a tab and an argument.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	183 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	184
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	185 \begin{methoddesc}{endheaders}{}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	186 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	187 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	188
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	189
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	190 \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	191
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	192 \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	193
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	194 \begin{methoddesc}{read}{}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	195 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	196 \end{methoddesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	197
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	198 \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	199 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	200 matching header.
7875 8f425f8f4be2 Remove obsolete \setindexsubitem macros. Fred Drake <fdrake@acm.org> parents: 7657 diff changeset	201 \end{methoddesc}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	202
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	203 \begin{datadesc}{msg}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	204 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	205 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	206
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	207 \begin{datadesc}{version}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	208 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	209 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	210
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	211 \begin{datadesc}{status}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	212 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	213 \end{datadesc}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	214
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	215 \begin{datadesc}{reason}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	216 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	217 \end{datadesc}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	218
20086 dad94ca47e21 Minor changes. Fred Drake <fdrake@acm.org> parents: 19637 diff changeset	219
16115 3e13524ed86c Minor markup adjustment. Fred Drake <fdrake@acm.org> parents: 15413 diff changeset	220 \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	221
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	222 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	223
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7219 diff changeset	224 \begin{verbatim}
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	225 >>> import httplib
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	226 >>> 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	227 >>> 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	228 >>> r1 = conn.getresponse()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	229 >>> 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	230 200 OK
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	231 >>> data1 = r1.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	232 >>> 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	233 >>> r2 = conn.getresponse()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	234 >>> 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	235 404 Not Found
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	236 >>> data2 = r2.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	237 >>> 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	238 \end{verbatim}
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	239
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	240 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	241
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	242 \begin{verbatim}
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	243 >>> import httplib, urllib
0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	244 >>> 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	245 >>> 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	246 ... "Accept": "text/plain"}
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	247 >>> 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	248 >>> conn.request("POST", "/cgi-bin/query", params, headers)
21512 326d9972f6f6 Fix typo in httplib example. Fred Drake <fdrake@acm.org> parents: 21111 diff changeset	249 >>> response = conn.getresponse()
21111 8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	250 >>> 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	251 200 OK
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	252 >>> data = response.read()
8d0c106d9099 Updated documentation for the new httplib interface, by Kalle Svensson. Fred Drake <fdrake@acm.org> parents: 20919 diff changeset	253 >>> conn.close()
13087 0f216a54d34b Skip Montanaro <skip@mojam.com>: Fred Drake <fdrake@acm.org> parents: 10689 diff changeset	254 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libhttplib.tex @ 27998:e27f58a50737 legacy-trunk