combox/file.py: updated docstrings.

2 files changed, 189 insertions, 84 deletions

diff --git a/ChangeLog b/ChangeLog
index 210a2fc..437a793 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2015-12-23 Siddharth Ravikumar <sravik@bgsu.edu>
+
+	* combox/file.py: updated docstring of all functions. The
+	docstrings are now palatable to sphinx to digest.
+
 2015-12-22 Siddharth Ravikumar <sravik@bgsu.edu>
 
 	* README.rst: removed `contact` section.
diff --git a/combox/file.py b/combox/file.py
index 25e9b79..08f7ccf 100644
--- a/combox/file.py
+++ b/combox/file.py
@@ -28,19 +28,24 @@ from glob import glob
 from combox.config import get_nodedirs
 from combox.log import log_e
 
-def relative_path(p, config, comboxd=True):
-    """Returns the relative path to the `p' w. r. t combox or node directory.
-
-    If `comboxd' is True, the relative path is w. r. t combox
-    directory.
-
-    If `comboxd' is False, the relative path is w. r. t node
-    directory.
 
-    p: path to a directory or file.
-
-    config: a dictionary that contains configuration information about
-    combox.
+def relative_path(p, config, comboxd=True):
+    """Returns the relative path to the `p` w. r. t combox or node directory.
+
+    :param str p:
+        Path to a directory or file.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
+    :param bool comboxd:
+        True if `p` is a path relative to combox directory.
+    :returns:
+        Path relative to combox directory if `comboxd` is `True`,
+        otherwise returns path relative to the node directory.
+    :rtype: str
+    :raises ValueError:
+        If path `p` is not under the combox directory or the node
+        directory.
 
     """
     directory = None
@@ -59,10 +64,19 @@ def relative_path(p, config, comboxd=True):
 
 
 def cb_path(node_path, config):
-    """
-    Returns abs. path of file (in combox dir.) given the node_path.
-    """
+    """Returns absolute path of file/directory under the combox directory.
+
+    :param str node_path:
+        Path to a file/directory under a node directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
+    :returns:
+        Returns the corresponding path to the file/directory under the
+        combox directory.
+    :rtype: str
 
+    """
     if node_path[:-1].endswith('shard'):
         # partition function is used to remove the `.shard.N' from the
         # file name.
@@ -79,15 +93,24 @@ def cb_path(node_path, config):
 
 
 def node_path(cb_path, config, isfile):
-    """Returns abs. path of file (in node dir.) given the cb_path (combox dir. path).
-
-    If cb_path is a file, it returns the path to its shard in the
-    first node directory.
-
-    isfile: True if cb_path is a file.
+    """Returns abs. path of file/directory in node directory.
+
+    :param str cb_path:
+        Path to a file/directory under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
+    :param bool isfile:
+        True if `cb_path` is not a directory.
+    :returns:
+        If `cb_path` is a file, it returns the path to its shard under
+        the first node directory.
+
+        If `cb_path` is a directory, it returns the corresponding path
+        to this directory under the first node directory.
+    :rtype: str
 
     """
-
     if isfile:
         # partition function is used to remove the `.shard.N' from the
         # file name.
@@ -103,12 +126,23 @@ def node_path(cb_path, config, isfile):
 
 
 def node_paths(cb_path, config, isfile):
-    """Returns list of abs. path of file (in node dir.) the cb_path.
+    """Returns a list of abs. paths of a file/directory in node directories.
+
+    :param str cb_path:
+        Path to a file/directory under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
+    :param bool isfile:
+        True if `cb_path` is not a directory.
+    :returns:
+        If `cb_path` is a file, it returns a list of paths to its
+        shards under the node directories.
+
+        If `cb_path` is a directory, it returns a list its
+        corresponding paths under the node directories.
+    :rtype: list
 
