[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [bridgedb/develop] Sphinxify all docstrings in bridgedb.Bucket.
commit aa67615395a4a3d29e855a6e510ddc1a276dbed7
Author: Isis Lovecruft <isis@xxxxxxxxxxxxxx>
Date: Wed Aug 20 05:54:43 2014 +0000
Sphinxify all docstrings in bridgedb.Bucket.
---
lib/bridgedb/Bucket.py | 134 +++++++++++++++++++++++++-----------------------
1 file changed, 69 insertions(+), 65 deletions(-)
diff --git a/lib/bridgedb/Bucket.py b/lib/bridgedb/Bucket.py
index b5054ac..5b33a36 100644
--- a/lib/bridgedb/Bucket.py
+++ b/lib/bridgedb/Bucket.py
@@ -38,11 +38,15 @@ toHex = binascii.b2a_hex
PSEUDO_DISTRI_PREFIX = "pseudo_"
class BucketData(object):
- """A file bucket value class.
- name - Name of the bucket (From config), prefixed by pseudo
- distributor prefix
- needed - Needed number of bridges for that bucket (From config)
- allocated - Number of already allocated bridges for that bucket
+ """Configures a bridge bucket with the number of bridges which should be
+ allocated, the name of the bucket, and other similar data.
+
+ :param str name: The name of this bucket (from the config file). This will
+ be prefixed by the :data:`PSEUDO_DISTRIBUTOR_PREFIX`.
+ :type needed: str or int
+ :param needed: The number of bridges needed for this bucket (also from the
+ config file).
+ :param int allocated: Number of bridges already allocated for this bucket.
"""
def __init__(self, name, needed):
self.name = name
@@ -54,57 +58,61 @@ class BucketData(object):
class BucketManager(object):
"""BucketManager reads a number of file bucket identifiers from the config.
- They're expected to be in the following format:
-
- FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }
-
- This syntax means that certain buckets ("name1", "name2" and so on)
- are given a number of bridges (10, 15 and so on). Names can be anything.
- The name will later be the prefix of the file that is written with the
- assigned number of bridges in it. Instead of a number, a wildcard item
- ("*") is allowed, too. This means that the corresponsing bucket file
- will get the maximum number of possible bridges (as many as are left in
- the unallocated bucket).
-
- The files will be written in ip:port format, one bridge per line.
-
- The way this works internally is as follows:
-
- First of all, the assignBridgesToBuckets() routine runs through
- the database of bridges and looks up the 'distributor' field of each
- bridge. Unallocated bridges are sent to a pool for later assignement.
- Already allocated bridges for file bucket distribution are sorted and
- checked.
- They're checked for whether their bucket identifier still exists in the
- current config and also whether the number of assigned bridges is still
- valid. If either the bucket identifier is not existing anymore or too
- many bridges are currently assigned to it, bridges will go to the
- unassigned pool.
-
- In the second step, after bridges are sorted and the unassigned pool is
- ready, the assignBridgesToBuckets() routine assigns one bridge
- from the unassigned pool to a known bucket identifier at a time until it
- either runs out of bridges in the unallocated pool or the number of
- needed bridges for that bucket is reached.
-
- When all bridges are assigned in this way, they can then be dumped into
- files by calling the dumpBridges() routine.
-
- cfg - The central configuration instance
- bucketList - A list of BucketData instances, holding all
- configured (and thus requested) buckets with
- their respective numbers
- unallocatedList - Holding all bridges from the 'unallocated'
- pool
- unallocated_available - Is at least one unallocated bridge
- available?
- distributor_prefix - The 'distributor' field in the database will
- hold the name of our pseudo-distributor,
- prefixed by this
- db - The bridge database access instance
+
+ They're expected to be in the following format::
+
+ FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }
+
+ This syntax means that certain buckets ("name1", "name2" and so on) are
+ given a number of bridges (10, 15 and so on). Names can be anything. The
+ name will later be the prefix of the file that is written with the
+ assigned number of bridges in it. Instead of a number, a wildcard item
+ ("*") is allowed, too. This means that the corresponsing bucket file will
+ get the maximum number of possible bridges (as many as are left in the
+ unallocated bucket).
+
+ The files will be written in ip:port format, one bridge per line.
+
+ The way this works internally is as follows:
+
+ First of all, the assignBridgesToBuckets() routine runs through the
+ database of bridges and looks up the 'distributor' field of each
+ bridge. Unallocated bridges are sent to a pool for later assignement.
+ Already allocated bridges for file bucket distribution are sorted and
+ checked. They're checked for whether their bucket identifier still exists
+ in the current config and also whether the number of assigned bridges is
+ still valid. If either the bucket identifier is not existing anymore or
+ too many bridges are currently assigned to it, bridges will go to the
+ unassigned pool.
+
+ In the second step, after bridges are sorted and the unassigned pool is
+ ready, the assignBridgesToBuckets() routine assigns one bridge from the
+ unassigned pool to a known bucket identifier at a time until it either
+ runs out of bridges in the unallocated pool or the number of needed
+ bridges for that bucket is reached.
+
+ When all bridges are assigned in this way, they can then be dumped into
+ files by calling the dumpBridges() routine.
+
+ :type cfg: :class:`bridgedb.persistent.Conf`
+ :ivar cfg: The central configuration instance.
+ :ivar list bucketList: A list of BucketData instances, holding all
+ configured (and thus requested) buckets with their respective numbers.
+ :ivar list unallocatedList: Holds all bridges from the 'unallocated' pool.
+ :ivar bool unallocated_available: Is at least one unallocated bridge
+ available?
+ :ivar str distributor_prefix: The 'distributor' field in the database will
+ hold the name of our pseudo-distributor, prefixed by this string. By
+ default, this uses :data:`PSEUDO_DISTRIBUTOR_PREFIX`.
+ :ivar db: The bridge database instance.
"""
def __init__(self, cfg):
+ """Create a ``BucketManager``.
+
+ :type cfg: :class:`bridgedb.persistent.Conf`
+ :param cfg: The central configuration instance.
+ """
self.cfg = cfg
self.bucketList = []
self.unallocatedList = []
@@ -112,8 +120,7 @@ class BucketManager(object):
self.distributor_prefix = PSEUDO_DISTRI_PREFIX
def addToUnallocatedList(self, hex_key):
- """Add a bridge by hex_key into the unallocated pool
- """
+ """Add a bridge by **hex_key** into the unallocated pool."""
with bridgedb.Storage.getDB() as db:
try:
db.updateDistributorForHexKey("unallocated", hex_key)
@@ -126,8 +133,8 @@ class BucketManager(object):
self.unallocated_available = True
def getBucketByIdent(self, bucketIdent):
- """Do we know this bucket identifier? If yes, return the corresponding
- BucketData object.
+ """If we know this bucket identifier, then return the corresponding
+ :class:`BucketData` object.
"""
for d in self.bucketList:
if d.name == bucketIdent:
@@ -135,8 +142,7 @@ class BucketManager(object):
return None
def assignUnallocatedBridge(self, bucket):
- """Assign an unallocated bridge to a certain bucket
- """
+ """Assign an unallocated bridge to a certain **bucket**."""
hex_key = self.unallocatedList.pop()
# Mark pseudo-allocators in the database as such
allocator_name = bucket.name
@@ -163,8 +169,8 @@ class BucketManager(object):
return True
def assignBridgesToBuckets(self):
- """Read file bucket identifiers from the configuration, sort them and
- write necessary changes to the database
+ """Read file bucket identifiers from the configuration, sort them, and
+ write necessary changes to the database.
"""
logging.debug("Assigning bridges to buckets for pseudo-distributors")
# Build distributor list
@@ -221,8 +227,7 @@ class BucketManager(object):
self.bucketList.remove(d)
def dumpBridgesToFile(self, filename, bridges):
- """Dump a list of given bridges into a file
- """
+ """Dump a list of given **bridges** into **filename**."""
logging.debug("Dumping bridge assignments to file: %r" % filename)
# get the bridge histories and sort by Time On Same Address
bridgeHistories = []
@@ -263,8 +268,7 @@ class BucketManager(object):
print "I/O error: %s" % filename
def dumpBridges(self):
- """Dump all known file distributors to files, sort by distributor
- """
+ """Dump all known file distributors to files, sorted by distributor."""
logging.info("Dumping all distributors to file.")
with bridgedb.Storage.getDB() as db:
allBridges = db.getAllBridges()
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits