summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libhttplib.tex
blob: 55ec9b9899847219d418f8d32ec2903929e161ea (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
\section{Standard Module \module{httplib}}
\label{module-httplib}
\stmodindex{httplib}
\indexii{HTTP}{protocol}


This module defines a class which implements the client side of the
HTTP protocol.  It is normally not used directly --- the module
\module{urllib}\refstmodindex{urllib} uses it to handle URLs that use
HTTP.

The module defines one class, \class{HTTP}:

\begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
An \class{HTTP} 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.  If no host is passed, no connection is made, and the
\method{connect()} method should be used to connect to a server.  For
example, the following calls all create instances that connect to the
server at the same host and port:

\begin{verbatim}
>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
\end{verbatim}

Once an \class{HTTP} instance has been connected to an HTTP server, it
should be used as follows:

\begin{enumerate}

\item[1.] Make exactly one call to the \method{putrequest()} method.

\item[2.] Make zero or more calls to the \method{putheader()} method.

\item[3.] Call the \method{endheaders()} method (this can be omitted if
step 4 makes no calls).

\item[4.] Optional calls to the \method{send()} method.

\item[5.] Call the \method{getreply()} method.

\item[6.] Call the \method{getfile()} method and read the data off the
file object that it returns.

\end{enumerate}
\end{classdesc}

\subsection{HTTP Objects}

\class{HTTP} instances have the following methods:


\begin{methoddesc}{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}{connect}{host\optional{, port}}
Connect to the server given by \var{host} and \var{port}.  See the
intro for the default port.  This should be called directly only if
the instance was instantiated without passing a host.
\end{methoddesc}

\begin{methoddesc}{send}{data}
Send data to the server.  This should be used directly only after the
\method{endheaders()} method has been called and before
\method{getreply()} has been called.
\end{methoddesc}

\begin{methoddesc}{putrequest}{request, selector}
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.0}).
\end{methoddesc}

\begin{methoddesc}{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}{endheaders}{}
Send a blank line to the server, signalling the end of the headers.
\end{methoddesc}

\begin{methoddesc}{getreply}{}
Complete the request by shutting down the sending end of the socket,
read the reply from the server, and return a triple
\code{(\var{replycode}, \var{message}, \var{headers})}.  Here,
\var{replycode} is the integer reply code from the request (e.g.\
\code{200} if the request was handled properly); \var{message} is the
message string corresponding to the reply code; and \var{headers} is
an instance of the class \class{mimetools.Message} containing the
headers received from the server.  See the description of the
\module{mimetools}\refstmodindex{mimetools} module.
\end{methoddesc}

\begin{methoddesc}{getfile}{}
Return a file object from which the data returned by the server can be
read, using the \method{read()}, \method{readline()} or
\method{readlines()} methods.
\end{methoddesc}

\subsection{Example}
\nodename{HTTP Example}

Here is an example session:

\begin{verbatim}
>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
>>> h.putheader('Accept', 'text/html')
>>> h.putheader('Accept', 'text/plain')
>>> h.endheaders()
>>> errcode, errmsg, headers = h.getreply()
>>> print errcode # Should be 200
>>> f = h.getfile()
>>> data = f.read() # Get the raw HTML
>>> f.close()
\end{verbatim}