-    If cb_path is a file, it returns a list of abs. path names of
-    shards of the file in the node directories.
-
-    isfile: True if cb_path is a file
     """
 
     n_paths = []
@@ -131,12 +165,15 @@ def node_paths(cb_path, config, isfile):
 
 
 def mk_nodedir(directory, config):
-    """
-    Creates directory `directory' inside the nodes.
+    """Creates directory `directory` under all the node directories.
 
-    config: a dictionary containing configuration info about combox.
-    """
+    :param str directory:
+        Path to a directory under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
 
+    """
     nodes = get_nodedirs(config)
 
     rel_path = relative_path(directory, config)
@@ -147,7 +184,12 @@ def mk_nodedir(directory, config):
 
 
 def mk_dir(directory):
-    """Creates directory"""
+    """Creates a directory.
+
+    :param str directory:
+        Path to a directory to create.
+
+    """
     try:
         os.mkdir(directory)
     except OSError, e:
@@ -155,12 +197,15 @@ def mk_dir(directory):
 
 
 def rm_nodedir(directory, config):
-    """
-    Removes directory `directory' inside the nodes.
+    """Removes directory `directory` under all the node directories.
 
-    config: a dictionary containing configuration info about combox.
-    """
+    :param str directory:
+        Path to a directory under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
 
+    """
     nodes = get_nodedirs(config)
 
     rel_path = relative_path(directory, config)
@@ -171,9 +216,10 @@ def rm_nodedir(directory, config):
 
 
 def rm_path(fpath):
-    """Removes fpath.
+    """Removes path `fpath`.
 
-    fpath can be a file or a empty directory.
+    :param str fpath:
+        It can be a file or an empty directory.
     """
     try:
         if path.isfile(fpath):
@@ -185,14 +231,17 @@ def rm_path(fpath):
 
 
 def move_nodedir(src, dest, config):
-    """
-    Moves directory `directory' inside the nodes from old to new location.
+    """Moves directory `src` to `dest`.
 
-    src: old path to the directory
-    dest: new path to the directory
-    config: a dictionary containing configuration info about combox.
-    """
+    :param str src:
+         Old path to the directory.
+    :param str dest:
+         New path to the directory
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
 
+    """
     nodes = get_nodedirs(config)
 
     src_rel_path = relative_path(src, config)
@@ -208,14 +257,15 @@ def move_nodedir(src, dest, config):
 
 
 def rm_shards(fpath, config):
-    """
-    Removes the file shards of `fpath' in the node directories.
+    """Removes the file shards of `fpath` under the node directories.
 
-    fpath: is the path to a file in the combox directory.
+    :param str fpath:
+         Path to file under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
 
-    config: a dictionary containing configuration info about combox.
     """
-
     nodes = get_nodedirs(config)
 
     rel_path = relative_path(fpath, config)
@@ -241,14 +291,18 @@ def move_shards(src, dest, config):
     """Move the shards in node directories.
 
     This function is used when a file is moved to different location
-    inside the combox directory. It moves the shards to the
-    corresponding location in the node directories.
+    inside the combox directory. It moves the shards of the respective
+    file to the new location under the node directories.
 
-    src: old path to the file that was moved.
-    dest: new path to the file that was moved.
-    config: a dictionary containing configuration info about combox.
-    """
+    :param str src:
+        Old path to the file that was moved under the combox directory.
+    :param str dest:
+        New path to the file that was moved under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
 
+    """
     nodes = get_nodedirs(config)
 
     src_rel_path = relative_path(src, config)
@@ -276,9 +330,12 @@ def move_shards(src, dest, config):
 
 def purge_dir(p):
     """
-    Purge everything under the given directory `p'.
+    Purge everything under the given directory `p`.
+
+    Directory `p` itself is not deleted.
 
-    Directory `p' itself is not deleted.
+    :param str p:
+        Path to directory that needs to be purged.
     """
 
     p = path.abspath(p)
@@ -297,12 +354,17 @@ def purge_dir(p):
 
 
 def split_data(data, n):
-    """Split data into `n' parts and return them as an array.
+    """Split `data` into `n` parts and return them as a list.
 
-    data: Stream of bytes or string
-    n: Number of parts the file has to be split.
-    """
+    :param str data:
+        Stream of bytes or string.
+    :param int n:
+        Number of parts the `data` has to be split.
+    :returns:
+        List of strings -- the `data` divided into `n` parts.
+    :rtype: list
 
+    """
     d_parts = []
     # File size in bytes.
     data_size = len(data)
