Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 38f3b72

Browse files
freddrakefreddrake
committed
Updated documentation for the new httplib interface, by Kalle Svensson.
This closes SF bug #458447.
1 parent 454af89 commit 38f3b72

2 files changed

Lines changed: 140 additions & 79 deletions

File tree

‎Doc/ACKS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@ Greg Stein
167167
Peter Stoehr
168168
Mark Summerfield
169169
Reuben Sumner
170+
Kalle Svensson
170171
Jim Tittsler
171172
Martijn Vries
172173
Charles G. Waldman

‎Doc/lib/libhttplib.tex‎

Lines changed: 139 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -13,72 +13,121 @@ \section{\module{httplib} ---
1313
available if the \refmodule{socket} module was compiled with SSL
1414
support.}
1515

16-
The module defines one class, \class{HTTP}:
17-
18-
\begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
19-
An \class{HTTP} instance
20-
represents one transaction with an HTTP server. It should be
21-
instantiated passing it a host and optional port number. If no port
22-
number is passed, the port is extracted from the host string if it has
23-
the form \code{\var{host}:\var{port}}, else the default HTTP port (80)
24-
is used. If no host is passed, no connection is made, and the
25-
\method{connect()} method should be used to connect to a server. For
26-
example, the following calls all create instances that connect to the
27-
server at the same host and port:
16+
The constants defined in this module are:
17+
18+
\begin{datadesc}{HTTP_PORT}
19+
The default port for the HTTP protocol (always \code{80}).
20+
\end{datadesc}
21+
22+
\begin{datadesc}{HTTPS_PORT}
23+
The default port for the HTTPS protocol (always \code{443}).
24+
\end{datadesc}
25+
26+
The module provides the following classes:
27+
28+
\begin{classdesc}{HTTPConnection}{host\optional{, port}}
29+
An \class{HTTPConnection} instance represents one transaction with an HTTP
30+
server. It should be instantiated passing it a host and optional port number.
31+
If no port number is passed, the port is extracted from the host string if it
32+
has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is
33+
used. For example, the following calls all create instances that connect to
34+
the server at the same host and port:
2835

2936
\begin{verbatim}
30-
>>> h1 = httplib.HTTP('www.cwi.nl')
31-
>>> h2 = httplib.HTTP('www.cwi.nl:80')
32-
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
37+
>>> h1 = httplib.HTTPConnection('www.cwi.nl')
38+
>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
39+
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
3340
\end{verbatim}
41+
\end{classdesc}
3442

35-
Once an \class{HTTP} instance has been connected to an HTTP server, it
36-
should be used as follows:
43+
\begin{classdesc}{HTTPSConnection}{host\optional{, port}}
44+
A subclass of \class{HTTPConnection} that uses SSL for communication with
45+
secure servers. Default port is \code{443}.
46+
\end{classdesc}
3747

38-
\begin{enumerate}
48+
The following exceptions are raised as appropriate:
3949

40-
\item Make exactly one call to the \method{putrequest()} method.
50+
\begin{excdesc}{HTTPException}
51+
The base class of the other exceptions in this module. It is a
52+
subclass of \exception{Exception}.
53+
\end{excdesc}
4154

42-
\item Make zero or more calls to the \method{putheader()} method.
55+
\begin{excdesc}{NotConnected}
56+
A subclass of \exception{HTTPException}.
57+
\end{excdesc}
4358

44-
\item Call the \method{endheaders()} method (this can be omitted if
45-
step 4 makes no calls).
59+
\begin{excdesc}{UnknownProtocol}
60+
A subclass of \exception{HTTPException}.
61+
\end{excdesc}
4662

47-
\item Optional calls to the \method{send()} method.
63+
\begin{excdesc}{UnknownTransferEncoding}
64+
A subclass of \exception{HTTPException}.
65+
\end{excdesc}
4866

49-
\item Call the \method{getreply()} method.
67+
\begin{excdesc}{IllegalKeywordArgument}
68+
A subclass of \exception{HTTPException}.
69+
\end{excdesc}
5070

51-
\item Call the \method{getfile()} method and read the data off the
52-
file object that it returns.
71+
\begin{excdesc}{UnimplementedFileMode}
72+
A subclass of \exception{HTTPException}.
73+
\end{excdesc}
5374

