1 

     2 :mod:`SocketServer` --- A framework for network servers

     3 =======================================================

     4 

     5 .. module:: SocketServer

     6    :synopsis: A framework for network servers.

     7 

     8 .. note::

     9 

    10    The :mod:`SocketServer` module has been renamed to `socketserver` in Python

    11    3.0.  The :term:`2to3` tool will automatically adapt imports when converting

    12    your sources to 3.0.

    13 

    14 

    15 The :mod:`SocketServer` module simplifies the task of writing network servers.

    16 

    17 There are four basic server classes: :class:`TCPServer` uses the Internet TCP

    18 protocol, which provides for continuous streams of data between the client and

    19 server.  :class:`UDPServer` uses datagrams, which are discrete packets of

    20 information that may arrive out of order or be lost while in transit.  The more

    21 infrequently used :class:`UnixStreamServer` and :class:`UnixDatagramServer`

    22 classes are similar, but use Unix domain sockets; they're not available on

    23 non-Unix platforms.  For more details on network programming, consult a book

    24 such as

    25 W. Richard Steven's UNIX Network Programming or Ralph Davis's Win32 Network

    26 Programming.

    27 

    28 These four classes process requests :dfn:`synchronously`; each request must be

    29 completed before the next request can be started.  This isn't suitable if each

    30 request takes a long time to complete, because it requires a lot of computation,

    31 or because it returns a lot of data which the client is slow to process.  The

    32 solution is to create a separate process or thread to handle each request; the

    33 :class:`ForkingMixIn` and :class:`ThreadingMixIn` mix-in classes can be used to

    34 support asynchronous behaviour.

    35 

    36 Creating a server requires several steps.  First, you must create a request

    37 handler class by subclassing the :class:`BaseRequestHandler` class and

    38 overriding its :meth:`handle` method; this method will process incoming

    39 requests.  Second, you must instantiate one of the server classes, passing it

    40 the server's address and the request handler class.  Finally, call the

    41 :meth:`handle_request` or :meth:`serve_forever` method of the server object to

    42 process one or many requests.

    43 

    44 When inheriting from :class:`ThreadingMixIn` for threaded connection behavior,

    45 you should explicitly declare how you want your threads to behave on an abrupt

    46 shutdown. The :class:`ThreadingMixIn` class defines an attribute

    47 *daemon_threads*, which indicates whether or not the server should wait for

    48 thread termination. You should set the flag explicitly if you would like threads

    49 to behave autonomously; the default is :const:`False`, meaning that Python will

    50 not exit until all threads created by :class:`ThreadingMixIn` have exited.

    51 

    52 Server classes have the same external methods and attributes, no matter what

    53 network protocol they use.

    54 

    55 

    56 Server Creation Notes

    57 ---------------------

    58 

    59 There are five classes in an inheritance diagram, four of which represent

    60 synchronous servers of four types::

    61 

    62    +------------+

    63    | BaseServer |

    64    +------------+

    65          |

    66          v

    67    +-----------+        +------------------+

    68    | TCPServer |------->| UnixStreamServer |

    69    +-----------+        +------------------+

    70          |

    71          v

    72    +-----------+        +--------------------+

    73    | UDPServer |------->| UnixDatagramServer |

    74    +-----------+        +--------------------+

    75 

    76 Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from

    77 :class:`UnixStreamServer` --- the only difference between an IP and a Unix

    78 stream server is the address family, which is simply repeated in both Unix

    79 server classes.

    80 

    81 Forking and threading versions of each type of server can be created using the

    82 :class:`ForkingMixIn` and :class:`ThreadingMixIn` mix-in classes.  For instance,

    83 a threading UDP server class is created as follows::

    84 

    85    class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass

    86 

    87 The mix-in class must come first, since it overrides a method defined in

    88 :class:`UDPServer`.  Setting the various member variables also changes the

    89 behavior of the underlying server mechanism.

    90 

    91 To implement a service, you must derive a class from :class:`BaseRequestHandler`

    92 and redefine its :meth:`handle` method.  You can then run various versions of

    93 the service by combining one of the server classes with your request handler

    94 class.  The request handler class must be different for datagram or stream

    95 services.  This can be hidden by using the handler subclasses

    96 :class:`StreamRequestHandler` or :class:`DatagramRequestHandler`.

    97 

    98 Of course, you still have to use your head!  For instance, it makes no sense to

    99 use a forking server if the service contains state in memory that can be

   100 modified by different requests, since the modifications in the child process

   101 would never reach the initial state kept in the parent process and passed to

   102 each child.  In this case, you can use a threading server, but you will probably

   103 have to use locks to protect the integrity of the shared data.

   104 

   105 On the other hand, if you are building an HTTP server where all data is stored

   106 externally (for instance, in the file system), a synchronous class will

   107 essentially render the service "deaf" while one request is being handled --

   108 which may be for a very long time if a client is slow to receive all the data it

   109 has requested.  Here a threading or forking server is appropriate.

   110 

   111 In some cases, it may be appropriate to process part of a request synchronously,

   112 but to finish processing in a forked child depending on the request data.  This

   113 can be implemented by using a synchronous server and doing an explicit fork in

   114 the request handler class :meth:`handle` method.

   115 

   116 Another approach to handling multiple simultaneous requests in an environment

   117 that supports neither threads nor :func:`fork` (or where these are too expensive

   118 or inappropriate for the service) is to maintain an explicit table of partially

   119 finished requests and to use :func:`select` to decide which request to work on

   120 next (or whether to handle a new incoming request).  This is particularly

   121 important for stream services where each client can potentially be connected for

   122 a long time (if threads or subprocesses cannot be used). See :mod:`asyncore` for

   123 another way to manage this.

   124 

   125 .. XXX should data and methods be intermingled, or separate?

   126    how should the distinction between class and instance variables be drawn?

   127 

   128 

   129 Server Objects

   130 --------------

   131 

   132 

   133 .. function:: fileno()

   134 

   135    Return an integer file descriptor for the socket on which the server is

   136    listening.  This function is most commonly passed to :func:`select.select`, to

   137    allow monitoring multiple servers in the same process.

   138 

   139 

   140 .. function:: handle_request()

   141 

   142    Process a single request.  This function calls the following methods in

   143    order: :meth:`get_request`, :meth:`verify_request`, and

   144    :meth:`process_request`.  If the user-provided :meth:`handle` method of the

   145    handler class raises an exception, the server's :meth:`handle_error` method

   146    will be called.  If no request is received within :attr:`self.timeout`

   147    seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`

   148    will return.

   149 

   150 

   151 .. function:: serve_forever(poll_interval=0.5)

   152 

   153    Handle requests until an explicit :meth:`shutdown` request.  Polls for

   154    shutdown every *poll_interval* seconds.

   155 

   156 

   157 .. function:: shutdown()

   158 

   159    Tells the :meth:`serve_forever` loop to stop and waits until it does.

   160 

   161    .. versionadded:: 2.6

   162 

   163 

   164 .. data:: address_family

   165 

   166    The family of protocols to which the server's socket belongs.

   167    Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.

   168 

   169 

   170 .. data:: RequestHandlerClass

   171 

   172    The user-provided request handler class; an instance of this class is created

   173    for each request.

   174 

   175 

   176 .. data:: server_address

   177 

   178    The address on which the server is listening.  The format of addresses varies

   179    depending on the protocol family; see the documentation for the socket module

   180    for details.  For Internet protocols, this is a tuple containing a string giving

   181    the address, and an integer port number: ``('127.0.0.1', 80)``, for example.

   182 

   183 

   184 .. data:: socket

   185 

   186    The socket object on which the server will listen for incoming requests.

   187 

   188 The server classes support the following class variables:

   189 

   190 .. XXX should class variables be covered before instance variables, or vice versa?

   191 

   192 

   193 .. data:: allow_reuse_address

   194 

   195    Whether the server will allow the reuse of an address. This defaults to

   196    :const:`False`, and can be set in subclasses to change the policy.

   197 

   198 

   199 .. data:: request_queue_size

   200 

   201    The size of the request queue.  If it takes a long time to process a single

   202    request, any requests that arrive while the server is busy are placed into a

   203    queue, up to :attr:`request_queue_size` requests.  Once the queue is full,

   204    further requests from clients will get a "Connection denied" error.  The default

   205    value is usually 5, but this can be overridden by subclasses.

   206 

   207 

   208 .. data:: socket_type

   209 

   210    The type of socket used by the server; :const:`socket.SOCK_STREAM` and

   211    :const:`socket.SOCK_DGRAM` are two common values.

   212 

   213 .. data:: timeout

   214 

   215    Timeout duration, measured in seconds, or :const:`None` if no timeout is

   216    desired.  If :meth:`handle_request` receives no incoming requests within the

   217    timeout period, the :meth:`handle_timeout` method is called.

   218 

   219 There are various server methods that can be overridden by subclasses of base

   220 server classes like :class:`TCPServer`; these methods aren't useful to external

   221 users of the server object.

   222 

   223 .. XXX should the default implementations of these be documented, or should

   224    it be assumed that the user will look at SocketServer.py?

   225 

   226 

   227 .. function:: finish_request()

   228 

   229    Actually processes the request by instantiating :attr:`RequestHandlerClass` and

   230    calling its :meth:`handle` method.

   231 

   232 

   233 .. function:: get_request()

   234 

   235    Must accept a request from the socket, and return a 2-tuple containing the *new*

   236    socket object to be used to communicate with the client, and the client's

   237    address.

   238 

   239 

   240 .. function:: handle_error(request, client_address)

   241 

   242    This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`

   243    method raises an exception.  The default action is to print the traceback to

   244    standard output and continue handling further requests.

   245 

   246 .. function:: handle_timeout()

   247 

   248    This function is called when the :attr:`timeout` attribute has been set to a

   249    value other than :const:`None` and the timeout period has passed with no

   250    requests being received.  The default action for forking servers is

   251    to collect the status of any child processes that have exited, while

   252    in threading servers this method does nothing.

   253 

   254 .. function:: process_request(request, client_address)

   255 

   256    Calls :meth:`finish_request` to create an instance of the

   257    :attr:`RequestHandlerClass`.  If desired, this function can create a new process

   258    or thread to handle the request; the :class:`ForkingMixIn` and

   259    :class:`ThreadingMixIn` classes do this.

   260 

   261 .. Is there any point in documenting the following two functions?

   262    What would the purpose of overriding them be: initializing server

   263    instance variables, adding new network families?

   264 

   265 

   266 .. function:: server_activate()

   267 

   268    Called by the server's constructor to activate the server.  The default behavior

   269    just :meth:`listen`\ s to the server's socket. May be overridden.

   270 

   271 

   272 .. function:: server_bind()

   273 

   274    Called by the server's constructor to bind the socket to the desired address.

   275    May be overridden.

   276 

   277 

   278 .. function:: verify_request(request, client_address)

   279 

   280    Must return a Boolean value; if the value is :const:`True`, the request will be

   281    processed, and if it's :const:`False`, the request will be denied. This function

   282    can be overridden to implement access controls for a server. The default

   283    implementation always returns :const:`True`.

   284 

   285 

   286 RequestHandler Objects

   287 ----------------------

   288 

   289 The request handler class must define a new :meth:`handle` method, and can

   290 override any of the following methods.  A new instance is created for each

   291 request.

   292 

   293 

   294 .. function:: finish()

   295 

   296    Called after the :meth:`handle` method to perform any clean-up actions

   297    required.  The default implementation does nothing.  If :meth:`setup` or

   298    :meth:`handle` raise an exception, this function will not be called.

   299 

   300 

   301 .. function:: handle()

   302 

   303    This function must do all the work required to service a request.  The

   304    default implementation does nothing.  Several instance attributes are

   305    available to it; the request is available as :attr:`self.request`; the client

   306    address as :attr:`self.client_address`; and the server instance as

   307    :attr:`self.server`, in case it needs access to per-server information.

   308 

   309    The type of :attr:`self.request` is different for datagram or stream

   310    services.  For stream services, :attr:`self.request` is a socket object; for

   311    datagram services, :attr:`self.request` is a pair of string and socket.

   312    However, this can be hidden by using the request handler subclasses

   313    :class:`StreamRequestHandler` or :class:`DatagramRequestHandler`, which

   314    override the :meth:`setup` and :meth:`finish` methods, and provide

   315    :attr:`self.rfile` and :attr:`self.wfile` attributes.  :attr:`self.rfile` and

   316    :attr:`self.wfile` can be read or written, respectively, to get the request

   317    data or return data to the client.

   318 

   319 

   320 .. function:: setup()

   321 

   322    Called before the :meth:`handle` method to perform any initialization actions

   323    required.  The default implementation does nothing.

   324 

   325 

   326 Examples

   327 --------

   328 

   329 :class:`SocketServer.TCPServer` Example

   330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   331 

   332 This is the server side::

   333 

   334    import SocketServer

   335 

   336    class MyTCPHandler(SocketServer.BaseRequestHandler):

   337        """

   338        The RequestHandler class for our server.

   339 

   340        It is instantiated once per connection to the server, and must

   341        override the handle() method to implement communication to the

   342        client.

   343        """

   344 

   345        def handle(self):

   346            # self.request is the TCP socket connected to the client

   347            self.data = self.request.recv(1024).strip()

   348            print "%s wrote:" % self.client_address[0]

   349            print self.data

   350            # just send back the same data, but upper-cased

   351            self.request.send(self.data.upper())

   352 

   353    if __name__ == "__main__":

   354        HOST, PORT = "localhost", 9999

   355 

   356        # Create the server, binding to localhost on port 9999

   357        server = SocketServer.TCPServer((HOST, PORT), MyTCPHandler)

   358 

   359        # Activate the server; this will keep running until you

   360        # interrupt the program with Ctrl-C

   361        server.serve_forever()

   362 

   363 An alternative request handler class that makes use of streams (file-like

   364 objects that simplify communication by providing the standard file interface)::

   365 

   366    class MyTCPHandler(SocketServer.StreamRequestHandler):

   367 

   368        def handle(self):

   369            # self.rfile is a file-like object created by the handler;

   370            # we can now use e.g. readline() instead of raw recv() calls

   371            self.data = self.rfile.readline().strip()

   372            print "%s wrote:" % self.client_address[0]

   373            print self.data

   374            # Likewise, self.wfile is a file-like object used to write back

   375            # to the client

   376            self.wfile.write(self.data.upper())

   377 

   378 The difference is that the ``readline()`` call in the second handler will call

   379 ``recv()`` multiple times until it encounters a newline character, while the

   380 single ``recv()`` call in the first handler will just return what has been sent

   381 from the client in one ``send()`` call.

   382 

   383 

   384 This is the client side::

   385 

   386    import socket

   387    import sys

   388 

   389    HOST, PORT = "localhost", 9999

   390    data = " ".join(sys.argv[1:])

   391 

   392    # Create a socket (SOCK_STREAM means a TCP socket)

   393    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

   394 

   395    # Connect to server and send data

   396    sock.connect((HOST, PORT))

   397    sock.send(data + "\n")

   398 

   399    # Receive data from the server and shut down

   400    received = sock.recv(1024)

   401    sock.close()

   402 

   403    print "Sent:     %s" % data

   404    print "Received: %s" % received

   405 

   406 

   407 The output of the example should look something like this:

   408 

   409 Server::

   410 

   411    $ python TCPServer.py

   412    127.0.0.1 wrote:

   413    hello world with TCP

   414    127.0.0.1 wrote:

   415    python is nice

   416 

   417 Client::

   418 

   419    $ python TCPClient.py hello world with TCP

   420    Sent:     hello world with TCP

   421    Received: HELLO WORLD WITH TCP

   422    $ python TCPClient.py python is nice

   423    Sent:     python is nice

   424    Received: PYTHON IS NICE

   425 

   426 

   427 :class:`SocketServer.UDPServer` Example

   428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   429 

   430 This is the server side::

   431 

   432    import SocketServer

   433 

   434    class MyUDPHandler(SocketServer.BaseRequestHandler):

   435        """

   436        This class works similar to the TCP handler class, except that

   437        self.request consists of a pair of data and client socket, and since

   438        there is no connection the client address must be given explicitly

   439        when sending data back via sendto().

   440        """

   441 

   442        def handle(self):

   443            data = self.request[0].strip()

   444            socket = self.request[1]

   445            print "%s wrote:" % self.client_address[0]

   446            print data

   447            socket.sendto(data.upper(), self.client_address)

   448 

   449    if __name__ == "__main__":

   450       HOST, PORT = "localhost", 9999

   451       server = SocketServer.UDPServer((HOST, PORT), BaseUDPRequestHandler)

   452       server.serve_forever()

   453 

   454 This is the client side::

   455 

   456    import socket

   457    import sys

   458 

   459    HOST, PORT = "localhost"

   460    data = " ".join(sys.argv[1:])

   461 

   462    # SOCK_DGRAM is the socket type to use for UDP sockets

   463    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

   464 

   465    # As you can see, there is no connect() call; UDP has no connections.

   466    # Instead, data is directly sent to the recipient via sendto().

   467    sock.sendto(data + "\n", (HOST, PORT))

   468    received = sock.recv(1024)

   469 

   470    print "Sent:     %s" % data

   471    print "Received: %s" % received

   472 

   473 The output of the example should look exactly like for the TCP server example.

   474 

   475 

   476 Asynchronous Mixins

   477 ~~~~~~~~~~~~~~~~~~~

   478 

   479 To build asynchronous handlers, use the :class:`ThreadingMixIn` and

   480 :class:`ForkingMixIn` classes.

   481 

   482 An example for the :class:`ThreadingMixIn` class::

   483 

   484    import socket

   485    import threading

   486    import SocketServer

   487 

   488    class ThreadedTCPRequestHandler(SocketServer.BaseRequestHandler):

   489 

   490        def handle(self):

   491            data = self.request.recv(1024)

   492            cur_thread = threading.currentThread()

   493            response = "%s: %s" % (cur_thread.getName(), data)

   494            self.request.send(response)

   495 

   496    class ThreadedTCPServer(SocketServer.ThreadingMixIn, SocketServer.TCPServer):

   497        pass

   498 

   499    def client(ip, port, message):

   500        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

   501        sock.connect((ip, port))

   502        sock.send(message)

   503        response = sock.recv(1024)

   504        print "Received: %s" % response

   505        sock.close()

   506 

   507    if __name__ == "__main__":

   508        # Port 0 means to select an arbitrary unused port

   509        HOST, PORT = "localhost", 0

   510 

   511        server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)

   512        ip, port = server.server_address

   513 

   514        # Start a thread with the server -- that thread will then start one

   515        # more thread for each request

   516        server_thread = threading.Thread(target=server.serve_forever)

   517        # Exit the server thread when the main thread terminates

   518        server_thread.setDaemon(True)

   519        server_thread.start()

   520        print "Server loop running in thread:", t.getName()

   521 

   522        client(ip, port, "Hello World 1")

   523        client(ip, port, "Hello World 2")

   524        client(ip, port, "Hello World 3")

   525 

   526        server.shutdown()

   527 

   528 The output of the example should look something like this::

   529 

   530    $ python ThreadedTCPServer.py

   531    Server loop running in thread: Thread-1

   532    Received: Thread-2: Hello World 1

   533    Received: Thread-3: Hello World 2

   534    Received: Thread-4: Hello World 3

   535 

   536 

   537 The :class:`ForkingMixIn` class is used in the same way, except that the server

   538 will spawn a new process for each request.