@@ -327,12 +389,16 @@ def split_data(data, n):
 
 
 def glue_data(d_parts):
-    """Glue different parts of the data to one.
+    """Glue different parts of the `data` into a single whole.
 
-    d_parts: Array containing different parts of the data. Each part
-    is a sequence of bytes.
-    """
+    :param list d_parts:
+        List containing different parts of the `data`. Each part is a
+        sequence of bytes.
+    :returns:
+        The `data` glued into a single whole.
+    :rtype: str
 
+    """
     data = ''
     for part in d_parts:
         data += part
@@ -341,9 +407,14 @@ def glue_data(d_parts):
 
 
 def read_file(filename):
-    """Read file and return it as a string.
+    """Read file `filename` and return it as a string.
+
+    :param str filename:
+        Absolute pathname of the file.
+    :returns:
+        Content of file `filename` as a string.
+    :rtype: str
 
-    filename: Absolute pathname of the file.
     """
     file_ = None
     content = ''
@@ -360,8 +431,17 @@ def hash_file(filename, file_content=None):
 
     Returns the hexdigest of the file content's hash.
 
-    filename: Absolute pathname of the file.
-    file_content: If not None, hash of file_content is returned.
+    :param str filename:
+        Absolute pathname of the file.
+    :param str file_content:
+        If not ``None``, SHA512 hash of `file_content` is returned.
+    :returns:
+        If `file_content` is ``None``, returns the SHA512 hash of
+        contents of file `filename`.
+
+        If `file_content` is not ``None``, returns the SHA512 hash of
+        `file_content`.
+    :rtype: str
     """
 
     if not file_content:
@@ -371,10 +451,13 @@ def hash_file(filename, file_content=None):
 
 
 def write_file(filename, filecontent):
-    """Write `filecontent' to `filename'.
+    """Write `filecontent` to `filename`.
+
+    :param str filename:
+        Absolute pathname of the file.
+    :param str filecontent:
+        Data to write to `filename`.
 
-    filename: Absolute pathname of the file.
-    filecontent: String/bytstream to write to filename.
     """
     file_ = None
     try:
@@ -385,15 +468,18 @@ def write_file(filename, filecontent):
         log_e("Error creating and writing content to %s" % filename)
         exit(1)
 
+
 def write_shards(shards, directories, shard_basename):
-    """Write shards to respective files respective files.
+    """Write shards to node directories.
 
-    shard: list of strings (ciphers or data).
+    :param list shards:
+        List of strings (data).
+    :param list directories:
+        List of paths of node directories.
+    :param str shard_basename:
+        Base name for the shards.
 
-    directories: absolute path of directories to which it shards must be written to.
-    shard_basename: base name of the shard.
     """
-
     shard_no = 0
     for directory in directories:
         # partial filename of the shard
@@ -402,13 +488,20 @@ def write_shards(shards, directories, shard_basename):
         write_file(shard_name, shards[shard_no])
         shard_no += 1
 
+
 def read_shards(directories, shard_basename):
-    """Read the shards from directory and return it as a list.
+    """Read the shards of a file from node directories and return it as a list.
 
-    directories: absolute path of directories from which to read the shards.
-    shard_basename: base name of the shard.
-    """
+    :param list directories:
+        List of paths of node directories from which to read the
+        shards.
+    :param str shard_basename:
+        Base name for the shards; the canonical file name.
+    :returns:
+        List of contents of the shards of the file with basename
+        `shard_basename`.
 
+    """
     # get the names of the file shards
     file_shards = []
     for directory in directories:
@@ -425,11 +518,18 @@ def read_shards(directories, shard_basename):
 
 
 def no_of_shards(cb_path, config):
-    """Returns the no. of shards that exists for `cb_path' in node directories.
+    """Returns the no. of shards that exists for `cb_path` under the node directories.
 
-    cb_path: path to file in combox directory.
-    """
+    :param str cb_path:
+        Path to a file under the combox directory.
+    :param dict config:
+        A dictionary that contains configuration information about
+        combox.
+    :returns:
+        The number of shards that exists for the file `cb_path`.
+    :rtype: int
 
+    """
     no_shards_there = 0
     shard_paths = node_paths(cb_path, config, isfile=True)