54-
\end{enumerate}
55-
\end{classdesc}
75+
\begin{excdesc}{IncompleteRead}
76+
A subclass of \exception{HTTPException}.
77+
\end{excdesc}
5678

57-
\begin{datadesc}{HTTP_PORT}
58-
The default port for the HTTP protocol (always \code{80}).
59-
\end{datadesc}
79+
\begin{excdesc}{ImproperConnectionState}
80+
A subclass of \exception{HTTPException}.
81+
\end{excdesc}
6082

61-
\begin{datadesc}{HTTPS_PORT}
62-
The default port for the HTTPS protocol (always \code{443}).
63-
\end{datadesc}
83+
\begin{excdesc}{CannotSendRequest}
84+
A subclass of \exception{ImproperConnectionState}.
85+
\end{excdesc}
6486

87+
\begin{excdesc}{CannotSendHeader}
88+
A subclass of \exception{ImproperConnectionState}.
89+
\end{excdesc}
6590

66-
\subsection{HTTP Objects \label{http-objects}}
91+
\begin{excdesc}{ResponseNotReady}
92+
A subclass of \exception{ImproperConnectionState}.
93+
\end{excdesc}
6794

68-
\class{HTTP} instances have the following methods:
95+
\begin{excdesc}{BadStatusLine}
96+
A subclass of \exception{HTTPException}. Raised if a server responds with a
97+
HTTP status code that we don't understand.
98+
\end{excdesc}
6999

70100

101+
\subsection{HTTPConnection Objects \label{httpconnection-objects}}
102+
103+
\class{HTTPConnection} instances have the following methods:
104+
105+
\begin{methoddesc}{request}{method, url\optional{, body\optional{, headers}}}
106+
This will send a request to the server using the HTTP request method
107+
\var{method} and the selector \var{url}. If the \var{body} argument is
108+
present, it should be a string of data to send after the headers are finished.
109+
The header Content-Length is automatically set to the correct value.
110+
The \var{headers} argument should be a mapping of extra HTTP headers to send
111+
with the request.
112+
\end{methoddesc}
113+
114+
\begin{methoddesc}{getresponse}{}
115+
Should be called after a request is sent to get the response from the server.
116+
Returns an \class{HTTPResponse} instance.
117+
\end{methoddesc}
118+
71119
\begin{methoddesc}{set_debuglevel}{level}
72120
Set the debugging level (the amount of debugging output printed).
73121
The default debug level is \code{0}, meaning no debugging output is
74122
printed.
75123
\end{methoddesc}
76124

77-
\begin{methoddesc}{connect}{host\optional{, port}}
78-
Connect to the server given by \var{host} and \var{port}. See the
79-
introduction to the \refmodule{httplib} module for information on the
80-
default ports. This should be called directly only if the instance
81-
was instantiated without passing a host.
125+
\begin{methoddesc}{connect}{}
126+
Connect to the server specified when the object was created.
127+
\end{methoddesc}
128+
129+
\begin{methoddesc}{close}{}
130+
Close the connection to the server.
82131
\end{methoddesc}
83132

84133
\begin{methoddesc}{send}{data}
@@ -91,11 +140,11 @@ \subsection{HTTP Objects \label{http-objects}}
91140
This should be the first call after the connection to the server has
92141
been made. It sends a line to the server consisting of the
93142
\var{request} string, the \var{selector} string, and the HTTP version
94-
(\code{HTTP/1.0}).
143+
(\code{HTTP/1.1}).
95144
\end{methoddesc}
96145

97146
\begin{methoddesc}{putheader}{header, argument\optional{, ...}}
98-
Send an \rfc{822} style header to the server. It sends a line to the
147+
Send an \rfc{822}-style header to the server. It sends a line to the
99148
server consisting of the header, a colon and a space, and the first
100149
argument. If more arguments are given, continuation lines are sent,
101150
each consisting of a tab and an argument.
@@ -105,58 +154,69 @@ \subsection{HTTP Objects \label{http-objects}}
105154
Send a blank line to the server, signalling the end of the headers.
106155
\end{methoddesc}
107156

