mirror of https://github.com/python/cpython
Issue #15608: Merge socketserver doc from 3.5
This commit is contained in:
Martin Panter
commit
be1aec752d
|
|
@ -10,16 +10,34 @@
|
|||
|
||||
The :mod:`socketserver` module simplifies the task of writing network servers.
|
||||
|
||||
There are four basic server classes: :class:`TCPServer` uses the Internet TCP
|
||||
protocol, which provides for continuous streams of data between the client and
|
||||
server. :class:`UDPServer` uses datagrams, which are discrete packets of
|
||||
information that may arrive out of order or be lost while in transit. The more
|
||||
infrequently used :class:`UnixStreamServer` and :class:`UnixDatagramServer`
|
||||
classes are similar, but use Unix domain sockets; they're not available on
|
||||
non-Unix platforms. For more details on network programming, consult a book
|
||||
such as
|
||||
W. Richard Steven's UNIX Network Programming or Ralph Davis's Win32 Network
|
||||
Programming.
|
||||
There are four basic concrete server classes:
|
||||
|
||||
|
||||
.. class:: TCPServer(server_address, RequestHandlerClass, bind_and_activate=True)
|
||||
|
||||
This uses the Internet TCP protocol, which provides for
|
||||
continuous streams of data between the client and server.
|
||||
If *bind_and_activate* is true, the constructor automatically attempts to
|
||||
invoke :meth:`~BaseServer.server_bind` and
|
||||
:meth:`~BaseServer.server_activate`. The other parameters are passed to
|
||||
the :class:`BaseServer` base class.
|
||||
|
||||
|
||||
.. class:: UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)
|
||||
|
||||
This uses datagrams, which are discrete packets of information that may
|
||||
arrive out of order or be lost while in transit. The parameters are
|
||||
the same as for :class:`TCPServer`.
|
||||
|
||||
|
||||
.. class:: UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)
|
||||
UnixDatagramServer(server_address, RequestHandlerClass, bind_and_activate=True)
|
||||
|
||||
These more infrequently used classes are similar to the TCP and
|
||||
UDP classes, but use Unix domain sockets; they're not available on
|
||||
non-Unix platforms. The parameters are the same as for
|
||||
:class:`TCPServer`.
|
||||
|
||||
|
||||
These four classes process requests :dfn:`synchronously`; each request must be
|
||||
completed before the next request can be started. This isn't suitable if each
|
||||
|
|
@ -31,10 +49,12 @@ support asynchronous behaviour.
|
|||
|
||||
Creating a server requires several steps. First, you must create a request
|
||||
handler class by subclassing the :class:`BaseRequestHandler` class and
|
||||
overriding its :meth:`handle` method; this method will process incoming
|
||||
overriding its :meth:`~BaseRequestHandler.handle` method;
|
||||
this method will process incoming
|
||||
requests. Second, you must instantiate one of the server classes, passing it
|
||||
the server's address and the request handler class. Then call the
|
||||
:meth:`handle_request` or :meth:`serve_forever` method of the server object to
|
||||
:meth:`~BaseServer.handle_request` or
|
||||
:meth:`~BaseServer.serve_forever` method of the server object to
|
||||
process one or many requests. Finally, call :meth:`~BaseServer.server_close`
|
||||
to close the socket.
|
||||
|
||||
|
|
@ -76,18 +96,33 @@ Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from
|
|||
stream server is the address family, which is simply repeated in both Unix
|
||||
server classes.
|
||||
|
||||
Forking and threading versions of each type of server can be created using the
|
||||
:class:`ForkingMixIn` and :class:`ThreadingMixIn` mix-in classes. For instance,
|
||||
a threading UDP server class is created as follows::
|
||||
|
||||
class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
|
||||
.. class:: ForkingMixIn
|
||||
ThreadingMixIn
|
||||
|
||||
Forking and threading versions of each type of server can be created
|
||||
using these mix-in classes. For instance, :class:`ThreadingUDPServer`
|
||||
is created as follows::
|
||||
|
||||
class ThreadingUDPServer(ThreadingMixIn, UDPServer):
|
||||
pass
|
||||
|
||||
The mix-in class comes first, since it overrides a method defined in
|
||||
:class:`UDPServer`. Setting the various attributes also changes the
|
||||
behavior of the underlying server mechanism.
|
||||
|
||||
|
||||
.. class:: ForkingTCPServer
|
||||
ForkingUDPServer
|
||||
ThreadingTCPServer
|
||||
ThreadingUDPServer
|
||||
|
||||
These classes are pre-defined using the mix-in classes.
|
||||
|
||||
The mix-in class must come first, since it overrides a method defined in
|
||||
:class:`UDPServer`. Setting the various attributes also change the
|
||||
behavior of the underlying server mechanism.
|
||||
|
||||
To implement a service, you must derive a class from :class:`BaseRequestHandler`
|
||||
and redefine its :meth:`handle` method. You can then run various versions of
|
||||
and redefine its :meth:`~BaseRequestHandler.handle` method.
|
||||
You can then run various versions of
|
||||
the service by combining one of the server classes with your request handler
|
||||
class. The request handler class must be different for datagram or stream
|
||||
services. This can be hidden by using the handler subclasses
|
||||
|
|
@ -109,7 +144,7 @@ has requested. Here a threading or forking server is appropriate.
|
|||
In some cases, it may be appropriate to process part of a request synchronously,
|
||||
but to finish processing in a forked child depending on the request data. This
|
||||
can be implemented by using a synchronous server and doing an explicit fork in
|
||||
the request handler class :meth:`handle` method.
|
||||
the request handler class :meth:`~BaseRequestHandler.handle` method.
|
||||
|
||||
Another approach to handling multiple simultaneous requests in an environment
|
||||
that supports neither threads nor :func:`~os.fork` (or where these are too
|
||||
|
|
@ -127,227 +162,240 @@ connected for a long time (if threads or subprocesses cannot be used). See
|
|||
Server Objects
|
||||
--------------
|
||||
|
||||
.. class:: BaseServer
|
||||
.. class:: BaseServer(server_address, RequestHandlerClass)
|
||||
|
||||
This is the superclass of all Server objects in the module. It defines the
|
||||
interface, given below, but does not implement most of the methods, which is
|
||||
done in subclasses.
|
||||
done in subclasses. The two parameters are stored in the respective
|
||||
:attr:`server_address` and :attr:`RequestHandlerClass` attributes.
|
||||
|
||||
|
||||
.. method:: BaseServer.fileno()
|
||||
.. method:: fileno()
|
||||
|
||||
Return an integer file descriptor for the socket on which the server is
|
||||
listening. This function is most commonly passed to :mod:`selectors`, to
|
||||
allow monitoring multiple servers in the same process.
|
||||
Return an integer file descriptor for the socket on which the server is
|
||||
listening. This function is most commonly passed to :mod:`selectors`, to
|
||||
allow monitoring multiple servers in the same process.
|
||||
|
||||
|
||||
.. method:: BaseServer.handle_request()
|
||||
.. method:: handle_request()
|
||||
|
||||
Process a single request. This function calls the following methods in
|
||||
order: :meth:`get_request`, :meth:`verify_request`, and
|
||||
:meth:`process_request`. If the user-provided :meth:`handle` method of the
|
||||
handler class raises an exception, the server's :meth:`handle_error` method
|
||||
will be called. If no request is received within :attr:`self.timeout`
|
||||
seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`
|
||||
will return.
|
||||
Process a single request. This function calls the following methods in
|
||||
order: :meth:`get_request`, :meth:`verify_request`, and
|
||||
:meth:`process_request`. If the user-provided
|
||||
:meth:`~BaseRequestHandler.handle` method of the
|
||||
handler class raises an exception, the server's :meth:`handle_error` method
|
||||
will be called. If no request is received within :attr:`timeout`
|
||||
seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`
|
||||
will return.
|
||||
|
||||
|
||||
.. method:: BaseServer.serve_forever(poll_interval=0.5)
|
||||
.. method:: serve_forever(poll_interval=0.5)
|
||||
|
||||
Handle requests until an explicit :meth:`shutdown` request. Poll for
|
||||
shutdown every *poll_interval* seconds. Ignores :attr:`self.timeout`. It
|
||||
also calls :meth:`service_actions`, which may be used by a subclass or mixin
|
||||
to provide actions specific to a given service. For example, the
|
||||
:class:`ForkingMixIn` class uses :meth:`service_actions` to clean up zombie
|
||||
child processes.
|
||||
Handle requests until an explicit :meth:`shutdown` request. Poll for
|
||||
shutdown every *poll_interval* seconds.
|
||||
Ignores the :attr:`timeout` attribute. It
|
||||
also calls :meth:`service_actions`, which may be used by a subclass or mixin
|
||||
to provide actions specific to a given service. For example, the
|
||||
:class:`ForkingMixIn` class uses :meth:`service_actions` to clean up zombie
|
||||
child processes.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Added ``service_actions`` call to the ``serve_forever`` method.
|
||||
.. versionchanged:: 3.3
|
||||
Added ``service_actions`` call to the ``serve_forever`` method.
|
||||
|
||||
|
||||
.. method:: BaseServer.service_actions()
|
||||
.. method:: service_actions()
|
||||
|
||||
This is called in the :meth:`serve_forever` loop. This method can be
|
||||
overridden by subclasses or mixin classes to perform actions specific to
|
||||
a given service, such as cleanup actions.
|
||||
This is called in the :meth:`serve_forever` loop. This method can be
|
||||
overridden by subclasses or mixin classes to perform actions specific to
|
||||
a given service, such as cleanup actions.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. method:: BaseServer.shutdown()
|
||||
.. method:: shutdown()
|
||||
|
||||
Tell the :meth:`serve_forever` loop to stop and wait until it does.
|
||||
Tell the :meth:`serve_forever` loop to stop and wait until it does.
|
||||
|
||||
|
||||
.. method:: BaseServer.server_close()
|
||||
.. method:: server_close()
|
||||
|
||||
Clean up the server. May be overridden.
|
||||
Clean up the server. May be overridden.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
.. attribute:: address_family
|
||||
|
||||
.. attribute:: BaseServer.address_family
|
||||
The family of protocols to which the server's socket belongs.
|
||||
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
|
||||
|
||||
The family of protocols to which the server's socket belongs.
|
||||
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
|
||||
|
||||
.. attribute:: RequestHandlerClass
|
||||
|
||||
.. attribute:: BaseServer.RequestHandlerClass
|
||||
The user-provided request handler class; an instance of this class is created
|
||||
for each request.
|
||||
|
||||
The user-provided request handler class; an instance of this class is created
|
||||
for each request.
|
||||
|
||||
.. attribute:: server_address
|
||||
|
||||
.. attribute:: BaseServer.server_address
|
||||
The address on which the server is listening. The format of addresses varies
|
||||
depending on the protocol family;
|
||||
see the documentation for the :mod:`socket` module
|
||||
for details. For Internet protocols, this is a tuple containing a string giving
|
||||
the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
|
||||
|
||||
The address on which the server is listening. The format of addresses varies
|
||||
depending on the protocol family; see the documentation for the socket module
|
||||
for details. For Internet protocols, this is a tuple containing a string giving
|
||||
the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
|
||||
|
||||
.. attribute:: socket
|
||||
|
||||
.. attribute:: BaseServer.socket
|
||||
The socket object on which the server will listen for incoming requests.
|
||||
|
||||
The socket object on which the server will listen for incoming requests.
|
||||
|
||||
The server classes support the following class variables:
|
||||
|
||||
The server classes support the following class variables:
|
||||
.. XXX should class variables be covered before instance variables, or vice versa?
|
||||
|
||||
.. XXX should class variables be covered before instance variables, or vice versa?
|
||||
.. attribute:: allow_reuse_address
|
||||
|
||||
.. attribute:: BaseServer.allow_reuse_address
|
||||
Whether the server will allow the reuse of an address. This defaults to
|
||||
:const:`False`, and can be set in subclasses to change the policy.
|
||||
|
||||
Whether the server will allow the reuse of an address. This defaults to
|
||||
:const:`False`, and can be set in subclasses to change the policy.
|
||||
|
||||
.. attribute:: request_queue_size
|
||||
|
||||
.. attribute:: BaseServer.request_queue_size
|
||||
The size of the request queue. If it takes a long time to process a single
|
||||
request, any requests that arrive while the server is busy are placed into a
|
||||
queue, up to :attr:`request_queue_size` requests. Once the queue is full,
|
||||
further requests from clients will get a "Connection denied" error. The default
|
||||
value is usually 5, but this can be overridden by subclasses.
|
||||
|
||||
The size of the request queue. If it takes a long time to process a single
|
||||
request, any requests that arrive while the server is busy are placed into a
|
||||
queue, up to :attr:`request_queue_size` requests. Once the queue is full,
|
||||
further requests from clients will get a "Connection denied" error. The default
|
||||
value is usually 5, but this can be overridden by subclasses.
|
||||
|
||||
.. attribute:: socket_type
|
||||
|
||||
.. attribute:: BaseServer.socket_type
|
||||
The type of socket used by the server; :const:`socket.SOCK_STREAM` and
|
||||
:const:`socket.SOCK_DGRAM` are two common values.
|
||||
|
||||
The type of socket used by the server; :const:`socket.SOCK_STREAM` and
|
||||
:const:`socket.SOCK_DGRAM` are two common values.
|
||||
|
||||
.. attribute:: timeout
|
||||
|
||||
.. attribute:: BaseServer.timeout
|
||||
Timeout duration, measured in seconds, or :const:`None` if no timeout is
|
||||
desired. If :meth:`handle_request` receives no incoming requests within the
|
||||
timeout period, the :meth:`handle_timeout` method is called.
|
||||
|
||||
Timeout duration, measured in seconds, or :const:`None` if no timeout is
|
||||
desired. If :meth:`handle_request` receives no incoming requests within the
|
||||
timeout period, the :meth:`handle_timeout` method is called.
|
||||
|
||||
There are various server methods that can be overridden by subclasses of base
|
||||
server classes like :class:`TCPServer`; these methods aren't useful to external
|
||||
users of the server object.
|
||||
|
||||
There are various server methods that can be overridden by subclasses of base
|
||||
server classes like :class:`TCPServer`; these methods aren't useful to external
|
||||
users of the server object.
|
||||
.. XXX should the default implementations of these be documented, or should
|
||||
it be assumed that the user will look at socketserver.py?
|
||||
|
||||
.. XXX should the default implementations of these be documented, or should
|
||||
it be assumed that the user will look at socketserver.py?
|
||||
.. method:: finish_request()
|
||||
|
||||
.. method:: BaseServer.finish_request()
|
||||
Actually processes the request by instantiating :attr:`RequestHandlerClass` and
|
||||
calling its :meth:`~BaseRequestHandler.handle` method.
|
||||
|
||||
Actually processes the request by instantiating :attr:`RequestHandlerClass` and
|
||||
calling its :meth:`handle` method.
|
||||
|
||||
.. method:: get_request()
|
||||
|
||||
.. method:: BaseServer.get_request()
|
||||
Must accept a request from the socket, and return a 2-tuple containing the *new*
|
||||
socket object to be used to communicate with the client, and the client's
|
||||
address.
|
||||
|
||||
Must accept a request from the socket, and return a 2-tuple containing the *new*
|
||||
socket object to be used to communicate with the client, and the client's
|
||||
address.
|
||||
|
||||
.. method:: handle_error(request, client_address)
|
||||
|
||||
.. method:: BaseServer.handle_error(request, client_address)
|
||||
This function is called if the :meth:`~BaseRequestHandler.handle`
|
||||
method of a :attr:`RequestHandlerClass` instance raises
|
||||
an exception. The default action is to print the traceback to
|
||||
standard output and continue handling further requests.
|
||||
|
||||
This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`
|
||||
method raises an exception. The default action is to print the traceback to
|
||||
standard output and continue handling further requests.
|
||||
|
||||
.. method:: handle_timeout()
|
||||
|
||||
.. method:: BaseServer.handle_timeout()
|
||||
This function is called when the :attr:`timeout` attribute has been set to a
|
||||
value other than :const:`None` and the timeout period has passed with no
|
||||
requests being received. The default action for forking servers is
|
||||
to collect the status of any child processes that have exited, while
|
||||
in threading servers this method does nothing.
|
||||
|
||||
This function is called when the :attr:`timeout` attribute has been set to a
|
||||
value other than :const:`None` and the timeout period has passed with no
|
||||
requests being received. The default action for forking servers is
|
||||
to collect the status of any child processes that have exited, while
|
||||
in threading servers this method does nothing.
|
||||
|
||||
.. method:: process_request(request, client_address)
|
||||
|
||||
.. method:: BaseServer.process_request(request, client_address)
|
||||
Calls :meth:`finish_request` to create an instance of the
|
||||
:attr:`RequestHandlerClass`. If desired, this function can create a new process
|
||||
or thread to handle the request; the :class:`ForkingMixIn` and
|
||||
:class:`ThreadingMixIn` classes do this.
|
||||
|
||||
Calls :meth:`finish_request` to create an instance of the
|
||||
:attr:`RequestHandlerClass`. If desired, this function can create a new process
|
||||
or thread to handle the request; the :class:`ForkingMixIn` and
|
||||
:class:`ThreadingMixIn` classes do this.
|
||||
|
||||
.. Is there any point in documenting the following two functions?
|
||||
What would the purpose of overriding them be: initializing server
|
||||
instance variables, adding new network families?
|
||||
|
||||
.. Is there any point in documenting the following two functions?
|
||||
What would the purpose of overriding them be: initializing server
|
||||
instance variables, adding new network families?
|
||||
.. method:: server_activate()
|
||||
|
||||
.. method:: BaseServer.server_activate()
|
||||
Called by the server's constructor to activate the server. The default behavior
|
||||
for a TCP server just invokes :meth:`~socket.socket.listen`
|
||||
on the server's socket. May be overridden.
|
||||
|
||||
Called by the server's constructor to activate the server. The default behavior
|
||||
just :meth:`listen`\ s to the server's socket. May be overridden.
|
||||
|
||||
.. method:: server_bind()
|
||||
|
||||
.. method:: BaseServer.server_bind()
|
||||
Called by the server's constructor to bind the socket to the desired address.
|
||||
May be overridden.
|
||||
|
||||
Called by the server's constructor to bind the socket to the desired address.
|
||||
May be overridden.
|
||||
|
||||
.. method:: verify_request(request, client_address)
|
||||
|
||||
.. method:: BaseServer.verify_request(request, client_address)
|
||||
Must return a Boolean value; if the value is :const:`True`, the request will
|
||||
be processed, and if it's :const:`False`, the request will be denied. This
|
||||
function can be overridden to implement access controls for a server. The
|
||||
default implementation always returns :const:`True`.
|
||||
|
||||
Must return a Boolean value; if the value is :const:`True`, the request will
|
||||
be processed, and if it's :const:`False`, the request will be denied. This
|
||||
function can be overridden to implement access controls for a server. The
|
||||
default implementation always returns :const:`True`.
|
||||
|
||||
Request Handler Objects
|
||||
-----------------------
|
||||
|
||||
RequestHandler Objects
|
||||
----------------------
|
||||
.. class:: BaseRequestHandler
|
||||
|
||||
The request handler class must define a new :meth:`handle` method, and can
|
||||
override any of the following methods. A new instance is created for each
|
||||
request.
|
||||
This is the superclass of all request handler objects. It defines
|
||||
the interface, given below. A concrete request handler subclass must
|
||||
define a new :meth:`handle` method, and can override any of
|
||||
the other methods. A new instance of the subclass is created for each
|
||||
request.
|
||||
|
||||
|
||||
.. method:: RequestHandler.finish()
|
||||
.. method:: setup()
|
||||
|
||||
Called after the :meth:`handle` method to perform any clean-up actions
|
||||
required. The default implementation does nothing. If :meth:`setup`
|
||||
raises an exception, this function will not be called.
|
||||
Called before the :meth:`handle` method to perform any initialization actions
|
||||
required. The default implementation does nothing.
|
||||
|
||||
|
||||
.. method:: RequestHandler.handle()
|
||||
.. method:: handle()
|
||||
|
||||
This function must do all the work required to service a request. The
|
||||
default implementation does nothing. Several instance attributes are
|
||||
available to it; the request is available as :attr:`self.request`; the client
|
||||
address as :attr:`self.client_address`; and the server instance as
|
||||
:attr:`self.server`, in case it needs access to per-server information.
|
||||
This function must do all the work required to service a request. The
|
||||
default implementation does nothing. Several instance attributes are
|
||||
available to it; the request is available as :attr:`self.request`; the client
|
||||
address as :attr:`self.client_address`; and the server instance as
|
||||
:attr:`self.server`, in case it needs access to per-server information.
|
||||
|
||||
The type of :attr:`self.request` is different for datagram or stream
|
||||
services. For stream services, :attr:`self.request` is a socket object; for
|
||||
datagram services, :attr:`self.request` is a pair of string and socket.
|
||||
However, this can be hidden by using the request handler subclasses
|
||||
:class:`StreamRequestHandler` or :class:`DatagramRequestHandler`, which
|
||||
override the :meth:`setup` and :meth:`finish` methods, and provide
|
||||
:attr:`self.rfile` and :attr:`self.wfile` attributes. :attr:`self.rfile` and
|
||||
:attr:`self.wfile` can be read or written, respectively, to get the request
|
||||
data or return data to the client.
|
||||
The type of :attr:`self.request` is different for datagram or stream
|
||||
services. For stream services, :attr:`self.request` is a socket object; for
|
||||
datagram services, :attr:`self.request` is a pair of string and socket.
|
||||
|
||||
|
||||
.. method:: RequestHandler.setup()
|
||||
.. method:: finish()
|
||||
|
||||
Called before the :meth:`handle` method to perform any initialization actions
|
||||
required. The default implementation does nothing.
|
||||
Called after the :meth:`handle` method to perform any clean-up actions
|
||||
required. The default implementation does nothing. If :meth:`setup`
|
||||
raises an exception, this function will not be called.
|
||||
|
||||
|
||||
.. class:: StreamRequestHandler
|
||||
DatagramRequestHandler
|
||||
|
||||
These :class:`BaseRequestHandler` subclasses override the
|
||||
:meth:`~BaseRequestHandler.setup` and :meth:`~BaseRequestHandler.finish`
|
||||
methods, and provide :attr:`self.rfile` and :attr:`self.wfile` attributes.
|
||||
The :attr:`self.rfile` and :attr:`self.wfile` attributes can be
|
||||
read or written, respectively, to get the request data or return data
|
||||
to the client.
|
||||
|
||||
|
||||
Examples
|
||||
|
|
@ -362,7 +410,7 @@ This is the server side::
|
|||
|
||||
class MyTCPHandler(socketserver.BaseRequestHandler):
|
||||
"""
|
||||
The RequestHandler class for our server.
|
||||
The request handler class for our server.
|
||||
|
||||
It is instantiated once per connection to the server, and must
|
||||
override the handle() method to implement communication to the
|
||||
|
|
|
|||
Loading…
Reference in New Issue