diff options
| -rw-r--r-- | combox/silo.py | 146 |
1 files changed, 103 insertions, 43 deletions
diff --git a/combox/silo.py b/combox/silo.py index e52b815..741772b 100644 --- a/combox/silo.py +++ b/combox/silo.py @@ -25,15 +25,21 @@ from threading import Lock from combox.file import hash_file + class ComboxSilo(object): - """The Combox silo. + """Helps keep track of files in combox directory. - Helps keep track of files in combox directory. - """ + :param dict config: + A dictionary that contains configuration information about + combox. + :param threading.Lock lock: + Lock used by :class:`.ComboxDirMonitor` and + :class:`.NodeDirMonitor` to access this object. + """ def __init__(self, config, lock): - """config: a dictinary which contains combox configuration. + """Initialize ComboxSilo. """ self.config = config @@ -41,9 +47,20 @@ class ComboxSilo(object): self.silo_path = path.join(config['silo_dir'], 'silo.db') self.db = pickledb.load(self.silo_path, True) - ## things we need for housekeep the node directory. + ## things we need for housekeep the node directories self.node_dicts = ['file_created', 'file_modified', 'file_moved', 'file_deleted', 'file_moved_info'] + """List of names of dictionaries stored in DB to housekeep the node + directories. + + Initialized to:: + + ['file_created', 'file_modified', 'file_moved', + 'file_deleted', 'file_moved_info'] + + when :class:`ComboxSilo` object is created. + + """ # created the dicts if not already created. for ndict in self.node_dicts: @@ -54,17 +71,23 @@ class ComboxSilo(object): def reload(self): - """Re-loads the DB from disk.""" + """Re-loads the DB from disk. + + """ with self.lock: self.db = pickledb.load(self.silo_path, True) def update(self, filep): - """Update filep's info in db + """Update filep's info in DB. - filep and the hash of its content is written to the db. + Path of `filep` and the hash of its content is written to the + DB. - filep: path to the file in combox directory. + :param str filep: + Path to the file under the combox directory. + :returns: `True` + :rtype: bool """ self.reload() @@ -74,7 +97,14 @@ class ComboxSilo(object): def keys(self): - """Returns a list of all keys in db.""" + """Returns list of file' paths tracked by combox. + + :returns: + List of file paths of files tracked by combox. + :rtype: + `True` + + """ # this is why Redis or some other key-value DB should be used # instead of PickleDB self.reload() @@ -83,9 +113,15 @@ class ComboxSilo(object): def remove(self, filep): - """Removes filep from db. + """Removes `filep` from DB. - filep: path to the file in combox directory. + :param str filep: + Path to a file under combox directory whose information + has to be removed from the DB. + :returns: + Returns `False` if `filep` is not present in the DB; `True` + otherwise. + :rtype: bool """ try: @@ -98,11 +134,13 @@ class ComboxSilo(object): def exists(self, filep): - """Checks if filep's info is stored in db. + """Checks if filep's info is stored in DB. - Returns True if filep's info is in db; False otherwise. - - filep: path to the file in combox directory. + :param str filep: + Path to a file under the combox directory. + :returns: + Returns `True` if filep's info is in DB; `False` otherwise. + :rtype: bool """ self.reload() @@ -114,15 +152,19 @@ class ComboxSilo(object): def stale(self, filep, fhash=None): - """Returns True if filep's hash is different from the hash stored in db. - - Returns None, if filep's info is not yet stored in db. - Returns False, if filep's hash has not changed it. + """Checks if filep's info in the DB is outdated. + + :param str filep: + Path to a file under the combox directory. + :param bool fhash: + If not `None`, it is assumed to be filep's hash. + :returns: + Returns `True`, if filep's hash is outdated; `False` if + filep's hash is correct; `None` if filep's info is not yet + stored in DB. + :rtype: bool - filep: path to the file in combox directory. - fhash: If not None, it is assumed to be filep's hash. """ - if not fhash: fhash = hash_file(filep) @@ -139,19 +181,24 @@ class ComboxSilo(object): def nodedicts(self): - """ - Returns a list containing the dicts related the the node directories. + """Returns :attr:`node_dicts` + """ return self.node_dicts def node_set(self, type_, file_, num=-1): - """ - Update information about the shard of `file_'. + """Update information about the shard of `file_` in dictionary `type_` in the DB. + + :param str type_: + The name of the dictinary in DB. It must be one of the + following values: `file_created`, `file_modified`, + `file_moved`, `file_deleted`. + :param str file_: + Path of the file under the combox directory. + :param int num: + Integer associated with the `file_`. - type_: 'file_created', 'file_modified', 'file_moved', 'file_deleted' - file_: path of the file_ in combox directory. - num: (optional) integer associated with the `file_'. """ self.reload() @@ -173,11 +220,13 @@ class ComboxSilo(object): def node_store_moved_info(self, src_path, dest_path): """ - Update/create about file move. + Make note of a file/directory moved from `src_path` to `dest_path`. + + :param str src_path: + The source path of the file being moved. + :param str dest_path: + The destination path of the file being moved. - type_: expected type is 'file_moved_info'. - src_path: usually the source path of the file being moved. - dest_path: usually the destination path of the file being moved. """ self.reload() with self.lock: @@ -185,11 +234,19 @@ class ComboxSilo(object): def node_get(self, type_, file_): - """ - Returns a number denoting the number of node directories in which the file_'s shard was created/modified/moved/deleted. + """Returns a number denoting the number of node directories in which the `file_`'s shards was created/modified/moved/deleted. + + :param str type_: + The name of the dictinary in DB. It must be one of the + following values: `file_created`, `file_modified`, + `file_moved`, `file_deleted`. + :param str file_: + Path of the file under the combox directory. + :returns: + Number denoting the number of node directories in which + the `file_`' shards were created/modified/moved/deleted. + :rtype: int - type_: 'file_created', 'file_modified', 'file_moved', 'file_deleted' - file_: path of the file_ in combox directory. """ self.reload() with self.lock: @@ -201,13 +258,16 @@ class ComboxSilo(object): def node_rem(self, type_, file_): - """ - Removes information about the shard of `file_'. + """Removes information about the shards of `file_` in the `type_` dictionary in DB. - type_: 'file_created', 'file_modified', 'file_moved', 'file_deleted' - file_: path of the file_ in combox directory. - """ + :param str type_: + The name of the dictinary in DB. It must be one of the + following values: `file_created`, `file_modified`, + `file_moved`, `file_deleted`. + :param str file_: + Path of the file under the combox directory. + """ self.reload() with self.lock: try: |