January 2014 - tor-commits - lists.torproject.org

[bridgedb/master] Add docstring for Bridges.PluggableTransport.getTransportLine().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 9e49ce055a3eb7186c81fa9b9fe67f72f2de607c Author: Isis Lovecruft <isis(a)torproject.org> Date: Sat Jan 11 20:12:23 2014 +0000 Add docstring for Bridges.PluggableTransport.getTransportLine(). --- lib/bridgedb/Bridges.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 5b07141..58305b8 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -399,8 +399,19 @@ class PluggableTransport: else: self.argdict = {} def getTransportLine(self, includeFingerprint=False): - """ - returns a torrc bridge line for this transport + """Get a torrc line for this pluggable transport. + + This method does not return lines which are prefixed with the word + 'bridge', as they would be in a torrc file. Instead, lines returned + look like this: + + obfs3 245.102.100.252:23619 59ca743e89b508e16b8c7c6d2290efdfd14eea98 + + :param bool includeFingerprints: If ``True``, include the digest of + this bridges public identity key in the torrc line. + :rtype: str + :returns: A configuration line for adding this pluggable transport + into a torrc file. """ if isinstance(self.address,ipaddr.IPv6Address): address = "[%s]" % self.address

1 0

[bridgedb/master] Add class docstrings for bridgedb.Bridges.BridgeRing.
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 7c8630fe70292158def9886be1b9567cd4b91ad7 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 00:15:43 2014 +0000 Add class docstrings for bridgedb.Bridges.BridgeRing. --- lib/bridgedb/Bridges.py | 61 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 58305b8..198263b 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -653,17 +653,60 @@ class BridgeRingParameters(object): self.needFlags = [(flag.lower(), count) for flag, count in needFlags[:]] class BridgeRing(BridgeHolder): - """Arranges bridges in a ring based on an hmac function.""" - ## Fields: - ## bridges: a map from hmac value to Bridge. - ## bridgesByID: a map from bridge ID Digest to Bridge. - ## isSorted: true iff sortedKeys is currently sorted. - ## sortedKeys: a list of all the hmacs, in order. - ## name: a string to represent this ring in the logs. + """Arranges bridges into a hashring based on an hmac function.""" + def __init__(self, key, answerParameters=None): """Create a new BridgeRing, using key as its hmac key. - :ivar list subrings: XXX + :param key: DOCDOC + :type answerParameters: :class:`BridgeRingParameters` + :param answerParameters: DOCDOC + + :ivar dict bridges: A dictionary which maps HMAC keys to + :class:`~bridgedb.Bridges.Bridge`s. + :ivar dict bridgesByID: A dictionary which maps raw hash digests of + bridge ID keys to + :class:`~bridgedb.Bridges.Bridge`s. + :type hmac: callable + :ivar hmac: An HMAC function, which uses the **key** parameter to + generate new HMACs for storing, inserting, and retrieving + :class:`~bridgedb.Bridges.Bridge`s within mappings. + :ivar bool isSorted: ``True`` if ``sortedKeys`` is currently sorted. + :ivar list sortedKeys: A sorted list of all of the HMACs. + :ivar str name: A string which identifies this hashring, used mostly + for differentiating this hashring in log messages, but + it is also used for naming subrings. If this hashring + is a subring, the ``name`` will include whatever + distinguishing parameters differentiate that + particular subring (i.e. ``'(port-443 subring)'`` or + ``'(Stable subring)'``) + :type subrings: list + :ivar subrings: A list of other ``BridgeRing``s, each of which + contains bridges of a particular type. For example, a + subring might contain only ``Bridge``s which have been + given the "Stable" flag, or it might contain only IPv6 + bridges. Each item in this list should be a 4-tuple: + + ``(type, value, count, ring)`` + + where: + + * ``type`` is a string which describes what kind of + parameter is used to determine if a ``Bridge`` + belongs in that subring, i.e. ``'port'`` or + ``'flag'``. + + * ``value`` is a specific value pertaining to the + ``type``, e.g. ``type='port'; value=443``. + + * ``count`` is an integer for the current total + number of bridges in the subring. + + * ``ring`` is a + :class:`~bridgedb.Bridges.BridgeRing`; it is the + sub hashring which contains ``count`` number of + :class:`~bridgedb.Bridges.Bridge`s of a certain + ``type``. """ self.bridges = {} self.bridgesByID = {} @@ -674,7 +717,7 @@ class BridgeRing(BridgeHolder): answerParameters = BridgeRingParameters() self.answerParameters = answerParameters - self.subrings = [] #DOCDOC + self.subrings = [] for port,count in self.answerParameters.needPorts: #note that we really need to use the same key here, so that # the mapping is in the same order for all subrings.

1 0

[bridgedb/master] Minor PEP8 whitespace fixes in bridgedb.Bridges.BridgeRing.setName().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit eccd03a6d58a0f400c1ae5caa822bbd38dc342cf Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:10:36 2014 +0000 Minor PEP8 whitespace fixes in bridgedb.Bridges.BridgeRing.setName(). --- lib/bridgedb/Bridges.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 198263b..da231a4 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -733,11 +733,11 @@ class BridgeRing(BridgeHolder): :param string name: The name for this hashring. """ self.name = name - for tp,val,_,subring in self.subrings: + for tp, val, _, subring in self.subrings: if tp == 'port': - subring.setName("%s (port-%s subring)"%(name, val)) + subring.setName("%s (port-%s subring)" % (name, val)) else: - subring.setName("%s (%s subring)"%(name, val)) + subring.setName("%s (%s subring)" % (name, val)) def __len__(self): return len(self.bridges)