108-
\begin{methoddesc}{getreply}{}
109-
Complete the request by shutting down the sending end of the socket,
110-
read the reply from the server, and return a triple
111-
\code{(\var{replycode}, \var{message}, \var{headers})}. Here,
112-
\var{replycode} is the integer reply code from the request (e.g.,
113-
\code{200} if the request was handled properly); \var{message} is the
114-
message string corresponding to the reply code; and \var{headers} is
115-
an instance of the class \class{mimetools.Message} containing the
116-
headers received from the server. See the description of the
117-
\refmodule{mimetools}\refstmodindex{mimetools} module.
157+
158+
\subsection{HTTPResponse Objects \label{httpresponse-objects}}
159+
160+
\class{HTTPResponse} instances have the following methods and attributes:
161+
162+
\begin{methoddesc}{read}{}
163+
Reads and returns the response body.
118164
\end{methoddesc}
119165

120-
\begin{methoddesc}{getfile}{}
121-
Return a file object from which the data returned by the server can be
122-
read, using the \method{read()}, \method{readline()} or
123-
\method{readlines()} methods.
166+
\begin{methoddesc}{getheader}{name\optional{, default}}
167+
Get the contents of the header \var{name}, or \var{default} if there is no
168+
matching header.
124169
\end{methoddesc}
125170

171+
\begin{datadesc}{msg}
172+
A \class{mimetools.Message} instance containing the response headers.
173+
\end{datadesc}
174+
175+
\begin{datadesc}{version}
176+
HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
177+
\end{datadesc}
178+
179+
\begin{datadesc}{status}
180+
Status code returned by server.
181+
\end{datadesc}
182+
183+
\begin{datadesc}{reason}
184+
Reason phrase returned by server.
185+
\end{datadesc}
186+
126187

127188
\subsection{Examples \label{httplib-examples}}
128189

129190
Here is an example session that uses the \samp{GET} method:
130191

131192
\begin{verbatim}
132193
>>> import httplib
133-
>>> h = httplib.HTTP('www.cwi.nl')
134-
>>> h.putrequest('GET', '/index.html')
135-
>>> h.putheader('Accept', 'text/html')
136-
>>> h.putheader('Accept', 'text/plain')
137-
>>> h.putheader('Host', 'www.cwi.nl')
138-
>>> h.endheaders()
139-
>>> errcode, errmsg, headers = h.getreply()
140-
>>> print errcode # Should be 200
141-
>>> f = h.getfile()
142-
>>> data = f.read() # Get the raw HTML
143-
>>> f.close()
194+
>>> conn = httplib.HTTPConnection("www.python.org")
195+
>>> conn.request("GET", "/index.html")
196+
>>> r1 = conn.getresponse()
197+
>>> print r1.status, r1.reason
198+
200 OK
199+
>>> data1 = r1.read()
200+
>>> conn.request("GET", "/parrot.spam")
201+
>>> r2 = conn.getresponse()
202+
>>> print r2.status, r2.reason
203+
404 Not Found
204+
>>> data2 = r2.read()
205+
>>> conn.close()
144206
\end{verbatim}
145207

146208
Here is an example session that shows how to \samp{POST} requests:
147209

148210
\begin{verbatim}
149211
>>> import httplib, urllib
150212
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
151-
>>> h = httplib.HTTP("www.musi-cal.com:80")
152-
>>> h.putrequest("POST", "/cgi-bin/query")
153-
>>> h.putheader("Content-type", "application/x-www-form-urlencoded")
154-
>>> h.putheader("Content-length", "%d" % len(params))
155-
>>> h.putheader('Accept', 'text/plain')
156-
>>> h.putheader('Host', 'www.musi-cal.com')
157-
>>> h.endheaders()
158-
>>> h.send(params)
159-
>>> reply, msg, hdrs = h.getreply()
160-
>>> print reply # should be 200
161-
>>> data = h.getfile().read() # get the raw HTML
213+
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
214+
... "Accept": "text/plain"}
215+
>>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
216+
>>> conn.request("POST", "/cgi-bin/query", params, headers)
217+
>>> response = h.getresponse()
218+
>>> print response.status, response.reason
219+
200 OK
220+
>>> data = response.read()
221+
>>> conn.close()
162222
\end{verbatim}

0 commit comments

Comments
 (0)