commit e71c6705fd0245c259c39f63a0806a30fa001597 Author: Isis Lovecruft <isis@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: