• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`socketserver` --- A framework for network servers
2=======================================================
3
4.. module:: socketserver
5   :synopsis: A framework for network servers.
6
7**Source code:** :source:`Lib/socketserver.py`
8
9--------------
10
11The :mod:`socketserver` module simplifies the task of writing network servers.
12
13There are four basic concrete server classes:
14
15
16.. class:: TCPServer(server_address, RequestHandlerClass, bind_and_activate=True)
17
18   This uses the internet TCP protocol, which provides for
19   continuous streams of data between the client and server.
20   If *bind_and_activate* is true, the constructor automatically attempts to
21   invoke :meth:`~BaseServer.server_bind` and
22   :meth:`~BaseServer.server_activate`.  The other parameters are passed to
23   the :class:`BaseServer` base class.
24
25
26.. class:: UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)
27
28   This uses datagrams, which are discrete packets of information that may
29   arrive out of order or be lost while in transit.  The parameters are
30   the same as for :class:`TCPServer`.
31
32
33.. class:: UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)
34           UnixDatagramServer(server_address, RequestHandlerClass, bind_and_activate=True)
35
36   These more infrequently used classes are similar to the TCP and
37   UDP classes, but use Unix domain sockets; they're not available on
38   non-Unix platforms.  The parameters are the same as for
39   :class:`TCPServer`.
40
41
42These four classes process requests :dfn:`synchronously`; each request must be
43completed before the next request can be started.  This isn't suitable if each
44request takes a long time to complete, because it requires a lot of computation,
45or because it returns a lot of data which the client is slow to process.  The
46solution is to create a separate process or thread to handle each request; the
47:class:`ForkingMixIn` and :class:`ThreadingMixIn` mix-in classes can be used to
48support asynchronous behaviour.
49
50Creating a server requires several steps.  First, you must create a request
51handler class by subclassing the :class:`BaseRequestHandler` class and
52overriding its :meth:`~BaseRequestHandler.handle` method;
53this method will process incoming
54requests.  Second, you must instantiate one of the server classes, passing it
55the server's address and the request handler class. It is recommended to use
56the server in a :keyword:`with` statement. Then call the
57:meth:`~BaseServer.handle_request` or
58:meth:`~BaseServer.serve_forever` method of the server object to
59process one or many requests.  Finally, call :meth:`~BaseServer.server_close`
60to close the socket (unless you used a :keyword:`!with` statement).
61
62When inheriting from :class:`ThreadingMixIn` for threaded connection behavior,
63you should explicitly declare how you want your threads to behave on an abrupt
64shutdown.  The :class:`ThreadingMixIn` class defines an attribute
65*daemon_threads*, which indicates whether or not the server should wait for
66thread termination.  You should set the flag explicitly if you would like
67threads to behave autonomously; the default is :const:`False`, meaning that
68Python will not exit until all threads created by :class:`ThreadingMixIn` have
69exited.
70
71Server classes have the same external methods and attributes, no matter what
72network protocol they use.
73
74
75Server Creation Notes
76---------------------
77
78There are five classes in an inheritance diagram, four of which represent
79synchronous servers of four types::
80
81   +------------+
82   | BaseServer |
83   +------------+
84         |
85         v
86   +-----------+        +------------------+
87   | TCPServer |------->| UnixStreamServer |
88   +-----------+        +------------------+
89         |
90         v
91   +-----------+        +--------------------+
92   | UDPServer |------->| UnixDatagramServer |
93   +-----------+        +--------------------+
94
95Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from
96:class:`UnixStreamServer` --- the only difference between an IP and a Unix
97stream server is the address family, which is simply repeated in both Unix
98server classes.
99
100
101.. class:: ForkingMixIn
102           ThreadingMixIn
103
104   Forking and threading versions of each type of server can be created
105   using these mix-in classes.  For instance, :class:`ThreadingUDPServer`
106   is created as follows::
107
108      class ThreadingUDPServer(ThreadingMixIn, UDPServer):
109          pass
110
111   The mix-in class comes first, since it overrides a method defined in
112   :class:`UDPServer`.  Setting the various attributes also changes the
113   behavior of the underlying server mechanism.
114
115   :class:`ForkingMixIn` and the Forking classes mentioned below are
116   only available on POSIX platforms that support :func:`~os.fork`.
117
118   :meth:`socketserver.ForkingMixIn.server_close` waits until all child
119   processes complete, except if
120   :attr:`socketserver.ForkingMixIn.block_on_close` attribute is false.
121
122   :meth:`socketserver.ThreadingMixIn.server_close` waits until all non-daemon
123   threads complete, except if
124   :attr:`socketserver.ThreadingMixIn.block_on_close` attribute is false. Use
125   daemonic threads by setting
126   :data:`ThreadingMixIn.daemon_threads` to ``True`` to not wait until threads
127   complete.
128
129   .. versionchanged:: 3.7
130
131      :meth:`socketserver.ForkingMixIn.server_close` and
132      :meth:`socketserver.ThreadingMixIn.server_close` now waits until all
133      child processes and non-daemonic threads complete.
134      Add a new :attr:`socketserver.ForkingMixIn.block_on_close` class
135      attribute to opt-in for the pre-3.7 behaviour.
136
137
138.. class:: ForkingTCPServer
139           ForkingUDPServer
140           ThreadingTCPServer
141           ThreadingUDPServer
142
143   These classes are pre-defined using the mix-in classes.
144
145
146To implement a service, you must derive a class from :class:`BaseRequestHandler`
147and redefine its :meth:`~BaseRequestHandler.handle` method.
148You can then run various versions of
149the service by combining one of the server classes with your request handler
150class.  The request handler class must be different for datagram or stream
151services.  This can be hidden by using the handler subclasses
152:class:`StreamRequestHandler` or :class:`DatagramRequestHandler`.
153
154Of course, you still have to use your head!  For instance, it makes no sense to
155use a forking server if the service contains state in memory that can be
156modified by different requests, since the modifications in the child process
157would never reach the initial state kept in the parent process and passed to
158each child.  In this case, you can use a threading server, but you will probably
159have to use locks to protect the integrity of the shared data.
160
161On the other hand, if you are building an HTTP server where all data is stored
162externally (for instance, in the file system), a synchronous class will
163essentially render the service "deaf" while one request is being handled --
164which may be for a very long time if a client is slow to receive all the data it
165has requested.  Here a threading or forking server is appropriate.
166
167In some cases, it may be appropriate to process part of a request synchronously,
168but to finish processing in a forked child depending on the request data.  This
169can be implemented by using a synchronous server and doing an explicit fork in
170the request handler class :meth:`~BaseRequestHandler.handle` method.
171
172Another approach to handling multiple simultaneous requests in an environment
173that supports neither threads nor :func:`~os.fork` (or where these are too
174expensive or inappropriate for the service) is to maintain an explicit table of
175partially finished requests and to use :mod:`selectors` to decide which
176request to work on next (or whether to handle a new incoming request).  This is
177particularly important for stream services where each client can potentially be
178connected for a long time (if threads or subprocesses cannot be used).  See
179:mod:`asyncore` for another way to manage this.
180
181.. XXX should data and methods be intermingled, or separate?
182   how should the distinction between class and instance variables be drawn?
183
184
185Server Objects
186--------------
187
188.. class:: BaseServer(server_address, RequestHandlerClass)
189
190   This is the superclass of all Server objects in the module.  It defines the
191   interface, given below, but does not implement most of the methods, which is
192   done in subclasses.  The two parameters are stored in the respective
193   :attr:`server_address` and :attr:`RequestHandlerClass` attributes.
194
195
196   .. method:: fileno()
197
198      Return an integer file descriptor for the socket on which the server is
199      listening.  This function is most commonly passed to :mod:`selectors`, to
200      allow monitoring multiple servers in the same process.
201
202
203   .. method:: handle_request()
204
205      Process a single request.  This function calls the following methods in
206      order: :meth:`get_request`, :meth:`verify_request`, and
207      :meth:`process_request`.  If the user-provided
208      :meth:`~BaseRequestHandler.handle` method of the
209      handler class raises an exception, the server's :meth:`handle_error` method
210      will be called.  If no request is received within :attr:`timeout`
211      seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`
212      will return.
213
214
215   .. method:: serve_forever(poll_interval=0.5)
216
217      Handle requests until an explicit :meth:`shutdown` request.  Poll for
218      shutdown every *poll_interval* seconds.
219      Ignores the :attr:`timeout` attribute.  It
220      also calls :meth:`service_actions`, which may be used by a subclass or mixin
221      to provide actions specific to a given service.  For example, the
222      :class:`ForkingMixIn` class uses :meth:`service_actions` to clean up zombie
223      child processes.
224
225      .. versionchanged:: 3.3
226         Added ``service_actions`` call to the ``serve_forever`` method.
227
228
229   .. method:: service_actions()
230
231      This is called in the :meth:`serve_forever` loop. This method can be
232      overridden by subclasses or mixin classes to perform actions specific to
233      a given service, such as cleanup actions.
234
235      .. versionadded:: 3.3
236
237   .. method:: shutdown()
238
239      Tell the :meth:`serve_forever` loop to stop and wait until it does.
240      :meth:`shutdown` must be called while :meth:`serve_forever` is running in a
241      different thread otherwise it will deadlock.
242
243
244   .. method:: server_close()
245
246      Clean up the server. May be overridden.
247
248
249   .. attribute:: address_family
250
251      The family of protocols to which the server's socket belongs.
252      Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
253
254
255   .. attribute:: RequestHandlerClass
256
257      The user-provided request handler class; an instance of this class is created
258      for each request.
259
260
261   .. attribute:: server_address
262
263      The address on which the server is listening.  The format of addresses varies
264      depending on the protocol family;
265      see the documentation for the :mod:`socket` module
266      for details.  For internet protocols, this is a tuple containing a string giving
267      the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
268
269
270   .. attribute:: socket
271
272      The socket object on which the server will listen for incoming requests.
273
274
275   The server classes support the following class variables:
276
277   .. XXX should class variables be covered before instance variables, or vice versa?
278
279   .. attribute:: allow_reuse_address
280
281      Whether the server will allow the reuse of an address.  This defaults to
282      :const:`False`, and can be set in subclasses to change the policy.
283
284
285   .. attribute:: request_queue_size
286
287      The size of the request queue.  If it takes a long time to process a single
288      request, any requests that arrive while the server is busy are placed into a
289      queue, up to :attr:`request_queue_size` requests.  Once the queue is full,
290      further requests from clients will get a "Connection denied" error.  The default
291      value is usually 5, but this can be overridden by subclasses.
292
293
294   .. attribute:: socket_type
295
296      The type of socket used by the server; :const:`socket.SOCK_STREAM` and
297      :const:`socket.SOCK_DGRAM` are two common values.
298
299
300   .. attribute:: timeout
301
302      Timeout duration, measured in seconds, or :const:`None` if no timeout is
303      desired.  If :meth:`handle_request` receives no incoming requests within the
304      timeout period, the :meth:`handle_timeout` method is called.
305
306
307   There are various server methods that can be overridden by subclasses of base
308   server classes like :class:`TCPServer`; these methods aren't useful to external
309   users of the server object.
310
311   .. XXX should the default implementations of these be documented, or should
312      it be assumed that the user will look at socketserver.py?
313
314   .. method:: finish_request(request, client_address)
315
316      Actually processes the request by instantiating :attr:`RequestHandlerClass` and
317      calling its :meth:`~BaseRequestHandler.handle` method.
318
319
320   .. method:: get_request()
321
322      Must accept a request from the socket, and return a 2-tuple containing the *new*
323      socket object to be used to communicate with the client, and the client's
324      address.
325
326
327   .. method:: handle_error(request, client_address)
328
329      This function is called if the :meth:`~BaseRequestHandler.handle`
330      method of a :attr:`RequestHandlerClass` instance raises
331      an exception.  The default action is to print the traceback to
332      standard error and continue handling further requests.
333
334      .. versionchanged:: 3.6
335         Now only called for exceptions derived from the :exc:`Exception`
336         class.
337
338
339   .. method:: handle_timeout()
340
341      This function is called when the :attr:`timeout` attribute has been set to a
342      value other than :const:`None` and the timeout period has passed with no
343      requests being received.  The default action for forking servers is
344      to collect the status of any child processes that have exited, while
345      in threading servers this method does nothing.
346
347
348   .. method:: process_request(request, client_address)
349
350      Calls :meth:`finish_request` to create an instance of the
351      :attr:`RequestHandlerClass`.  If desired, this function can create a new process
352      or thread to handle the request; the :class:`ForkingMixIn` and
353      :class:`ThreadingMixIn` classes do this.
354
355
356   .. Is there any point in documenting the following two functions?
357      What would the purpose of overriding them be: initializing server
358      instance variables, adding new network families?
359
360   .. method:: server_activate()
361
362      Called by the server's constructor to activate the server.  The default behavior
363      for a TCP server just invokes :meth:`~socket.socket.listen`
364      on the server's socket.  May be overridden.
365
366
367   .. method:: server_bind()
368
369      Called by the server's constructor to bind the socket to the desired address.
370      May be overridden.
371
372
373   .. method:: verify_request(request, client_address)
374
375      Must return a Boolean value; if the value is :const:`True`, the request will
376      be processed, and if it's :const:`False`, the request will be denied.  This
377      function can be overridden to implement access controls for a server. The
378      default implementation always returns :const:`True`.
379
380
381   .. versionchanged:: 3.6
382      Support for the :term:`context manager` protocol was added.  Exiting the
383      context manager is equivalent to calling :meth:`server_close`.
384
385
386Request Handler Objects
387-----------------------
388
389.. class:: BaseRequestHandler
390
391   This is the superclass of all request handler objects.  It defines
392   the interface, given below.  A concrete request handler subclass must
393   define a new :meth:`handle` method, and can override any of
394   the other methods.  A new instance of the subclass is created for each
395   request.
396
397
398   .. method:: setup()
399
400      Called before the :meth:`handle` method to perform any initialization actions
401      required.  The default implementation does nothing.
402
403
404   .. method:: handle()
405
406      This function must do all the work required to service a request.  The
407      default implementation does nothing.  Several instance attributes are
408      available to it; the request is available as :attr:`self.request`; the client
409      address as :attr:`self.client_address`; and the server instance as
410      :attr:`self.server`, in case it needs access to per-server information.
411
412      The type of :attr:`self.request` is different for datagram or stream
413      services.  For stream services, :attr:`self.request` is a socket object; for
414      datagram services, :attr:`self.request` is a pair of string and socket.
415
416
417   .. method:: finish()
418
419      Called after the :meth:`handle` method to perform any clean-up actions
420      required.  The default implementation does nothing.  If :meth:`setup`
421      raises an exception, this function will not be called.
422
423
424.. class:: StreamRequestHandler
425           DatagramRequestHandler
426
427   These :class:`BaseRequestHandler` subclasses override the
428   :meth:`~BaseRequestHandler.setup` and :meth:`~BaseRequestHandler.finish`
429   methods, and provide :attr:`self.rfile` and :attr:`self.wfile` attributes.
430   The :attr:`self.rfile` and :attr:`self.wfile` attributes can be
431   read or written, respectively, to get the request data or return data
432   to the client.
433
434   The :attr:`rfile` attributes of both classes support the
435   :class:`io.BufferedIOBase` readable interface, and
436   :attr:`DatagramRequestHandler.wfile` supports the
437   :class:`io.BufferedIOBase` writable interface.
438
439   .. versionchanged:: 3.6
440      :attr:`StreamRequestHandler.wfile` also supports the
441      :class:`io.BufferedIOBase` writable interface.
442
443
444Examples
445--------
446
447:class:`socketserver.TCPServer` Example
448~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
449
450This is the server side::
451
452   import socketserver
453
454   class MyTCPHandler(socketserver.BaseRequestHandler):
455       """
456       The request handler class for our server.
457
458       It is instantiated once per connection to the server, and must
459       override the handle() method to implement communication to the
460       client.
461       """
462
463       def handle(self):
464           # self.request is the TCP socket connected to the client
465           self.data = self.request.recv(1024).strip()
466           print("{} wrote:".format(self.client_address[0]))
467           print(self.data)
468           # just send back the same data, but upper-cased
469           self.request.sendall(self.data.upper())
470
471   if __name__ == "__main__":
472       HOST, PORT = "localhost", 9999
473
474       # Create the server, binding to localhost on port 9999
475       with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
476           # Activate the server; this will keep running until you
477           # interrupt the program with Ctrl-C
478           server.serve_forever()
479
480An alternative request handler class that makes use of streams (file-like
481objects that simplify communication by providing the standard file interface)::
482
483   class MyTCPHandler(socketserver.StreamRequestHandler):
484
485       def handle(self):
486           # self.rfile is a file-like object created by the handler;
487           # we can now use e.g. readline() instead of raw recv() calls
488           self.data = self.rfile.readline().strip()
489           print("{} wrote:".format(self.client_address[0]))
490           print(self.data)
491           # Likewise, self.wfile is a file-like object used to write back
492           # to the client
493           self.wfile.write(self.data.upper())
494
495The difference is that the ``readline()`` call in the second handler will call
496``recv()`` multiple times until it encounters a newline character, while the
497single ``recv()`` call in the first handler will just return what has been sent
498from the client in one ``sendall()`` call.
499
500
501This is the client side::
502
503   import socket
504   import sys
505
506   HOST, PORT = "localhost", 9999
507   data = " ".join(sys.argv[1:])
508
509   # Create a socket (SOCK_STREAM means a TCP socket)
510   with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
511       # Connect to server and send data
512       sock.connect((HOST, PORT))
513       sock.sendall(bytes(data + "\n", "utf-8"))
514
515       # Receive data from the server and shut down
516       received = str(sock.recv(1024), "utf-8")
517
518   print("Sent:     {}".format(data))
519   print("Received: {}".format(received))
520
521
522The output of the example should look something like this:
523
524Server:
525
526.. code-block:: shell-session
527
528   $ python TCPServer.py
529   127.0.0.1 wrote:
530   b'hello world with TCP'
531   127.0.0.1 wrote:
532   b'python is nice'
533
534Client:
535
536.. code-block:: shell-session
537
538   $ python TCPClient.py hello world with TCP
539   Sent:     hello world with TCP
540   Received: HELLO WORLD WITH TCP
541   $ python TCPClient.py python is nice
542   Sent:     python is nice
543   Received: PYTHON IS NICE
544
545
546:class:`socketserver.UDPServer` Example
547~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
548
549This is the server side::
550
551   import socketserver
552
553   class MyUDPHandler(socketserver.BaseRequestHandler):
554       """
555       This class works similar to the TCP handler class, except that
556       self.request consists of a pair of data and client socket, and since
557       there is no connection the client address must be given explicitly
558       when sending data back via sendto().
559       """
560
561       def handle(self):
562           data = self.request[0].strip()
563           socket = self.request[1]
564           print("{} wrote:".format(self.client_address[0]))
565           print(data)
566           socket.sendto(data.upper(), self.client_address)
567
568   if __name__ == "__main__":
569       HOST, PORT = "localhost", 9999
570       with socketserver.UDPServer((HOST, PORT), MyUDPHandler) as server:
571           server.serve_forever()
572
573This is the client side::
574
575   import socket
576   import sys
577
578   HOST, PORT = "localhost", 9999
579   data = " ".join(sys.argv[1:])
580
581   # SOCK_DGRAM is the socket type to use for UDP sockets
582   sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
583
584   # As you can see, there is no connect() call; UDP has no connections.
585   # Instead, data is directly sent to the recipient via sendto().
586   sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
587   received = str(sock.recv(1024), "utf-8")
588
589   print("Sent:     {}".format(data))
590   print("Received: {}".format(received))
591
592The output of the example should look exactly like for the TCP server example.
593
594
595Asynchronous Mixins
596~~~~~~~~~~~~~~~~~~~
597
598To build asynchronous handlers, use the :class:`ThreadingMixIn` and
599:class:`ForkingMixIn` classes.
600
601An example for the :class:`ThreadingMixIn` class::
602
603   import socket
604   import threading
605   import socketserver
606
607   class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):
608
609       def handle(self):
610           data = str(self.request.recv(1024), 'ascii')
611           cur_thread = threading.current_thread()
612           response = bytes("{}: {}".format(cur_thread.name, data), 'ascii')
613           self.request.sendall(response)
614
615   class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
616       pass
617
618   def client(ip, port, message):
619       with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
620           sock.connect((ip, port))
621           sock.sendall(bytes(message, 'ascii'))
622           response = str(sock.recv(1024), 'ascii')
623           print("Received: {}".format(response))
624
625   if __name__ == "__main__":
626       # Port 0 means to select an arbitrary unused port
627       HOST, PORT = "localhost", 0
628
629       server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
630       with server:
631           ip, port = server.server_address
632
633           # Start a thread with the server -- that thread will then start one
634           # more thread for each request
635           server_thread = threading.Thread(target=server.serve_forever)
636           # Exit the server thread when the main thread terminates
637           server_thread.daemon = True
638           server_thread.start()
639           print("Server loop running in thread:", server_thread.name)
640
641           client(ip, port, "Hello World 1")
642           client(ip, port, "Hello World 2")
643           client(ip, port, "Hello World 3")
644
645           server.shutdown()
646
647
648The output of the example should look something like this:
649
650.. code-block:: shell-session
651
652   $ python ThreadedTCPServer.py
653   Server loop running in thread: Thread-1
654   Received: Thread-2: Hello World 1
655   Received: Thread-3: Hello World 2
656   Received: Thread-4: Hello World 3
657
658
659The :class:`ForkingMixIn` class is used in the same way, except that the server
660will spawn a new process for each request.
661Available only on POSIX platforms that support :func:`~os.fork`.
662
663