Debian Codegraph @

Doc/library/socketserver.rst

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