commit 18d8d30bf67c13396516cb980cd9523720aa2b40 Author: Isis Lovecruft <isis@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)