mirror of https://github.com/python/cpython
GHOP #180 by Michael Schneider: add examples to the socketserver documentation.
This commit is contained in:
parent
a9916b55de
commit
67d6933ab5
|
@ -244,8 +244,8 @@ users of the server object.
|
||||||
|
|
||||||
.. function:: handle_timeout()
|
.. function:: handle_timeout()
|
||||||
|
|
||||||
This function is called when the :attr:`timeout` attribute has been set to a
|
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
|
value other than :const:`None` and the timeout period has passed with no
|
||||||
requests being received. The default action for forking servers is
|
requests being received. The default action for forking servers is
|
||||||
to collect the status of any child processes that have exited, while
|
to collect the status of any child processes that have exited, while
|
||||||
in threading servers this method does nothing.
|
in threading servers this method does nothing.
|
||||||
|
@ -292,27 +292,28 @@ request.
|
||||||
|
|
||||||
.. function:: finish()
|
.. function:: finish()
|
||||||
|
|
||||||
Called after the :meth:`handle` method to perform any clean-up actions required.
|
Called after the :meth:`handle` method to perform any clean-up actions
|
||||||
The default implementation does nothing. If :meth:`setup` or :meth:`handle`
|
required. The default implementation does nothing. If :meth:`setup` or
|
||||||
raise an exception, this function will not be called.
|
:meth:`handle` raise an exception, this function will not be called.
|
||||||
|
|
||||||
|
|
||||||
.. function:: handle()
|
.. function:: handle()
|
||||||
|
|
||||||
This function must do all the work required to service a request. The default
|
This function must do all the work required to service a request. The
|
||||||
implementation does nothing. Several instance attributes are available to it;
|
default implementation does nothing. Several instance attributes are
|
||||||
the request is available as :attr:`self.request`; the client address as
|
available to it; the request is available as :attr:`self.request`; the client
|
||||||
:attr:`self.client_address`; and the server instance as :attr:`self.server`, in
|
address as :attr:`self.client_address`; and the server instance as
|
||||||
case it needs access to per-server information.
|
: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.
|
The type of :attr:`self.request` is different for datagram or stream
|
||||||
For stream services, :attr:`self.request` is a socket object; for datagram
|
services. For stream services, :attr:`self.request` is a socket object; for
|
||||||
services, :attr:`self.request` is a string. However, this can be hidden by using
|
datagram services, :attr:`self.request` is a pair of string and socket.
|
||||||
the request handler subclasses :class:`StreamRequestHandler` or
|
However, this can be hidden by using the request handler subclasses
|
||||||
:class:`DatagramRequestHandler`, which override the :meth:`setup` and
|
:class:`StreamRequestHandler` or :class:`DatagramRequestHandler`, which
|
||||||
:meth:`finish` methods, and provide :attr:`self.rfile` and :attr:`self.wfile`
|
override the :meth:`setup` and :meth:`finish` methods, and provide
|
||||||
attributes. :attr:`self.rfile` and :attr:`self.wfile` can be read or written,
|
:attr:`self.rfile` and :attr:`self.wfile` attributes. :attr:`self.rfile` and
|
||||||
respectively, to get the request data or return data to the client.
|
:attr:`self.wfile` can be read or written, respectively, to get the request
|
||||||
|
data or return data to the client.
|
||||||
|
|
||||||
|
|
||||||
.. function:: setup()
|
.. function:: setup()
|
||||||
|
@ -320,3 +321,217 @@ request.
|
||||||
Called before the :meth:`handle` method to perform any initialization actions
|
Called before the :meth:`handle` method to perform any initialization actions
|
||||||
required. The default implementation does nothing.
|
required. The default implementation does nothing.
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
:class:`socketserver.TCPServer` Example
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is the server side::
|
||||||
|
|
||||||
|
import socketserver
|
||||||
|
|
||||||
|
class MyTCPHandler(socketserver.BaseRequestHandler):
|
||||||
|
"""
|
||||||
|
The RequestHandler class for our server.
|
||||||
|
|
||||||
|
It is instantiated once per connection to the server, and must
|
||||||
|
override the handle() method to implement communication to the
|
||||||
|
client.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def handle(self):
|
||||||
|
# self.request is the TCP socket connected to the client
|
||||||
|
self.data = self.request.recv(1024).strip()
|
||||||
|
print "%s wrote:" % self.client_address[0]
|
||||||
|
print self.data
|
||||||
|
# just send back the same data, but upper-cased
|
||||||
|
self.request.send(self.data.upper())
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
HOST, PORT = "localhost", 9999
|
||||||
|
|
||||||
|
# Create the server, binding to localhost on port 9999
|
||||||
|
server = socketserver.TCPServer((HOST, PORT), MyTCPHandler)
|
||||||
|
|
||||||
|
# Activate the server; this will keep running until you
|
||||||
|
# interrupt the program with Ctrl-C
|
||||||
|
server.serve_forever()
|
||||||
|
|
||||||
|
An alternative request handler class that makes use of streams (file-like
|
||||||
|
objects that simplify communication by providing the standard file interface)::
|
||||||
|
|
||||||
|
class MyTCPHandler(socketserver.StreamRequestHandler):
|
||||||
|
|
||||||
|
def handle(self):
|
||||||
|
# self.rfile is a file-like object created by the handler;
|
||||||
|
# we can now use e.g. readline() instead of raw recv() calls
|
||||||
|
self.data = self.rfile.readline().strip()
|
||||||
|
print "%s wrote:" % self.client_address[0]
|
||||||
|
print self.data
|
||||||
|
# Likewise, self.wfile is a file-like object used to write back
|
||||||
|
# to the client
|
||||||
|
self.wfile.write(self.data.upper())
|
||||||
|
|
||||||
|
The difference is that the ``readline()`` call in the second handler will call
|
||||||
|
``recv()`` multiple times until it encounters a newline character, while the
|
||||||
|
single ``recv()`` call in the first handler will just return what has been sent
|
||||||
|
from the client in one ``send()`` call.
|
||||||
|
|
||||||
|
|
||||||
|
This is the client side::
|
||||||
|
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
|
||||||
|
HOST, PORT = "localhost", 9999
|
||||||
|
data = " ".join(sys.argv[1:])
|
||||||
|
|
||||||
|
# Create a socket (SOCK_STREAM means a TCP socket)
|
||||||
|
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||||
|
|
||||||
|
# Connect to server and send data
|
||||||
|
sock.connect((HOST, PORT))
|
||||||
|
sock.send(data + "\n")
|
||||||
|
|
||||||
|
# Receive data from the server and shut down
|
||||||
|
received = sock.recv(1024)
|
||||||
|
sock.close()
|
||||||
|
|
||||||
|
print "Sent: %s" % data
|
||||||
|
print "Received: %s" % received
|
||||||
|
|
||||||
|
|
||||||
|
The output of the example should look something like this:
|
||||||
|
|
||||||
|
Server::
|
||||||
|
|
||||||
|
$ python TCPServer.py
|
||||||
|
127.0.0.1 wrote:
|
||||||
|
hello world with TCP
|
||||||
|
127.0.0.1 wrote:
|
||||||
|
python is nice
|
||||||
|
|
||||||
|
Client::
|
||||||
|
|
||||||
|
$ python TCPClient.py hello world with TCP
|
||||||
|
Sent: hello world with TCP
|
||||||
|
Received: HELLO WORLD WITH TCP
|
||||||
|
$ python TCPClient.py python is nice
|
||||||
|
Sent: python is nice
|
||||||
|
Received: PYTHON IS NICE
|
||||||
|
|
||||||
|
|
||||||
|
:class:`socketserver.UDPServer` Example
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is the server side::
|
||||||
|
|
||||||
|
import socketserver
|
||||||
|
|
||||||
|
class MyUDPHandler(socketserver.BaseRequestHandler):
|
||||||
|
"""
|
||||||
|
This class works similar to the TCP handler class, except that
|
||||||
|
self.request consists of a pair of data and client socket, and since
|
||||||
|
there is no connection the client address must be given explicitly
|
||||||
|
when sending data back via sendto().
|
||||||
|
"""
|
||||||
|
|
||||||
|
def handle(self):
|
||||||
|
data = self.request[0].strip()
|
||||||
|
socket = self.request[1]
|
||||||
|
print "%s wrote:" % self.client_address[0]
|
||||||
|
print data
|
||||||
|
socket.sendto(data.upper(), self.client_address)
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
HOST, PORT = "localhost", 9999
|
||||||
|
server = socketserver.UDPServer((HOST, PORT), BaseUDPRequestHandler)
|
||||||
|
server.serve_forever()
|
||||||
|
|
||||||
|
This is the client side::
|
||||||
|
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
|
||||||
|
HOST, PORT = "localhost"
|
||||||
|
data = " ".join(sys.argv[1:])
|
||||||
|
|
||||||
|
# SOCK_DGRAM is the socket type to use for UDP sockets
|
||||||
|
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||||
|
|
||||||
|
# As you can see, there is no connect() call; UDP has no connections.
|
||||||
|
# Instead, data is directly sent to the recipient via sendto().
|
||||||
|
sock.sendto(data + "\n", (HOST, PORT))
|
||||||
|
received = sock.recv(1024)
|
||||||
|
|
||||||
|
print "Sent: %s" % data
|
||||||
|
print "Received: %s" % received
|
||||||
|
|
||||||
|
The output of the example should look exactly like for the TCP server example.
|
||||||
|
|
||||||
|
|
||||||
|
Asynchronous Mixins
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To build asynchronous handlers, use the :class:`ThreadingMixIn` and
|
||||||
|
:class:`ForkingMixIn` classes.
|
||||||
|
|
||||||
|
An example for the :class:`ThreadingMixIn` class::
|
||||||
|
|
||||||
|
import socket
|
||||||
|
import threading
|
||||||
|
import socketserver
|
||||||
|
|
||||||
|
class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):
|
||||||
|
|
||||||
|
def handle(self):
|
||||||
|
data = self.request.recv(1024)
|
||||||
|
cur_thread = threading.currentThread()
|
||||||
|
response = "%s: %s" % (cur_thread.getName(), data)
|
||||||
|
self.request.send(response)
|
||||||
|
|
||||||
|
class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def client(ip, port, message):
|
||||||
|
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||||
|
sock.connect((ip, port))
|
||||||
|
sock.send(message)
|
||||||
|
response = sock.recv(1024)
|
||||||
|
print "Received: %s" % response
|
||||||
|
sock.close()
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
# Port 0 means to select an arbitrary unused port
|
||||||
|
HOST, PORT = "localhost", 0
|
||||||
|
|
||||||
|
server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
|
||||||
|
ip, port = server.server_address
|
||||||
|
|
||||||
|
# Start a thread with the server -- that thread will then start one
|
||||||
|
# more thread for each request
|
||||||
|
server_thread = threading.Thread(target=server.serve_forever)
|
||||||
|
# Exit the server thread when the main thread terminates
|
||||||
|
server_thread.setDaemon(True)
|
||||||
|
server_thread.start()
|
||||||
|
print "Server loop running in thread:", t.getName()
|
||||||
|
|
||||||
|
client(ip, port, "Hello World 1")
|
||||||
|
client(ip, port, "Hello World 2")
|
||||||
|
client(ip, port, "Hello World 3")
|
||||||
|
|
||||||
|
server.shutdown()
|
||||||
|
|
||||||
|
The output of the example should look something like this::
|
||||||
|
|
||||||
|
$ python ThreadedTCPServer.py
|
||||||
|
Server loop running in thread: Thread-1
|
||||||
|
Received: Thread-2: Hello World 1
|
||||||
|
Received: Thread-3: Hello World 2
|
||||||
|
Received: Thread-4: Hello World 3
|
||||||
|
|
||||||
|
|
||||||
|
The :class:`ForkingMixIn` class is used in the same way, except that the server
|
||||||
|
will spawn a new process for each request.
|
||||||
|
|
Loading…
Reference in New Issue