diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile | 2 | ||||
| -rw-r--r-- | Doc/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libsocksvr.tex | 188 | ||||
| -rw-r--r-- | Doc/libsocksvr.tex | 188 |
5 files changed, 379 insertions, 1 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index a136685..98f7f61 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -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) diff --git a/Doc/lib.tex b/Doc/lib.tex index 4839415..bc30bae 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -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} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 4839415..bc30bae 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -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} diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex new file mode 100644 index 0000000..1e3cac3 --- /dev/null +++ b/Doc/lib/libsocksvr.tex @@ -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} diff --git a/Doc/libsocksvr.tex b/Doc/libsocksvr.tex new file mode 100644 index 0000000..1e3cac3 --- /dev/null +++ b/Doc/libsocksvr.tex @@ -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} |