diff options
Diffstat (limited to 'Doc/lib/libhttplib.tex')
| -rw-r--r-- | Doc/lib/libhttplib.tex | 452 |
1 files changed, 0 insertions, 452 deletions
diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex deleted file mode 100644 index 37a442d..0000000 --- a/Doc/lib/libhttplib.tex +++ /dev/null @@ -1,452 +0,0 @@ -\section{\module{httplib} --- - HTTP protocol client} - -\declaremodule{standard}{httplib} -\modulesynopsis{HTTP and HTTPS protocol client (requires sockets).} - -\indexii{HTTP}{protocol} -\index{HTTP!\module{httplib} (standard module)} - -This module defines classes which implement the client side of the -HTTP and HTTPS protocols. It is normally not used directly --- the -module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs -that use HTTP and HTTPS. - -\begin{notice} - HTTPS support is only available if the \refmodule{socket} module was - compiled with SSL support. -\end{notice} - -\begin{notice} - The public interface for this module changed substantially in Python - 2.0. The \class{HTTP} class is retained only for backward - compatibility with 1.5.2. It should not be used in new code. Refer - to the online docstrings for usage. -\end{notice} - -The module provides the following classes: - -\begin{classdesc}{HTTPConnection}{host\optional{, port\optional{, - strict\optional{, timeout}}}} -An \class{HTTPConnection} instance represents one transaction with an HTTP -server. It should be instantiated passing it a host and optional port number. -If no port number is passed, the port is extracted from the host string if it -has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is -used. When True, the optional parameter \var{strict} -causes \code{BadStatusLine} to be raised if the status line can't be parsed -as a valid HTTP/1.0 or 1.1 status line. If the optional \var{timeout} -parameter is given, connection attempts will timeout after that many -seconds (if it is not given or \code{None}, the global default -timeout setting is used). - -For example, the following calls all create instances that connect to -the server at the same host and port: - -\begin{verbatim} ->>> h1 = httplib.HTTPConnection('www.cwi.nl') ->>> h2 = httplib.HTTPConnection('www.cwi.nl:80') ->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80) ->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10) -\end{verbatim} -\versionadded{2.0} -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{HTTPSConnection}{host\optional{, port\optional{, - key_file\optional{, cert_file\optional{, - strict\optional{, timeout}}}}}} -A subclass of \class{HTTPConnection} that uses SSL for communication with -secure servers. Default port is \code{443}. -\var{key_file} is -the name of a PEM formatted file that contains your private -key. \var{cert_file} is a PEM formatted certificate chain file. - -\warning{This does not do any certificate verification!} - -\versionadded{2.0} -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}} -Class whose instances are returned upon successful connection. Not -instantiated directly by user. -\versionadded{2.0} -\end{classdesc} - -The following exceptions are raised as appropriate: - -\begin{excdesc}{HTTPException} -The base class of the other exceptions in this module. It is a -subclass of \exception{Exception}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{NotConnected} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{InvalidURL} -A subclass of \exception{HTTPException}, raised if a port is given and is -either non-numeric or empty. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnknownProtocol} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnknownTransferEncoding} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnimplementedFileMode} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{IncompleteRead} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{ImproperConnectionState} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{CannotSendRequest} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{CannotSendHeader} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{ResponseNotReady} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{BadStatusLine} -A subclass of \exception{HTTPException}. Raised if a server responds with a -HTTP status code that we don't understand. -\versionadded{2.0} -\end{excdesc} - -The constants defined in this module are: - -\begin{datadesc}{HTTP_PORT} - The default port for the HTTP protocol (always \code{80}). -\end{datadesc} - -\begin{datadesc}{HTTPS_PORT} - The default port for the HTTPS protocol (always \code{443}). -\end{datadesc} - -and also the following constants for integer status codes: - -\begin{tableiii}{l|c|l}{constant}{Constant}{Value}{Definition} - \lineiii{CONTINUE}{\code{100}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.1.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1}} - \lineiii{SWITCHING_PROTOCOLS}{\code{101}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.1.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2}} - \lineiii{PROCESSING}{\code{102}} - {WEBDAV, \ulink{RFC 2518, Section 10.1} - {http://www.webdav.org/specs/rfc2518.html#STATUS_102}} - - \lineiii{OK}{\code{200}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}} - \lineiii{CREATED}{\code{201}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2}} - \lineiii{ACCEPTED}{\code{202}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3}} - \lineiii{NON_AUTHORITATIVE_INFORMATION}{\code{203}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4}} - \lineiii{NO_CONTENT}{\code{204}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5}} - \lineiii{RESET_CONTENT}{\code{205}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6}} - \lineiii{PARTIAL_CONTENT}{\code{206}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.7} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7}} - \lineiii{MULTI_STATUS}{\code{207}} - {WEBDAV \ulink{RFC 2518, Section 10.2} - {http://www.webdav.org/specs/rfc2518.html#STATUS_207}} - \lineiii{IM_USED}{\code{226}} - {Delta encoding in HTTP, \rfc{3229}, Section 10.4.1} - - \lineiii{MULTIPLE_CHOICES}{\code{300}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1}} - \lineiii{MOVED_PERMANENTLY}{\code{301}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2}} - \lineiii{FOUND}{\code{302}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3}} - \lineiii{SEE_OTHER}{\code{303}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4}} - \lineiii{NOT_MODIFIED}{\code{304}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5}} - \lineiii{USE_PROXY}{\code{305}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6}} - \lineiii{TEMPORARY_REDIRECT}{\code{307}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.8} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8}} - - \lineiii{BAD_REQUEST}{\code{400}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}} - \lineiii{UNAUTHORIZED}{\code{401}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2}} - \lineiii{PAYMENT_REQUIRED}{\code{402}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}} - \lineiii{FORBIDDEN}{\code{403}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}} - \lineiii{NOT_FOUND}{\code{404}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5}} - \lineiii{METHOD_NOT_ALLOWED}{\code{405}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6}} - \lineiii{NOT_ACCEPTABLE}{\code{406}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.7} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7}} - \lineiii{PROXY_AUTHENTICATION_REQUIRED} - {\code{407}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.8} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8}} - \lineiii{REQUEST_TIMEOUT}{\code{408}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.9} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9}} - \lineiii{CONFLICT}{\code{409}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.10} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}} - \lineiii{GONE}{\code{410}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.11} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11}} - \lineiii{LENGTH_REQUIRED}{\code{411}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.12} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12}} - \lineiii{PRECONDITION_FAILED}{\code{412}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.13} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13}} - \lineiii{REQUEST_ENTITY_TOO_LARGE} - {\code{413}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.14} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14}} - \lineiii{REQUEST_URI_TOO_LONG}{\code{414}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.15} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15}} - \lineiii{UNSUPPORTED_MEDIA_TYPE}{\code{415}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.16} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16}} - \lineiii{REQUESTED_RANGE_NOT_SATISFIABLE}{\code{416}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.17} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17}} - \lineiii{EXPECTATION_FAILED}{\code{417}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.18} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18}} - \lineiii{UNPROCESSABLE_ENTITY}{\code{422}} - {WEBDAV, \ulink{RFC 2518, Section 10.3} - {http://www.webdav.org/specs/rfc2518.html#STATUS_422}} - \lineiii{LOCKED}{\code{423}} - {WEBDAV \ulink{RFC 2518, Section 10.4} - {http://www.webdav.org/specs/rfc2518.html#STATUS_423}} - \lineiii{FAILED_DEPENDENCY}{\code{424}} - {WEBDAV, \ulink{RFC 2518, Section 10.5} - {http://www.webdav.org/specs/rfc2518.html#STATUS_424}} - \lineiii{UPGRADE_REQUIRED}{\code{426}} - {HTTP Upgrade to TLS, \rfc{2817}, Section 6} - - \lineiii{INTERNAL_SERVER_ERROR}{\code{500}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1}} - \lineiii{NOT_IMPLEMENTED}{\code{501}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2}} - \lineiii{BAD_GATEWAY}{\code{502}} - {HTTP/1.1 \ulink{RFC 2616, Section 10.5.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3}} - \lineiii{SERVICE_UNAVAILABLE}{\code{503}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4}} - \lineiii{GATEWAY_TIMEOUT}{\code{504}} - {HTTP/1.1 \ulink{RFC 2616, Section 10.5.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5}} - \lineiii{HTTP_VERSION_NOT_SUPPORTED}{\code{505}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6}} - \lineiii{INSUFFICIENT_STORAGE}{\code{507}} - {WEBDAV, \ulink{RFC 2518, Section 10.6} - {http://www.webdav.org/specs/rfc2518.html#STATUS_507}} - \lineiii{NOT_EXTENDED}{\code{510}} - {An HTTP Extension Framework, \rfc{2774}, Section 7} -\end{tableiii} - -\begin{datadesc}{responses} -This dictionary maps the HTTP 1.1 status codes to the W3C names. - -Example: \code{httplib.responses[httplib.NOT_FOUND]} is \code{'Not Found'}. -\versionadded{2.5} -\end{datadesc} - - -\subsection{HTTPConnection Objects \label{httpconnection-objects}} - -\class{HTTPConnection} instances have the following methods: - -\begin{methoddesc}[HTTPConnection]{request}{method, url\optional{, body\optional{, headers}}} -This will send a request to the server using the HTTP request method -\var{method} and the selector \var{url}. If the \var{body} argument is -present, it should be a string of data to send after the headers are finished. -Alternatively, it may be an open file object, in which case the -contents of the file is sent; this file object should support -\code{fileno()} and \code{read()} methods. -The header Content-Length is automatically set to the correct value. -The \var{headers} argument should be a mapping of extra HTTP headers to send -with the request. - -\versionchanged[\var{body} can be a file object]{2.6} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{getresponse}{} -Should be called after a request is sent to get the response from the server. -Returns an \class{HTTPResponse} instance. -\note{Note that you must have read the whole response before you can send a new -request to the server.} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{set_debuglevel}{level} -Set the debugging level (the amount of debugging output printed). -The default debug level is \code{0}, meaning no debugging output is -printed. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{connect}{} -Connect to the server specified when the object was created. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{close}{} -Close the connection to the server. -\end{methoddesc} - -As an alternative to using the \method{request()} method described above, -you can also send your request step by step, by using the four functions -below. - -\begin{methoddesc}[HTTPConnection]{putrequest}{request, selector\optional{, -skip\_host\optional{, skip_accept_encoding}}} -This should be the first call after the connection to the server has -been made. It sends a line to the server consisting of the -\var{request} string, the \var{selector} string, and the HTTP version -(\code{HTTP/1.1}). To disable automatic sending of \code{Host:} or -\code{Accept-Encoding:} headers (for example to accept additional -content encodings), specify \var{skip_host} or \var{skip_accept_encoding} -with non-False values. -\versionchanged[\var{skip_accept_encoding} argument added]{2.4} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{putheader}{header, argument\optional{, ...}} -Send an \rfc{822}-style header to the server. It sends a line to the -server consisting of the header, a colon and a space, and the first -argument. If more arguments are given, continuation lines are sent, -each consisting of a tab and an argument. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{endheaders}{} -Send a blank line to the server, signalling the end of the headers. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{send}{data} -Send data to the server. This should be used directly only after the -\method{endheaders()} method has been called and before -\method{getresponse()} is called. -\end{methoddesc} - -\subsection{HTTPResponse Objects \label{httpresponse-objects}} - -\class{HTTPResponse} instances have the following methods and attributes: - -\begin{methoddesc}[HTTPResponse]{read}{\optional{amt}} -Reads and returns the response body, or up to the next \var{amt} bytes. -\end{methoddesc} - -\begin{methoddesc}[HTTPResponse]{getheader}{name\optional{, default}} -Get the contents of the header \var{name}, or \var{default} if there is no -matching header. -\end{methoddesc} - -\begin{methoddesc}[HTTPResponse]{getheaders}{} -Return a list of (header, value) tuples. \versionadded{2.4} -\end{methoddesc} - -\begin{memberdesc}[HTTPResponse]{msg} - A \class{mimetools.Message} instance containing the response headers. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{version} - HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{status} - Status code returned by server. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{reason} - Reason phrase returned by server. -\end{memberdesc} - - -\subsection{Examples \label{httplib-examples}} - -Here is an example session that uses the \samp{GET} method: - -\begin{verbatim} ->>> import httplib ->>> conn = httplib.HTTPConnection("www.python.org") ->>> conn.request("GET", "/index.html") ->>> r1 = conn.getresponse() ->>> print r1.status, r1.reason -200 OK ->>> data1 = r1.read() ->>> conn.request("GET", "/parrot.spam") ->>> r2 = conn.getresponse() ->>> print r2.status, r2.reason -404 Not Found ->>> data2 = r2.read() ->>> conn.close() -\end{verbatim} - -Here is an example session that shows how to \samp{POST} requests: - -\begin{verbatim} ->>> import httplib, urllib ->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) ->>> headers = {"Content-type": "application/x-www-form-urlencoded", -... "Accept": "text/plain"} ->>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80") ->>> conn.request("POST", "/cgi-bin/query", params, headers) ->>> response = conn.getresponse() ->>> print response.status, response.reason -200 OK ->>> data = response.read() ->>> conn.close() -\end{verbatim} |