[tor-commits] [bridgedb/develop] Give the PluggableTransports class a real docstring.

[isis at torproject.org]

commit 18d8d30bf67c13396516cb980cd9523720aa2b40
Author: Isis Lovecruft <isis at torproject.org>
Date:   Thu Mar 20 12:46:17 2014 +0000

    Give the PluggableTransports class a real docstring.
---
 lib/bridgedb/Bridges.py |   52 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 48 insertions(+), 4 deletions(-)

diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py
index 9dbafdf..2fb784a 100644
--- a/lib/bridgedb/Bridges.py
+++ b/lib/bridgedb/Bridges.py
@@ -466,12 +466,56 @@ re_ipv4 = re.compile("((?:\d{1,3}\.?){4}):(.*$)")
 
 
 class PluggableTransport(object):
-    """
-    an object that represents a pluggable-transport method
-    and a reference to the relevant bridge 
-    """
+    """A PT with reference to the parent bridge on which it is running."""
+
     def __init__(self, bridge, methodname, address, port, argdict=None):
+        """Create a ``PluggableTransport`` describing a PT running on a bridge.
+
+        Pluggable transports are described within a bridge's ``@type
+        bridge-extrainfo`` descriptor, see the ``Specifications: Client
+        behavior`` section and the ``TOR_PT_SERVER_TRANSPORT_OPTIONS``
+        description in pt-spec.txt_ for additional specification.
+
+        :type bridge: :class:`Bridge`
+        :param bridge: The parent bridge running this pluggable transport
+            instance, i.e. the main ORPort bridge whose
+            ``@type bridge-server-descriptor`` contains a hash digest for a
+            ``@type bridge-extrainfo-document``, the latter of which contains
+            the parameter of this pluggable transport in its ``transport``
+            line.
+
+        :param str methodname: The canonical "name" for this pluggable
+            transport, i.e. the one which would be specified in a torrc
+            file. For example, ``"obfs2"``, ``"obfs3"``, ``"scramblesuit"``
+            would all be pluggable transport method names.
+
+        :param str address: The IP address of the transport. Currently (as of
+            20 March 2014), there are no known, widely-deployed pluggable
+            transports which support IPv6. Ergo, this is very likely going to
+            be an IPv4 address.
 
+        :param int port: A integer specifying the port which this pluggable
+            transport is listening on. (This should likely be whatever port the
+            bridge specified in its ``ServerTransportPlugin`` torrc line,
+            unless the pluggable transport is running in "managed" mode.)
+
+        :param dict argdict: Some PTs can take additional arguments, which
+            must be distributed to the client out-of-band. These are present
+            in the ``@type bridge-extrainfo-document``, in the ``transport``
+            line like so::
+
+                METHOD SP ADDR ":" PORT SP [K=V[,K=V[,K=V[…]]]]
+
+            where K is the **argdict** key, and V is the value. For example,
+            in the case of ``scramblesuit``, for which the client must supply
+            a shared secret to the ``scramblesuit`` instance running on the
+            bridge, the **argdict** would be something like::
+
+                {'password': 'NEQGQYLUMUQGK5TFOJ4XI2DJNZTS4LRO'}
+
+        .. _pt-spec.txt:
+             https://gitweb.torproject.org/torspec.git/blob/HEAD:/pt-spec.txt
+        """
         #XXX: assert are disabled with python -O
         assert isinstance(bridge, Bridge)
         assert type(address) in (ipaddr.IPv4Address, ipaddr.IPv6Address)