[Twisted-Python] Web proxy docstrings

screwtape at froup.com screwtape at froup.com
Sun Dec 15 05:25:14 EST 2002


The other day, I decided to write myself a little bandwidth limiting
web proxy, so I could see how quickly the webpages I was working on
would load over a 28.8k modem, as opposed to the 100Mbit LAN I was on
at the time.

Well, despite my high expectations, Twisted impressed me yet *again*,
since all the pieces I needed were all ready written. However, a large
chunk of my time was taken up finding out how all the various pieces I
had at my disposal actually fitted together. Accordingly, I've
attached a little patch to twisted/web/proxy.py that contains the
documentation I wish I'd found there.

I don't know much about Twisted's documentation standards, but I
figure this little patch is better than nothing. If you do feel the
need to trim it down, though, the detail I most wanted is in the
docstring for the Proxy class.

-- 
 ___________ ____________________________
| Screwtape | Reply-To: munged on Usenet |________ ______ ____ __ _  _   _
|
| Darn rhodents, sigging anything that moves! -- Nils Desle
|
-------------- next part --------------
Index: twisted/web/proxy.py
===================================================================
RCS file: /cvs/Twisted/twisted/web/proxy.py,v
retrieving revision 1.9
diff -u -r1.9 proxy.py
--- twisted/web/proxy.py	15 Nov 2002 20:47:36 -0000	1.9
+++ twisted/web/proxy.py	15 Dec 2002 10:34:04 -0000
@@ -14,7 +14,21 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-"""Simplistic HTTP proxy support."""
+"""Simplistic HTTP proxy support.
+
+This comes in two main variants - the Proxy and the ReverseProxy. 
+
+When a Proxy is in use, a browser trying to connect to a server (say,
+www.yahoo.com) will be intercepted by the Proxy, and the proxy will covertly
+connect to the server, and return the result.
+
+When a ReverseProxy is in use, the client connects directly to the ReverseProxy
+(say, www.yahoo.com) which farms off the request to one of a pool of servers,
+and returns the result.
+
+Normally, a Proxy is used on the client end of an Internet connection, while a
+ReverseProxy is used on the server end.
+"""
 
 # twisted imports
 from twisted.protocols import http
@@ -27,6 +41,7 @@
 
 
 class ProxyClient(http.HTTPClient):
+    """Used by ProxyClientFactory to implement a simple web proxy."""
 
     def __init__(self, command, rest, version, headers, data, father):
         self.father = father
@@ -58,6 +73,7 @@
 
 
 class ProxyClientFactory(protocol.ClientFactory):
+    """Used by ProxyRequest to implement a simple web proxy."""
 
     def __init__(self, command, rest, version, headers, data, father):
         self.father = father
@@ -82,6 +98,7 @@
 
 
 class ProxyRequest(http.Request):
+    """Used by Proxy to impelement a simple web proxy."""
 
     protocols = {'http': ProxyClientFactory}
     ports = {'http': 80}
@@ -107,11 +124,23 @@
         reactor.connectTCP(host, port, clientFactory)
 
 class Proxy(http.HTTPChannel):
+    """This class implements a simple web proxy.
+
+    Since it inherits from twisted.protocols.http.HTTPChannel, to use it you
+    should do something like this:
+
+        from twisted.protocols import http
+        f = http.HTTPFactory()
+        f.HTTPChannel = Proxy
+
+    Make the HTTPFactory a listener on a port as per usual, and you have
+    a fully-functioning web proxy!"""
 
     requestFactory = ProxyRequest
 
 
 class ReverseProxyRequest(http.Request):
+    """Used by ReverseProxy to implement a simple reverse proxy."""
 
     def process(self):
         self.received_headers['host'] = self.factory.host
@@ -123,11 +152,15 @@
                            clientFactory)
 
 class ReverseProxy(http.HTTPChannel):
+    """Implements a simple reverse proxy.
+
+    For details of usage, see the file examples/proxy.py"""
 
     requestFactory = ReverseProxyRequest
 
 
 class ReverseProxyResource(resource.Resource):
+    """Apparently unused."""
 
     def __init__(self, host, port, path):
         resource.Resource.__init__(self)


More information about the Twisted-Python mailing list