traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added AMK's SocketServer docs.

This commit is contained in:
Guido van Rossum 1997-05-19 19:55:16 +00:00
parent fe4dfc7ce3
commit 6181e00667
5 changed files with 379 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/Makefile
View File

@ -110,7 +110,7 @@ LIBFILES = lib.tex \
libformatter.tex liboperator.tex libsoundex.tex libresource.tex \
libstat.tex libstrio.tex libundoc.tex libmailcap.tex libglob.tex \
libuser.tex libanydbm.tex librandom.tex libsite.tex libwhichdb.tex \
libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex
libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex
# Library document
lib.dvi: $(LIBFILES)

1
Doc/lib.tex
View File

@ -160,6 +160,7 @@ to Python and how to embed it in other applications.
\input{libmailcap}
\input{libbase64}
\input{libquopri}
\input{libsocksvr}
\input{librestricted}
\input{librexec}

1
Doc/lib/lib.tex
View File

@ -160,6 +160,7 @@ to Python and how to embed it in other applications.
\input{libmailcap}
\input{libbase64}
\input{libquopri}
\input{libsocksvr}
\input{librestricted}
\input{librexec}

188
Doc/lib/libsocksvr.tex Normal file
View File

@ -0,0 +1,188 @@
\section{Standard Module \sectcode{SocketServer}}
\stmodindex{SocketServer}
The \code{SocketServer} module simplifies the task of writing network
servers.
There are four basic server classes: \code{TCPServer} uses the
Internet TCP protocol, which provides for continuous streams of data
between the client and server. \code{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
\code{UnixStreamServer} and \code{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 \emph{Unix Network Programming}_ or
XXX (a Windows equivalent).
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 request takes a long time to complete, because it
requires a lot of computation, or because it returns a lot of data
which the client is slow to process. The solution is to create a
separate process or thread to handle each request; the
\code{ForkingMixIn} and \code{ThreadingMixIn} mix-in classes can be
used to support asynchronous behaviour.
Creating a server requires several steps. First, you must create a
request handler class by subclassing the \code{BaseRequestHandler}
class and overriding its \code{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. Finally, call the \code{handle_request()} or
\code{serve_forever()} method of the server object to process one or
many requests.
Server classes have the same external methods and attributes, no
matter what network protocol they use:
%XXX should data and methods be intermingled, or separate?
% how should the distinction between class and instance variables be
% drawn?
\begin{funcdesc}{fileno}{}
Return an integer file descriptor for the socket on which the server
is listening. This function is most commonly passed to
\code{select.select()}, to allow monitoring multiple servers in the
same process.
\end{funcdesc}
\begin{funcdesc}{handle_request}{}
Process a single request. This function calls the following methods
in order: \code{get_request()}, \code{verify_request()}, and
\code{process_request()}. If the user-provided \code{handle()} method
of the handler class raises an exception, the server's
\code{handle_error()} method will be called.
\end{funcdesc}
\begin{funcdesc}{serve_forever}{}
Handle an infinite number of requests. This simply calls
\code{handle_request()} inside an infinite loop.
\end{funcdesc}
\begin{datadesc}{address_family}
The family of protocols to which the server's socket belongs.
\code{socket.AF_INET} and \code{socket.AF_UNIX} are two possible values.
\end{datadesc}
\begin{datadesc}{RequestHandlerClass}
The user-provided request handler class; an instance of this class is
created for each request.
\end{datadesc}
\begin{datadesc}{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
socket module for details. For Internet protocols, this is a tuple
containing a string giving the address, and an integer port number:
\code{('127.0.0.1', 80)}, for example.
\end{datadesc}
\begin{datadesc}{socket}
The socket object on which the server will listen for incoming requests.
\end{datadesc}
% XXX should class variables be covered before instance variables, or
% vice versa?
The server classes support the following class variables:
\begin{datadesc}{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 \code{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.
\end{datadesc}
\begin{datadesc}{socket_type}
The type of socket used by the server; \code{socket.SOCK_STREAM} and
\code{socket.SOCK_DGRAM} are two possible values.
\end{datadesc}
There are various server methods that can be overridden by subclasses
of base server classes like \code{TCPServer}; these methods aren't
useful to external users of the server object.
% should the default implementations of these be documented, or should
% it be assumed that the user will look at SocketServer.py?
\begin{funcdesc}{finish_request}{}
Actually processes the request by instantiating
\code{RequestHandlerClass} and calling its \code{handle()} method.
\end{funcdesc}
\begin{funcdesc}{get_request}{}
Must accept a request from the socket, and return a 2-tuple containing
the \emph{new} socket object to be used to communicate with the
client, and the client's address.
\end{funcdesc}
\begin{funcdesc}{handle_error}{request\, client_address}
This function is called if the \code{RequestHandlerClass}'s
\code{handle} method raises an exception. The default action is to print
the traceback to standard output and continue handling further requests.
\end{funcdesc}
\begin{funcdesc}{process_request}{request\, client_address}
Calls \code{finish_request()} to create an instance of the
\code{RequestHandlerClass}. If desired, this function can create a new
process or thread to handle the request; the \code{ForkingMixIn} and
\code{ThreadingMixIn} classes do this.
\end{funcdesc}
% 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?
\begin{funcdesc}{server_activate}{}
Called by the server's constructor to activate the server.
May be overridden.
\end{funcdesc}
\begin{funcdesc}{server_bind}{}
Called by the server's constructor to bind the socket to the desired
address. May be overridden.
\end{funcdesc}
\begin{funcdesc}{verify_request}{request\, client_address}
Must return a Boolean value; if the value is true, the request will be
processed, and if it's false, the request will be denied.
This function can be overridden to implement access controls for a server.
The default implementation always return true.
\end{funcdesc}
The request handler class must define a new \code{handle} method, and
can override any of the following methods. A new instance is created
for each request.
\begin{funcdesc}{finish}{}
Called after the \code{handle} method to perform any clean-up actions
required. The default implementation does nothing. If \code{setup()}
or \code{handle()} raise an exception, this function will not be called.
\end{funcdesc}
\begin{funcdesc}{handle}{}
This function must do all the work required to service a request.
Several instance attributes are available to it; the request is
available as \code{self.request}; the client address as
\code{self.client_request}; and the server instance as \code{self.server}, in
case it needs access to per-server information.
The type of \code{self.request} is different for datagram or stream
services. For stream services, \code{self.request} is a socket
object; for datagram services, \code{self.request} is a string.
However, this can be hidden by using the mix-in request handler
classes
\code{StreamRequestHandler} or \code{DatagramRequestHandler}, which
override the \code{setup} and \code{finish} methods, and provides
\code{self.rfile} and \code{self.wfile} attributes. \code{self.rfile}
and \code{self.wfile} can be read or written, respectively, to get the
request data or return data to the client.
\end{funcdesc}
\begin{funcdesc}{setup}{}
Called before the \code{handle} method to perform any initialization
actions required. The default implementation does nothing.
\end{funcdesc}

188
Doc/libsocksvr.tex Normal file
View File

@ -0,0 +1,188 @@
\section{Standard Module \sectcode{SocketServer}}
\stmodindex{SocketServer}
The \code{SocketServer} module simplifies the task of writing network
servers.
There are four basic server classes: \code{TCPServer} uses the
Internet TCP protocol, which provides for continuous streams of data
between the client and server. \code{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
\code{UnixStreamServer} and \code{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 \emph{Unix Network Programming}_ or
XXX (a Windows equivalent).
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 request takes a long time to complete, because it
requires a lot of computation, or because it returns a lot of data
which the client is slow to process. The solution is to create a
separate process or thread to handle each request; the
\code{ForkingMixIn} and \code{ThreadingMixIn} mix-in classes can be
used to support asynchronous behaviour.
Creating a server requires several steps. First, you must create a
request handler class by subclassing the \code{BaseRequestHandler}
class and overriding its \code{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. Finally, call the \code{handle_request()} or
\code{serve_forever()} method of the server object to process one or
many requests.
Server classes have the same external methods and attributes, no
matter what network protocol they use:
%XXX should data and methods be intermingled, or separate?
% how should the distinction between class and instance variables be
% drawn?
\begin{funcdesc}{fileno}{}
Return an integer file descriptor for the socket on which the server
is listening. This function is most commonly passed to
\code{select.select()}, to allow monitoring multiple servers in the
same process.
\end{funcdesc}
\begin{funcdesc}{handle_request}{}
Process a single request. This function calls the following methods
in order: \code{get_request()}, \code{verify_request()}, and
\code{process_request()}. If the user-provided \code{handle()} method
of the handler class raises an exception, the server's
\code{handle_error()} method will be called.
\end{funcdesc}
\begin{funcdesc}{serve_forever}{}
Handle an infinite number of requests. This simply calls
\code{handle_request()} inside an infinite loop.
\end{funcdesc}
\begin{datadesc}{address_family}
The family of protocols to which the server's socket belongs.
\code{socket.AF_INET} and \code{socket.AF_UNIX} are two possible values.
\end{datadesc}
\begin{datadesc}{RequestHandlerClass}
The user-provided request handler class; an instance of this class is
created for each request.
\end{datadesc}
\begin{datadesc}{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
socket module for details. For Internet protocols, this is a tuple
containing a string giving the address, and an integer port number:
\code{('127.0.0.1', 80)}, for example.
\end{datadesc}
\begin{datadesc}{socket}
The socket object on which the server will listen for incoming requests.
\end{datadesc}
% XXX should class variables be covered before instance variables, or
% vice versa?
The server classes support the following class variables:
\begin{datadesc}{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 \code{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.
\end{datadesc}
\begin{datadesc}{socket_type}
The type of socket used by the server; \code{socket.SOCK_STREAM} and
\code{socket.SOCK_DGRAM} are two possible values.
\end{datadesc}
There are various server methods that can be overridden by subclasses
of base server classes like \code{TCPServer}; these methods aren't
useful to external users of the server object.
% should the default implementations of these be documented, or should
% it be assumed that the user will look at SocketServer.py?
\begin{funcdesc}{finish_request}{}
Actually processes the request by instantiating
\code{RequestHandlerClass} and calling its \code{handle()} method.
\end{funcdesc}
\begin{funcdesc}{get_request}{}
Must accept a request from the socket, and return a 2-tuple containing
the \emph{new} socket object to be used to communicate with the
client, and the client's address.
\end{funcdesc}
\begin{funcdesc}{handle_error}{request\, client_address}
This function is called if the \code{RequestHandlerClass}'s
\code{handle} method raises an exception. The default action is to print
the traceback to standard output and continue handling further requests.
\end{funcdesc}
\begin{funcdesc}{process_request}{request\, client_address}
Calls \code{finish_request()} to create an instance of the
\code{RequestHandlerClass}. If desired, this function can create a new
process or thread to handle the request; the \code{ForkingMixIn} and
\code{ThreadingMixIn} classes do this.
\end{funcdesc}
% 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?
\begin{funcdesc}{server_activate}{}
Called by the server's constructor to activate the server.
May be overridden.
\end{funcdesc}
\begin{funcdesc}{server_bind}{}
Called by the server's constructor to bind the socket to the desired
address. May be overridden.
\end{funcdesc}
\begin{funcdesc}{verify_request}{request\, client_address}
Must return a Boolean value; if the value is true, the request will be
processed, and if it's false, the request will be denied.
This function can be overridden to implement access controls for a server.
The default implementation always return true.
\end{funcdesc}
The request handler class must define a new \code{handle} method, and
can override any of the following methods. A new instance is created
for each request.
\begin{funcdesc}{finish}{}
Called after the \code{handle} method to perform any clean-up actions
required. The default implementation does nothing. If \code{setup()}
or \code{handle()} raise an exception, this function will not be called.
\end{funcdesc}
\begin{funcdesc}{handle}{}
This function must do all the work required to service a request.
Several instance attributes are available to it; the request is
available as \code{self.request}; the client address as
\code{self.client_request}; and the server instance as \code{self.server}, in
case it needs access to per-server information.
The type of \code{self.request} is different for datagram or stream
services. For stream services, \code{self.request} is a socket
object; for datagram services, \code{self.request} is a string.
However, this can be hidden by using the mix-in request handler
classes
\code{StreamRequestHandler} or \code{DatagramRequestHandler}, which
override the \code{setup} and \code{finish} methods, and provides
\code{self.rfile} and \code{self.wfile} attributes. \code{self.rfile}
and \code{self.wfile} can be read or written, respectively, to get the
request data or return data to the client.
\end{funcdesc}
\begin{funcdesc}{setup}{}
Called before the \code{handle} method to perform any initialization
actions required. The default implementation does nothing.
\end{funcdesc}