[tor-commits] [bridgedb/develop] Sphinxify all docstrings in bridgedb.Bucket.

isis at torproject.org isis at torproject.org
Thu Aug 21 01:33:15 UTC 2014


commit aa67615395a4a3d29e855a6e510ddc1a276dbed7
Author: Isis Lovecruft <isis at torproject.org>
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()





More information about the tor-commits mailing list