Ticket #5513: my-twisted-patch.patch

File my-twisted-patch.patch, 7.3 KB (added by zimmer, 8 years ago)

.patch that shows the added docstrings

  • twisted/web/proxy.py

     
    11# -*- test-case-name: twisted.web.test.test_proxy -*-
    2 # Copyright (c) Twisted Matrix Laboratories.
     2# Copyright (c) 2001-2010 Twisted Matrix Laboratories.
    33# See LICENSE for details.
    44
    55"""
     
    4040    _finished = False
    4141
    4242    def __init__(self, command, rest, version, headers, data, father):
     43        """
     44        Usually created when ProxyClientFactory.buildProtocol is called.
     45        The arguments passed to this __init__ are the same as the ones passed
     46        to ProxyClientFactory.__init__.
     47        @type command: C(str)
     48        @param command: HTTP Command (GET, POST, HEAD, etc)
     49       
     50        @type rest: C(str)
     51        @param rest: Rest of url other than host, ex. example.com/test.html
     52               /test.html is the rest
     53                     
     54        @type version: C(str)
     55        @param version: HTTP Version (HTTP/1.1, HTTP/1.0)
     56       
     57        @type headers: C(dict)
     58        @param headers: The headers that were specified in the request to
     59               (or through) the proxy server
     60         
     61        @type data: C(str)
     62        @param data: Data sent to (or through) the server for example with a
     63               POST requst
     64               
     65        @type father: C(ProxyRequest)
     66        @param father: The server request first passed to the ProxyClientFactory
     67               and then the ProxyClient when buildProtocol is called
     68        """
    4369        self.father = father
    4470        self.command = command
    4571        self.rest = rest
     
    6086
    6187
    6288    def handleStatus(self, version, code, message):
     89        """
     90        Handles the status sent from the remote server back to the client.
     91        Passes it onto the proxy server and then back to the user.
     92        @param version: HTTP Version (HTTP/1.1. HTTP/1.0)
     93        @param code: HTTP status code (200, 404, 403, etc)
     94        @param message: Message sent with the status
     95        """
    6396        self.father.setResponseCode(int(code), message)
    6497
    6598
    6699    def handleHeader(self, key, value):
     100        """
     101        Handles a header sent from the remote server back to the client
     102        Passes the header back to the proxy server and then back to the user
     103
     104        @type key: C{str}
     105        @param key: An HTTP header field name.
     106
     107        @type value: C{str}
     108        @param value: An HTTP header field value.
     109        """
     110
    67111        # t.web.server.Request sets default values for these headers in its
    68112        # 'process' method. When these headers are received from the remote
    69113        # server, they ought to override the defaults, rather than append to
     
    75119
    76120
    77121    def handleResponsePart(self, buffer):
     122        """
     123        Handles some data received by the client.
     124        Writes the data back to the proxy server.
     125       
     126        @type buffer: C(str)
     127        @param buffer: The data that was received from the remote server.
     128        """
    78129        self.father.write(buffer)
    79130
    80131
    81132    def handleResponseEnd(self):
    82133        """
     134        Handles the end of the connection to the remote server.
    83135        Finish the original request, indicating that the response has been
    84136        completely written to it, and disconnect the outgoing transport.
    85137        """
     
    99151
    100152
    101153    def __init__(self, command, rest, version, headers, data, father):
     154        """
     155        Copied from equivalent arguments passed to the protocol
     156        @type command: C(str)
     157        @param command: HTTP Command (GET, POST, HEAD, etc)
     158       
     159        @type rest: C(str)
     160        @param rest: Rest of url other than host, ex. example.com/test.html
     161               /test.html is the rest
     162                     
     163        @type version: C(str)
     164        @param version: HTTP Version (HTTP/1.1, HTTP/1.0)
     165       
     166        @type headers: C(dict)
     167        @param headers: The headers that were specified in the request to
     168               (or through) the proxy server
     169         
     170        @type data: C(str)
     171        @param data: Data sent to (or through) the server for example with a
     172               POST requst
     173               
     174        @type father: C(ProxyRequest)
     175        @param father: The server request first passed to the ProxyClientFactory
     176               and then the ProxyClient when buildProtocol is called
     177       
     178        """
    102179        self.father = father
    103180        self.command = command
    104181        self.rest = rest
     
    108185
    109186
    110187    def buildProtocol(self, addr):
     188        """
     189        Builds ProxyClient, passing the arugments set in __init__, and returns
     190        the protocol
     191        """
    111192        return self.protocol(self.command, self.rest, self.version,
    112193                             self.headers, self.data, self.father)
    113194
     
    136217    ports = {'http': 80}
    137218
    138219    def __init__(self, channel, queued, reactor=reactor):
     220        """
     221        Implements the proxy server's request handler see
     222       
     223        @type channel: C(Proxy)
     224        @param channel: Used as connection between your client and the proxy server
     225       
     226        @type queued: C(bool)
     227        @param queued: Is the request queued or can we write to the transport now?
     228       
     229        @type reactor: C(twisted.internet.reactor)
     230        @param reactor: Needed here to connect the Proxy client end to the remote server
     231        """
    139232        Request.__init__(self, channel, queued)
    140233        self.reactor = reactor
    141234
    142235
    143236    def process(self):
     237        """
     238        Called to process the request from your client
     239        This method parses the url (to see what the proxy needs to go fetch) and
     240        then connects to that url (just like if your program connect to example.com
     241        except the proxy server does it not your client directly) using the class
     242        specified in protocols.
     243        Overide if you want to control things such as headers and method sent to
     244        the remote server (for example if you want any GET request to change to a
     245        HEAD request)
     246        """
    144247        parsed = urlparse.urlparse(self.uri)
    145248        protocol = parsed[0]
    146249        host = parsed[1]
     
    167270    """
    168271    This class implements a simple web proxy.
    169272
    170     Since it inherits from L{twisted.web.http.HTTPChannel}, to use it you
     273    Since it inherits from L{twisted.protocols.http.HTTPChannel}, to use it you
    171274    should do something like this::
    172275
    173276        from twisted.web import http
     
    176279
    177280    Make the HTTPFactory a listener on a port as per usual, and you have
    178281    a fully-functioning web proxy!
     282
     283    The HTTP channel that your client and the proxy server communicate over.
     284    Subclasses HTTPChannel and just changes what request factory to use so
     285    instead of using one that say servers files you use C(ProxyRequest) to then
     286    connect to a remote host and serve that instead of boring files.
     287
    179288    """
    180289
    181290    requestFactory = ProxyRequest
     
    220329    """
    221330    Implements a simple reverse proxy.
    222331
    223     For details of usage, see the file examples/reverse-proxy.py.
     332    For details of usage, see the file examples/proxy.py.
    224333    """
    225334
    226335    requestFactory = ReverseProxyRequest
     
    301410            request.getAllHeaders(), request.content.read(), request)
    302411        self.reactor.connectTCP(self.host, self.port, clientFactory)
    303412        return NOT_DONE_YET
     413