1 0

[bridgedb/master] Add docstring for bridgedb.Bridges.BridgeRing.__len__().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit b85b8fa915e9f61009790b94a649280ac215e706 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:11:37 2014 +0000 Add docstring for bridgedb.Bridges.BridgeRing.__len__(). --- lib/bridgedb/Bridges.py | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index da231a4..f8f7906 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -740,6 +740,7 @@ class BridgeRing(BridgeHolder): subring.setName("%s (%s subring)" % (name, val)) def __len__(self): + """Get the number of unique bridges this hashring contains.""" return len(self.bridges) def clear(self):

1 0

[bridgedb/master] Add docstring for bridgedb.Bridges.BridgeRing.insert().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit e64e9a588d320d8f4a22379f8c9082f5091ce147 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:12:49 2014 +0000 Add docstring for bridgedb.Bridges.BridgeRing.insert(). --- lib/bridgedb/Bridges.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index e293e40..93d945d 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -754,8 +754,19 @@ class BridgeRing(BridgeHolder): subring.clear() def insert(self, bridge): - """Add a bridge to the ring. If the bridge is already there, - replace the old one.""" + """Add a **bridge** to this hashring. + + The bridge's position in the hashring is dependent upon the HMAC of + the raw hash digest of the bridge's ID key. The function used to + generate the HMAC, :ivar:`BridgeRing.hmac`, is unique to each + individual hashring. + + If the (presumably same) bridge is already at that determined position + in this hashring, replace the old one. + + :type bridge: :class:`~bridgedb.Bridges.Bridge` + :param bridge: The bridge to insert into this hashring. + """ for tp,val,_,subring in self.subrings: if tp == 'port': if val == bridge.orport:

1 0

[bridgedb/master] Fix doctest example in Dist.Distributor.setDistributorName().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 31e4491cb05ec0eec27edfa380a57c5d58fc05c4 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 00:50:07 2014 +0000 Fix doctest example in Dist.Distributor.setDistributorName(). See https://travis-ci.org/isislovecruft/bridgedb/jobs/16798991#L1591, it was erroring because it expected the default hashring name for every hashring which was prepopulated. --- lib/bridgedb/Dist.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Dist.py b/lib/bridgedb/Dist.py index 0b9bff2..8357ca6 100644 --- a/lib/bridgedb/Dist.py +++ b/lib/bridgedb/Dist.py @@ -70,8 +70,8 @@ class Distributor(bridgedb.Bridges.BridgeHolder): >>> ipDist.setDistributorName('HTTPS Distributor') >>> ipDist.prepopulateRings() >>> hashrings = ipDist.splitter.filterRings - >>> for (ringname, (filterFn, subring)) in hashrings.items(): - ... print subring.name + >>> firstSubring = hashrings.items()[0][1][1] + >>> assert firstSubring.name :param str name: A name for this distributor. """

