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

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

12 Jan '14

commit e41a2acf1ddf3aa84584bd65511803bd7f1385ac Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:24:46 2013 +0000 Add a docstring to bridgedb.Bridges.BridgeRing.setName(). --- lib/bridgedb/Bridges.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index d77e632..a49da9f 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -730,7 +730,10 @@ class BridgeRing(BridgeHolder): self.setName("Ring") def setName(self, name): - """DOCDOC""" + """Tag a unique name to this hashring for identification. + + :param string name: The name for this hashring. + """ self.name = name for tp,val,_,subring in self.subrings: if tp == 'port':

1 0

[bridgedb/master] Add a docstring to __init__ constructor for BridgeRingParameters.
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit e71c6705fd0245c259c39f63a0806a30fa001597 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:21:32 2013 +0000 Add a docstring to __init__ constructor for BridgeRingParameters. --- lib/bridgedb/Bridges.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 4627a88..97c93f6 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -658,9 +658,31 @@ class BridgeRingParameters(object): .. _flags: https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt#l1696 """ - def __init__(self, needPorts=(), needFlags=()): - """DOCDOC takes list of port, count""" - for port,count in needPorts: + def __init__(self, needPorts=[], needFlags=[]): + """Control the creation of subrings by including a minimum number of + bridges which possess certain attributes. + + XXX In bridgedb.conf, there is a note on the FORCE_FLAGS setting which + reads: "Only 'stable' is now supported." Is this still the case? + Why? + + :type needPorts: iterable + :param needPorts: An iterable of two-tuples. Each two tuple should + contain ``(port, minimum)``, where ``port`` is an integer + specifying a port number, and ``minimum`` is another integer + specifying the minimum number of Bridges running on that ``port`` + to include in any new subring. + :type needFlags: iterable + :param needFlags: An iterable of two-tuples. Each two tuple should + contain ``(flag, minimum)``, where ``flag`` is a string specifying + an OR flag_, and ``minimum`` is an integer for the minimum number + of Bridges which have acquired that ``flag`` to include in any new + subring. + :raises: An :exc:`TypeError` if an invalid port number, a minimum less + than one, or an "unsupported" flag is given. "Stable" appears to + be the only currently "supported" flag. + """ + for port, count in needPorts: if not (1 <= port <= 65535): raise TypeError("Port %s out of range."%port) if count <= 0:

1 0

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

12 Jan '14

commit b4fc2b92afc2498441ff82c2d6be3bd20285d01e Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:25:39 2013 +0000 Add a docstring to bridgedb.Bridges.FixedBridgeSplitter.clear(). --- lib/bridgedb/Bridges.py | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index a49da9f..a0d853e 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -856,6 +856,7 @@ class FixedBridgeSplitter(BridgeHolder): self.rings[which].insert(bridge) def clear(self): + """Clear all bridges from every ring in ``rings``.""" for r in self.rings: r.clear()

1 0

[bridgedb/master] Start documenting sub-hashring ivars in Bridges.BridgeRing class.
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit bf25c8b3a2ec23a5df653145e7930b306ecf9b9b Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:24:02 2013 +0000 Start documenting sub-hashring ivars in Bridges.BridgeRing class. --- lib/bridgedb/Bridges.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 8e28e7b..d77e632 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -706,7 +706,10 @@ class BridgeRing(BridgeHolder): ## sortedKeys: a list of all the hmacs, in order. ## name: a string to represent this ring in the logs. def __init__(self, key, answerParameters=None): - """Create a new BridgeRing, using key as its hmac key.""" + """Create a new BridgeRing, using key as its hmac key. + + :ivar list subrings: XXX + """ self.bridges = {} self.bridgesByID = {} self.hmac = get_hmac_fn(key, hex=False)

1 0

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

12 Jan '14

commit 595c57b60d55c674fb78e9d339e7ef2df1946b9f Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:27:04 2013 +0000 Add a docstring to bridgedb.Bridges.FixedBridgeSplitter.__len__(). --- lib/bridgedb/Bridges.py | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index a0d853e..1371ce8 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -861,6 +861,7 @@ class FixedBridgeSplitter(BridgeHolder): r.clear() def __len__(self): + """Returns the total number of bridges in all ``rings``.""" n = 0 for r in self.rings: n += len(r)

1 0

