Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsocksvr.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents a22caf129345
children 84b43ff42fa8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5548
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{SocketServer}}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{SocketServer}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 The \code{SocketServer} module simplifies the task of writing network
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 servers.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 There are four basic server classes: \code{TCPServer} uses the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 Internet TCP protocol, which provides for continuous streams of data
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 between the client and server. \code{UDPServer} uses datagrams, which
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 are discrete packets of information that may arrive out of order or be
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 lost while in transit. The more infrequently used
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \code{UnixStreamServer} and \code{UnixDatagramServer} classes are
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 similar, but use Unix domain sockets; they're not available on
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 non-Unix platforms. For more details on network programming, consult
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 a book such as W. Richard Steven's \emph{Unix Network Programming}_ or
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 XXX (a Windows equivalent).
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 These four classes process requests \dfn{synchronously}; each request
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 must be completed before the next request can be started. This isn't
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 suitable if each request takes a long time to complete, because it
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 requires a lot of computation, or because it returns a lot of data
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 which the client is slow to process. The solution is to create a
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 separate process or thread to handle each request; the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \code{ForkingMixIn} and \code{ThreadingMixIn} mix-in classes can be
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 used to support asynchronous behaviour.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
26
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 Creating a server requires several steps. First, you must create a
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 request handler class by subclassing the \code{BaseRequestHandler}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 class and overriding its \code{handle()} method; this method will
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 process incoming requests. Second, you must instantiate one of the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 server classes, passing it the server's address and the request
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 handler class. Finally, call the \code{handle_request()} or
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \code{serve_forever()} method of the server object to process one or
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 many requests.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 Server classes have the same external methods and attributes, no
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 matter what network protocol they use:
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 %XXX should data and methods be intermingled, or separate?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 % how should the distinction between class and instance variables be
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 % drawn?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \begin{funcdesc}{fileno}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 Return an integer file descriptor for the socket on which the server
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 is listening. This function is most commonly passed to
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \code{select.select()}, to allow monitoring multiple servers in the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 same process.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
49
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 \begin{funcdesc}{handle_request}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 Process a single request. This function calls the following methods
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 in order: \code{get_request()}, \code{verify_request()}, and
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 \code{process_request()}. If the user-provided \code{handle()} method
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 of the handler class raises an exception, the server's
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \code{handle_error()} method will be called.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \begin{funcdesc}{serve_forever}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Handle an infinite number of requests. This simply calls
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \code{handle_request()} inside an infinite loop.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
62
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \begin{datadesc}{address_family}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 The family of protocols to which the server's socket belongs.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \code{socket.AF_INET} and \code{socket.AF_UNIX} are two possible values.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \begin{datadesc}{RequestHandlerClass}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 The user-provided request handler class; an instance of this class is
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 created for each request.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
72
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \begin{datadesc}{server_address}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 The address on which the server is listening. The format of addresses
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 varies depending on the protocol family; see the documentation for the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 socket module for details. For Internet protocols, this is a tuple
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 containing a string giving the address, and an integer port number:
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \code{('127.0.0.1', 80)}, for example.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
80
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 \begin{datadesc}{socket}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 The socket object on which the server will listen for incoming requests.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
84
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 % XXX should class variables be covered before instance variables, or
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 % vice versa?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
87
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 The server classes support the following class variables:
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
89
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \begin{datadesc}{request_queue_size}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 The size of the request queue. If it takes a long time to process a
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 single request, any requests that arrive while the server is busy are
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 placed into a queue, up to \code{request_queue_size} requests. Once
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 the queue is full, further requests from clients will get a
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 ``Connection denied'' error. The default value is usually 5, but this
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 can be overridden by subclasses.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 \begin{datadesc}{socket_type}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 The type of socket used by the server; \code{socket.SOCK_STREAM} and
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 \code{socket.SOCK_DGRAM} are two possible values.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 \end{datadesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
103
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 There are various server methods that can be overridden by subclasses
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 of base server classes like \code{TCPServer}; these methods aren't
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 useful to external users of the server object.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 % should the default implementations of these be documented, or should
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 % it be assumed that the user will look at SocketServer.py?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
110
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 \begin{funcdesc}{finish_request}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 Actually processes the request by instantiating
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 \code{RequestHandlerClass} and calling its \code{handle()} method.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
115
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 \begin{funcdesc}{get_request}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 Must accept a request from the socket, and return a 2-tuple containing
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 the \emph{new} socket object to be used to communicate with the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 client, and the client's address.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
121
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 \begin{funcdesc}{handle_error}{request\, client_address}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 This function is called if the \code{RequestHandlerClass}'s
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 \code{handle} method raises an exception. The default action is to print
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 the traceback to standard output and continue handling further requests.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
127
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 \begin{funcdesc}{process_request}{request\, client_address}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 Calls \code{finish_request()} to create an instance of the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 \code{RequestHandlerClass}. If desired, this function can create a new
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 process or thread to handle the request; the \code{ForkingMixIn} and
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 \code{ThreadingMixIn} classes do this.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 % Is there any point in documenting the following two functions?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 % What would the purpose of overriding them be: initializing server
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 % instance variables, adding new network families?
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
138
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \begin{funcdesc}{server_activate}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 Called by the server's constructor to activate the server.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
141 May be overridden.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
143
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \begin{funcdesc}{server_bind}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 Called by the server's constructor to bind the socket to the desired
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 address. May be overridden.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
148
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 \begin{funcdesc}{verify_request}{request\, client_address}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 Must return a Boolean value; if the value is true, the request will be
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 processed, and if it's false, the request will be denied.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 This function can be overridden to implement access controls for a server.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 The default implementation always return true.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
155
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 The request handler class must define a new \code{handle} method, and
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 can override any of the following methods. A new instance is created
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
158 for each request.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
159
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
160 \begin{funcdesc}{finish}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
161 Called after the \code{handle} method to perform any clean-up actions
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 required. The default implementation does nothing. If \code{setup()}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
163 or \code{handle()} raise an exception, this function will not be called.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
165
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 \begin{funcdesc}{handle}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
167 This function must do all the work required to service a request.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 Several instance attributes are available to it; the request is
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 available as \code{self.request}; the client address as
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 \code{self.client_request}; and the server instance as \code{self.server}, in
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 case it needs access to per-server information.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
172
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 The type of \code{self.request} is different for datagram or stream
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 services. For stream services, \code{self.request} is a socket
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 object; for datagram services, \code{self.request} is a string.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 However, this can be hidden by using the mix-in request handler
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
177 classes
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \code{StreamRequestHandler} or \code{DatagramRequestHandler}, which
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
179 override the \code{setup} and \code{finish} methods, and provides
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \code{self.rfile} and \code{self.wfile} attributes. \code{self.rfile}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 and \code{self.wfile} can be read or written, respectively, to get the
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 request data or return data to the client.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 \end{funcdesc}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
184
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 \begin{funcdesc}{setup}{}
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 Called before the \code{handle} method to perform any initialization
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 actions required. The default implementation does nothing.
a22caf129345 Added AMK's SocketServer docs.
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 \end{funcdesc}