1 0

[bridgedb/master] Add docstring for bridgedb.Bridges.BridgeRing.clear().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 7249c7c0fcf885bcf9e45afc169881bc86f68194 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:12:07 2014 +0000 Add docstring for bridgedb.Bridges.BridgeRing.clear(). --- lib/bridgedb/Bridges.py | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index f8f7906..e293e40 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -744,6 +744,7 @@ class BridgeRing(BridgeHolder): return len(self.bridges) def clear(self): + """Remove all bridges and mappings from this hashring and subrings.""" self.bridges = {} self.bridgesByID = {} self.isSorted = False

1 0

[bridgedb/master] Minor PEP8 whitespace fix in bridgedb.Bridges.BridgeRing.insert().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 579c24896c30d352381e27d56669a27b9cfaa244 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:13:36 2014 +0000 Minor PEP8 whitespace fix in bridgedb.Bridges.BridgeRing.insert(). --- lib/bridgedb/Bridges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 93d945d..e83eea6 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -767,7 +767,7 @@ class BridgeRing(BridgeHolder): :type bridge: :class:`~bridgedb.Bridges.Bridge` :param bridge: The bridge to insert into this hashring. """ - for tp,val,_,subring in self.subrings: + for tp, val, _, subring in self.subrings: if tp == 'port': if val == bridge.orport: subring.insert(bridge)

1 0

[bridgedb/master] Add docstring for bridgedb.Bridges.BridgeRing._getBridgeKeysAt().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 40c248179278645c4ea7992c33d13b33f9f1e016 Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:18:37 2014 +0000 Add docstring for bridgedb.Bridges.BridgeRing._getBridgeKeysAt(). --- lib/bridgedb/Bridges.py | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index e83eea6..504d33b 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -795,8 +795,40 @@ class BridgeRing(BridgeHolder): self.isSorted = True def _getBridgeKeysAt(self, pos, N=1): - """Helper: return the N keys appearing in the ring after position - pos""" + """Bisect a list of bridges at a specified position, **pos**, and + retrieve bridges from that point onwards, wrapping around the hashring + if necessary. + + If the number of bridges requested, **N**, is larger that the size of + this hashring, return the entire ring. Otherwise: + + 1. Sort this bridges in this hashring, if it is currently unsorted. + + 2. Bisect the sorted bridges. If the bridge at the desired position, + **pos**, already exists within this hashring, the the bisection + result is the bridge at position **pos**. Otherwise, the bisection + result is the first position after **pos** which has a bridge + assigned to it. + + 3. Try to obtain **N** bridges, starting at (and including) the + bridge in the requested position, **pos**. + + a. If there aren't **N** bridges after **pos**, wrap back + around to the beginning of the hashring and obtain bridges + until we have **N** bridges. + + 4. Check that the number of bridges obtained is indeed **N**, then + return them. + + :param bytes pos: The position to jump to. Any bridges returned will + start at this position in the hashring, if there is + a bridge assigned to that position. Otherwise, + indexing will start at the first position after this + one which has a bridge assigned to it. + :param int N: The number of bridges to return. + :rtype: list + :returns: A list of :class:`~bridgedb.Bridges.Bridge`s. + """ assert len(pos) == DIGEST_LEN if N >= len(self.sortedKeys): return self.sortedKeys

1 0

[bridgedb/master] Minor PEP8 whitespace fix in bridgedb.Bridges.BridgeRing.getBridges().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit db5a0d28c9706df57c9e6cdcbd04a200f38ee87c Author: Isis Lovecruft <isis(a)torproject.org> Date: Sun Jan 12 01:20:36 2014 +0000 Minor PEP8 whitespace fix in bridgedb.Bridges.BridgeRing.getBridges(). --- lib/bridgedb/Bridges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 2d9dd11..39148a5 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -857,7 +857,7 @@ class BridgeRing(BridgeHolder): :returns: A list of :class:`~bridgedb.Bridges.Bridge`s. """ forced = [] - for _,_,count,subring in self.subrings: + for _, _, count, subring in self.subrings: if len(subring) < count: count = len(subring) forced.extend(subring._getBridgeKeysAt(pos, count))

1 0