rest25/library/socketserver.rst => rest262/library/socketserver.rst
f1
2:mod:`SocketServer` --- A framework for network servers
3=======================================================
4
5.. module:: SocketServer
6   :synopsis: A framework for network servers.
n7+ 
8+.. note::
9+ 
10+   The :mod:`SocketServer` module has been renamed to :mod:`socketserver` in
11+   Python 3.0.  The :term:`2to3` tool will automatically adapt imports when
12+   converting your sources to 3.0.
7
8
9The :mod:`SocketServer` module simplifies the task of writing network servers.
10
11There are four basic server classes: :class:`TCPServer` uses the Internet TCP
12protocol, which provides for continuous streams of data between the client and
13server.  :class:`UDPServer` uses datagrams, which are discrete packets of
14information that may arrive out of order or be lost while in transit.  The more
15infrequently used :class:`UnixStreamServer` and :class:`UnixDatagramServer`
n16-classes are similar, but use Unix domain sockets; they're not available on non-
n22+classes are similar, but use Unix domain sockets; they're not available on
17-Unix platforms.  For more details on network programming, consult a book such as
23+non-Unix platforms.  For more details on network programming, consult a book
24+such as
18W. Richard Steven's UNIX Network Programming or Ralph Davis's Win32 Network
19Programming.
20
21These four classes process requests :dfn:`synchronously`; each request must be
22completed before the next request can be started.  This isn't suitable if each
23request takes a long time to complete, because it requires a lot of computation,
24or because it returns a lot of data which the client is slow to process.  The
25solution is to create a separate process or thread to handle each request; the
38you should explicitly declare how you want your threads to behave on an abrupt
39shutdown. The :class:`ThreadingMixIn` class defines an attribute
40*daemon_threads*, which indicates whether or not the server should wait for
41thread termination. You should set the flag explicitly if you would like threads
42to behave autonomously; the default is :const:`False`, meaning that Python will
43not exit until all threads created by :class:`ThreadingMixIn` have exited.
44
45Server classes have the same external methods and attributes, no matter what
n46-network protocol they use:
n53+network protocol they use.
47
48
49Server Creation Notes
50---------------------
51
52There are five classes in an inheritance diagram, four of which represent
53synchronous servers of four types::
54
107the request handler class :meth:`handle` method.
108
109Another approach to handling multiple simultaneous requests in an environment
110that supports neither threads nor :func:`fork` (or where these are too expensive
111or inappropriate for the service) is to maintain an explicit table of partially
112finished requests and to use :func:`select` to decide which request to work on
113next (or whether to handle a new incoming request).  This is particularly
114important for stream services where each client can potentially be connected for
n115-a long time (if threads or subprocesses cannot be used).
n122+a long time (if threads or subprocesses cannot be used). See :mod:`asyncore` for
123+another way to manage this.
116
n117-.. % XXX should data and methods be intermingled, or separate?
n125+.. XXX should data and methods be intermingled, or separate?
118-.. % how should the distinction between class and instance variables be
126+   how should the distinction between class and instance variables be drawn?
119-.. % drawn?
120
121
122Server Objects
123--------------
124
n132+.. class:: BaseServer
125
n126-.. function:: fileno()
n134+   This is the superclass of all Server objects in the module.  It defines the
135+   interface, given below, but does not implement most of the methods, which is
136+   done in subclasses.
137+ 
138+ 
139+.. method:: BaseServer.fileno()
127
128   Return an integer file descriptor for the socket on which the server is
129   listening.  This function is most commonly passed to :func:`select.select`, to
130   allow monitoring multiple servers in the same process.
131
132
n133-.. function:: handle_request()
n146+.. method:: BaseServer.handle_request()
134
n135-   Process a single request.  This function calls the following methods in order:
n148+   Process a single request.  This function calls the following methods in
136-   :meth:`get_request`, :meth:`verify_request`, and :meth:`process_request`.  If
149+   order: :meth:`get_request`, :meth:`verify_request`, and
137-   the user-provided :meth:`handle` method of the handler class raises an
150+   :meth:`process_request`.  If the user-provided :meth:`handle` method of the
138-   exception, the server's :meth:`handle_error` method will be called.
151+   handler class raises an exception, the server's :meth:`handle_error` method
152+   will be called.  If no request is received within :attr:`self.timeout`
153+   seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`
154+   will return.
139
140
n141-.. function:: serve_forever()
n157+.. method:: BaseServer.serve_forever(poll_interval=0.5)
142
n143-   Handle an infinite number of requests.  This simply calls :meth:`handle_request`
n159+   Handle requests until an explicit :meth:`shutdown` request.  Polls for
144-   inside an infinite loop.
160+   shutdown every *poll_interval* seconds.
145
146
n147-.. data:: address_family
n163+.. method:: BaseServer.shutdown()
164+ 
165+   Tells the :meth:`serve_forever` loop to stop and waits until it does.
166+ 
167+   .. versionadded:: 2.6
168+ 
169+ 
170+.. attribute:: BaseServer.address_family
148
149   The family of protocols to which the server's socket belongs.
n150-   :const:`socket.AF_INET` and :const:`socket.AF_UNIX` are two possible values.
n173+   Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
151
152
n153-.. data:: RequestHandlerClass
n176+.. attribute:: BaseServer.RequestHandlerClass
154
155   The user-provided request handler class; an instance of this class is created
156   for each request.
157
158
n159-.. data:: server_address
n182+.. attribute:: BaseServer.server_address
160
161   The address on which the server is listening.  The format of addresses varies
162   depending on the protocol family; see the documentation for the socket module
163   for details.  For Internet protocols, this is a tuple containing a string giving
164   the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
165
166
n167-.. data:: socket
n190+.. attribute:: BaseServer.socket
168
169   The socket object on which the server will listen for incoming requests.
170
n194+ 
171The server classes support the following class variables:
172
n173-.. % XXX should class variables be covered before instance variables, or
n197+.. XXX should class variables be covered before instance variables, or vice versa?
174-.. % vice versa?
175
n176- 
n199+.. attribute:: BaseServer.allow_reuse_address
177-.. data:: allow_reuse_address
178
179   Whether the server will allow the reuse of an address. This defaults to
180   :const:`False`, and can be set in subclasses to change the policy.
181
182
n183-.. data:: request_queue_size
n205+.. attribute:: BaseServer.request_queue_size
184
185   The size of the request queue.  If it takes a long time to process a single
186   request, any requests that arrive while the server is busy are placed into a
187   queue, up to :attr:`request_queue_size` requests.  Once the queue is full,
188   further requests from clients will get a "Connection denied" error.  The default
189   value is usually 5, but this can be overridden by subclasses.
190
191
n192-.. data:: socket_type
n214+.. attribute:: BaseServer.socket_type
193
194   The type of socket used by the server; :const:`socket.SOCK_STREAM` and
n195-   :const:`socket.SOCK_DGRAM` are two possible values.
n217+   :const:`socket.SOCK_DGRAM` are two common values.
218+ 
219+ 
220+.. attribute:: BaseServer.timeout
221+ 
222+   Timeout duration, measured in seconds, or :const:`None` if no timeout is
223+   desired.  If :meth:`handle_request` receives no incoming requests within the
224+   timeout period, the :meth:`handle_timeout` method is called.
225+ 
196
197There are various server methods that can be overridden by subclasses of base
198server classes like :class:`TCPServer`; these methods aren't useful to external
199users of the server object.
200
n201-.. % should the default implementations of these be documented, or should
n231+.. XXX should the default implementations of these be documented, or should
202-.. % it be assumed that the user will look at SocketServer.py?
232+   it be assumed that the user will look at SocketServer.py?
203
n204- 
n234+.. method:: BaseServer.finish_request()
205-.. function:: finish_request()
206
207   Actually processes the request by instantiating :attr:`RequestHandlerClass` and
208   calling its :meth:`handle` method.
209
210
n211-.. function:: get_request()
n240+.. method:: BaseServer.get_request()
212
213   Must accept a request from the socket, and return a 2-tuple containing the *new*
214   socket object to be used to communicate with the client, and the client's
215   address.
216
217
n218-.. function:: handle_error(request, client_address)
n247+.. method:: BaseServer.handle_error(request, client_address)
219
220   This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`
221   method raises an exception.  The default action is to print the traceback to
222   standard output and continue handling further requests.
223
224
n254+.. method:: BaseServer.handle_timeout()
255+ 
256+   This function is called when the :attr:`timeout` attribute has been set to a
257+   value other than :const:`None` and the timeout period has passed with no
258+   requests being received.  The default action for forking servers is
259+   to collect the status of any child processes that have exited, while
260+   in threading servers this method does nothing.
261+ 
262+ 
225-.. function:: process_request(request, client_address)
263+.. method:: BaseServer.process_request(request, client_address)
226
227   Calls :meth:`finish_request` to create an instance of the
228   :attr:`RequestHandlerClass`.  If desired, this function can create a new process
229   or thread to handle the request; the :class:`ForkingMixIn` and
230   :class:`ThreadingMixIn` classes do this.
231
n270+ 
232-.. Is there any point in documenting the following two functions?
271+.. Is there any point in documenting the following two functions?
233-.. % What would the purpose of overriding them be: initializing server
272+   What would the purpose of overriding them be: initializing server
234-.. % instance variables, adding new network families?
273+   instance variables, adding new network families?
235
n236- 
n275+.. method:: BaseServer.server_activate()
237-.. function:: server_activate()
238
239   Called by the server's constructor to activate the server.  The default behavior
240   just :meth:`listen`\ s to the server's socket. May be overridden.
241
242
n243-.. function:: server_bind()
n281+.. method:: BaseServer.server_bind()
244
245   Called by the server's constructor to bind the socket to the desired address.
246   May be overridden.
247
248
n249-.. function:: verify_request(request, client_address)
n287+.. method:: BaseServer.verify_request(request, client_address)
250
251   Must return a Boolean value; if the value is :const:`True`, the request will be
252   processed, and if it's :const:`False`, the request will be denied. This function
253   can be overridden to implement access controls for a server. The default
254   implementation always returns :const:`True`.
255
256
257RequestHandler Objects
258----------------------
259
260The request handler class must define a new :meth:`handle` method, and can
261override any of the following methods.  A new instance is created for each
262request.
263
264
n265-.. function:: finish()
n303+.. method:: RequestHandler.finish()
266
n267-   Called after the :meth:`handle` method to perform any clean-up actions required.
n305+   Called after the :meth:`handle` method to perform any clean-up actions
268-   The default implementation does nothing.  If :meth:`setup` or :meth:`handle`
306+   required.  The default implementation does nothing.  If :meth:`setup` or
269-   raise an exception, this function will not be called.
307+   :meth:`handle` raise an exception, this function will not be called.
270
271
n272-.. function:: handle()
n310+.. method:: RequestHandler.handle()
273
n274-   This function must do all the work required to service a request. The default
n312+   This function must do all the work required to service a request.  The
275-   implementation does nothing. Several instance attributes are available to it;
313+   default implementation does nothing.  Several instance attributes are
276-   the request is available as :attr:`self.request`; the client address as
314+   available to it; the request is available as :attr:`self.request`; the client
277-   :attr:`self.client_address`; and the server instance as :attr:`self.server`, in
315+   address as :attr:`self.client_address`; and the server instance as
278-   case it needs access to per-server information.
316+   :attr:`self.server`, in case it needs access to per-server information.
279
n280-   The type of :attr:`self.request` is different for datagram or stream services.
n318+   The type of :attr:`self.request` is different for datagram or stream
281-   For stream services, :attr:`self.request` is a socket object; for datagram
319+   services.  For stream services, :attr:`self.request` is a socket object; for
282-   services, :attr:`self.request` is a string. However, this can be hidden by using
320+   datagram services, :attr:`self.request` is a pair of string and socket.
283-   the  request handler subclasses :class:`StreamRequestHandler` or
321+   However, this can be hidden by using the request handler subclasses
284-   :class:`DatagramRequestHandler`, which override the :meth:`setup` and
322+   :class:`StreamRequestHandler` or :class:`DatagramRequestHandler`, which
285-   :meth:`finish` methods, and provide :attr:`self.rfile` and :attr:`self.wfile`
323+   override the :meth:`setup` and :meth:`finish` methods, and provide
286-   attributes. :attr:`self.rfile` and :attr:`self.wfile` can be read or written,
324+   :attr:`self.rfile` and :attr:`self.wfile` attributes.  :attr:`self.rfile` and
287-   respectively, to get the request data or return data to the client.
325+   :attr:`self.wfile` can be read or written, respectively, to get the request
326+   data or return data to the client.
288
289
n290-.. function:: setup()
n329+.. method:: RequestHandler.setup()
291
292   Called before the :meth:`handle` method to perform any initialization actions
293   required.  The default implementation does nothing.
294
t334+ 
335+Examples
336+--------
337+ 
338+:class:`SocketServer.TCPServer` Example
339+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340+ 
341+This is the server side::
342+ 
343+   import SocketServer
344+ 
345+   class MyTCPHandler(SocketServer.BaseRequestHandler):
346+       """
347+       The RequestHandler class for our server.
348+ 
349+       It is instantiated once per connection to the server, and must
350+       override the handle() method to implement communication to the
351+       client.
352+       """
353+ 
354+       def handle(self):
355+           # self.request is the TCP socket connected to the client
356+           self.data = self.request.recv(1024).strip()
357+           print "%s wrote:" % self.client_address[0]
358+           print self.data
359+           # just send back the same data, but upper-cased
360+           self.request.send(self.data.upper())
361+ 
362+   if __name__ == "__main__":
363+       HOST, PORT = "localhost", 9999
364+ 
365+       # Create the server, binding to localhost on port 9999
366+       server = SocketServer.TCPServer((HOST, PORT), MyTCPHandler)
367+ 
368+       # Activate the server; this will keep running until you
369+       # interrupt the program with Ctrl-C
370+       server.serve_forever()
371+ 
372+An alternative request handler class that makes use of streams (file-like
373+objects that simplify communication by providing the standard file interface)::
374+ 
375+   class MyTCPHandler(SocketServer.StreamRequestHandler):
376+ 
377+       def handle(self):
378+           # self.rfile is a file-like object created by the handler;
379+           # we can now use e.g. readline() instead of raw recv() calls
380+           self.data = self.rfile.readline().strip()
381+           print "%s wrote:" % self.client_address[0]
382+           print self.data
383+           # Likewise, self.wfile is a file-like object used to write back
384+           # to the client
385+           self.wfile.write(self.data.upper())
386+ 
387+The difference is that the ``readline()`` call in the second handler will call
388+``recv()`` multiple times until it encounters a newline character, while the
389+single ``recv()`` call in the first handler will just return what has been sent
390+from the client in one ``send()`` call.
391+ 
392+ 
393+This is the client side::
394+ 
395+   import socket
396+   import sys
397+ 
398+   HOST, PORT = "localhost", 9999
399+   data = " ".join(sys.argv[1:])
400+ 
401+   # Create a socket (SOCK_STREAM means a TCP socket)
402+   sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
403+ 
404+   # Connect to server and send data
405+   sock.connect((HOST, PORT))
406+   sock.send(data + "\n")
407+ 
408+   # Receive data from the server and shut down
409+   received = sock.recv(1024)
410+   sock.close()
411+ 
412+   print "Sent:     %s" % data
413+   print "Received: %s" % received
414+ 
415+ 
416+The output of the example should look something like this:
417+ 
418+Server::
419+ 
420+   $ python TCPServer.py
421+   127.0.0.1 wrote:
422+   hello world with TCP
423+   127.0.0.1 wrote:
424+   python is nice
425+ 
426+Client::
427+ 
428+   $ python TCPClient.py hello world with TCP
429+   Sent:     hello world with TCP
430+   Received: HELLO WORLD WITH TCP
431+   $ python TCPClient.py python is nice
432+   Sent:     python is nice
433+   Received: PYTHON IS NICE
434+ 
435+ 
436+:class:`SocketServer.UDPServer` Example
437+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
438+ 
439+This is the server side::
440+ 
441+   import SocketServer
442+ 
443+   class MyUDPHandler(SocketServer.BaseRequestHandler):
444+       """
445+       This class works similar to the TCP handler class, except that
446+       self.request consists of a pair of data and client socket, and since
447+       there is no connection the client address must be given explicitly
448+       when sending data back via sendto().
449+       """
450+ 
451+       def handle(self):
452+           data = self.request[0].strip()
453+           socket = self.request[1]
454+           print "%s wrote:" % self.client_address[0]
455+           print data
456+           socket.sendto(data.upper(), self.client_address)
457+ 
458+   if __name__ == "__main__":
459+      HOST, PORT = "localhost", 9999
460+      server = SocketServer.UDPServer((HOST, PORT), MyUDPHandler)
461+      server.serve_forever()
462+ 
463+This is the client side::
464+ 
465+   import socket
466+   import sys
467+ 
468+   HOST, PORT = "localhost"
469+   data = " ".join(sys.argv[1:])
470+ 
471+   # SOCK_DGRAM is the socket type to use for UDP sockets
472+   sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
473+ 
474+   # As you can see, there is no connect() call; UDP has no connections.
475+   # Instead, data is directly sent to the recipient via sendto().
476+   sock.sendto(data + "\n", (HOST, PORT))
477+   received = sock.recv(1024)
478+ 
479+   print "Sent:     %s" % data
480+   print "Received: %s" % received
481+ 
482+The output of the example should look exactly like for the TCP server example.
483+ 
484+ 
485+Asynchronous Mixins
486+~~~~~~~~~~~~~~~~~~~
487+ 
488+To build asynchronous handlers, use the :class:`ThreadingMixIn` and
489+:class:`ForkingMixIn` classes.
490+ 
491+An example for the :class:`ThreadingMixIn` class::
492+ 
493+   import socket
494+   import threading
495+   import SocketServer
496+ 
497+   class ThreadedTCPRequestHandler(SocketServer.BaseRequestHandler):
498+ 
499+       def handle(self):
500+           data = self.request.recv(1024)
501+           cur_thread = threading.currentThread()
502+           response = "%s: %s" % (cur_thread.getName(), data)
503+           self.request.send(response)
504+ 
505+   class ThreadedTCPServer(SocketServer.ThreadingMixIn, SocketServer.TCPServer):
506+       pass
507+ 
508+   def client(ip, port, message):
509+       sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
510+       sock.connect((ip, port))
511+       sock.send(message)
512+       response = sock.recv(1024)
513+       print "Received: %s" % response
514+       sock.close()
515+ 
516+   if __name__ == "__main__":
517+       # Port 0 means to select an arbitrary unused port
518+       HOST, PORT = "localhost", 0
519+ 
520+       server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
521+       ip, port = server.server_address
522+ 
523+       # Start a thread with the server -- that thread will then start one
524+       # more thread for each request
525+       server_thread = threading.Thread(target=server.serve_forever)
526+       # Exit the server thread when the main thread terminates
527+       server_thread.setDaemon(True)
528+       server_thread.start()
529+       print "Server loop running in thread:", server_thread.getName()
530+ 
531+       client(ip, port, "Hello World 1")
532+       client(ip, port, "Hello World 2")
533+       client(ip, port, "Hello World 3")
534+ 
535+       server.shutdown()
536+ 
537+The output of the example should look something like this::
538+ 
539+   $ python ThreadedTCPServer.py
540+   Server loop running in thread: Thread-1
541+   Received: Thread-2: Hello World 1
542+   Received: Thread-3: Hello World 2
543+   Received: Thread-4: Hello World 3
544+ 
545+ 
546+The :class:`ForkingMixIn` class is used in the same way, except that the server
547+will spawn a new process for each request.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op