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