| 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 |
|