[bridgedb/master] Add docstring to FixedBridgeSplitter.dumpAssignments().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 973e280baa6c1232bcfdd18dd993c9756c28dc33 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:30:39 2013 +0000 Add docstring to FixedBridgeSplitter.dumpAssignments(). --- lib/bridgedb/Bridges.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 819cdd2..4cafda0 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -867,9 +867,17 @@ class FixedBridgeSplitter(BridgeHolder): total += len(ring) return total - def dumpAssignments(self, f, description=""): + def dumpAssignments(self, filename, description=""): + """Write all bridges assigned to this hashring to ``filename``. + + :param string description: If given, include a description next to the + index number of the ring from :attr:`FilteredBridgeHolder.rings` + the following bridges were assigned to. For example, if the + description is ``"IPv6 obfs2 bridges"`` the line would read: + ``"IPv6 obfs2 bridges ring=3"``. + """ for i,r in zip(xrange(len(self.rings)), self.rings): - r.dumpAssignments(f, "%s ring=%s" % (description, i)) + r.dumpAssignments(filename, "%s ring=%s" % (description, i)) class UnallocatedHolder(BridgeHolder): """A pseudo-bridgeholder that ignores its bridges and leaves them

1 0

[bridgedb/master] PEP8 / make variable names clearer in FixedBridgeSplitter.__len__().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 8363316f8b6ffbc9057c7c0fa3798bca04e3d8d7 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:28:15 2013 +0000 PEP8 / make variable names clearer in FixedBridgeSplitter.__len__(). --- lib/bridgedb/Bridges.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 1371ce8..819cdd2 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -862,10 +862,10 @@ class FixedBridgeSplitter(BridgeHolder): def __len__(self): """Returns the total number of bridges in all ``rings``.""" - n = 0 - for r in self.rings: - n += len(r) - return n + total = 0 + for ring in self.rings: + total += len(ring) + return total def dumpAssignments(self, f, description=""): for i,r in zip(xrange(len(self.rings)), self.rings):

1 0

[bridgedb/master] Rename `index` and `ring` in FixedBridgeSplitter.dumpAssignments().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 6e88838c4ce399ba9ac7ac481b44bc478cf73452 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:31:28 2013 +0000 Rename `index` and `ring` in FixedBridgeSplitter.dumpAssignments(). Because `i` and `r` weren't immediately clear to me what they were referring to. --- lib/bridgedb/Bridges.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 4cafda0..6ffd116 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -876,8 +876,8 @@ class FixedBridgeSplitter(BridgeHolder): description is ``"IPv6 obfs2 bridges"`` the line would read: ``"IPv6 obfs2 bridges ring=3"``. """ - for i,r in zip(xrange(len(self.rings)), self.rings): - r.dumpAssignments(filename, "%s ring=%s" % (description, i)) + for index, ring in zip(xrange(len(self.rings)), self.rings): + ring.dumpAssignments(filename, "%s ring=%s" % (description, index)) class UnallocatedHolder(BridgeHolder): """A pseudo-bridgeholder that ignores its bridges and leaves them

1 0

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

12 Jan '14

commit f6a04be064e352ad6678fe3cba7e9a83941d5c82 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:32:42 2013 +0000 Add docstring to FilteredBridgeSplitter.insert(). --- lib/bridgedb/Bridges.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 6ffd116..d58d7f0 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -1023,6 +1023,14 @@ class FilteredBridgeSplitter(BridgeHolder): self.filterRings = {} def insert(self, bridge): + """Insert a bridge into all appropriate sub-hashrings. + + For all sub-hashrings, the ``bridge`` will only be added iff it passes + the filter functions for that sub-hashring. + + :type bridge: :class:`~bridgedb.Bridges.Bridge` + :param bridge: The bridge to add. + """ if not bridge.running: logging.debug("insert non-running bridge %s" % bridge.getID()) return

1 0

[bridgedb/master] Sphinxify and improve docstring for FilteredBridgeSplitter.addRing().
by isis＠torproject.org 12 Jan '14

12 Jan '14

commit 4747c1d2a184e94711d32e26d85494a1340661f4 Author: Isis Lovecruft <isis(a)torproject.org> Date: Fri Nov 15 13:39:22 2013 +0000 Sphinxify and improve docstring for FilteredBridgeSplitter.addRing(). --- lib/bridgedb/Bridges.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py index 340ac44..a59c56d 100644 --- a/lib/bridgedb/Bridges.py +++ b/lib/bridgedb/Bridges.py @@ -1046,12 +1046,17 @@ class FilteredBridgeSplitter(BridgeHolder): logging.debug("insert bridge into %s" % n) def addRing(self, ring, ringname, filterFn, populate_from=None): - """Add a ring to this splitter. - ring -- the ring to add - ringname -- a unique string identifying the ring - filterFn -- a function whose input is a Bridge, and returns - True or False - populate_from -- an iterable of Bridges + """Add a subring to this hashring. + + :type subring: :class:`BridgeHolder` + :param subring: The subring to add. + :param string ringname: A unique name for identifying the new + subring. + :param filterFn: A function whose input is a :class:`Bridge`, and + returns True/False based on some filtration criteria. + :type populate_from: iterable or None + :param populate_from: A group of :class:`Bridge`s. If given, the newly + added subring will be populated with these bridges. """ assert isinstance(ring, BridgeHolder) assert ringname not in self.filterRings.keys()

1 0