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