Improve docstrings

Signed-off-by: JoeLametta <[email protected]>

whipper/command/basecommand.py

@@ -29,25 +29,28 @@ class BaseCommand:
     """
     Register and handle whipper command arguments with ArgumentParser.
 
-    Register arguments by overriding `add_arguments()` and modifying
-    `self.parser`. Option defaults are read from the dot-separated
-    `prog_name` section of the config file (e.g., 'whipper cd rip'
-    options are read from '[whipper.cd.rip]'). Runs
-    `argparse.parse_args()` then calls `handle_arguments()`.
+    Register arguments by overriding ``add_arguments()`` and modifying
+    ``self.parser``. Option defaults are read from the dot-separated
+    ``prog_name`` section of the config file (e.g., ``whipper cd rip``
+    options are read from ``[whipper.cd.rip]``). Runs
+    ``argparse.parse_args()`` then calls ``handle_arguments()``.
 
-    Provides self.epilog() formatting command for argparse.
+    Provides ``self.epilog()`` formatting command for argparse.
 
-    device_option = True adds -d / --device option to current command
-    no_add_help = True removes -h / --help option from current command
+    Overriding ``formatter_class`` sets the argparse formatter class.
 
-    Overriding formatter_class sets the argparse formatter class.
-
-    If the 'subcommands' dictionary is set, __init__ searches the
-    arguments for subcommands.keys() and instantiates the class
+    If the ``subcommands`` dictionary is set, ``__init__`` searches the
+    arguments for ``subcommands.keys()`` and instantiates the class
     implementing the subcommand as self.cmd, passing all non-understood
     arguments, the current options namespace, and the full command path
     name.
+
+    :cvar device_option: if set to True adds ``-d`` / ``--device``
+                         option to current command
+    :cvar no_add_help: if set to True removes ``-h`` ``--help``
+                       option from current command
     """
+
     device_option = False
     no_add_help = False  # for rip.main.Whipper
     formatter_class = argparse.RawDescriptionHelpFormatter

whipper/common/accurip.py

@@ -42,8 +42,7 @@ class EntryNotFound(Exception):
 
 class _AccurateRipResponse(object):
     """
-    An AccurateRip response contains a collection of metadata identifying a
-    particular digital audio compact disc.
+    An AR resp. contains a collection of metadata identifying a specific disc.
 
     For disc level metadata it contains the track count, two internal disc
     IDs, and the CDDB disc ID.
@@ -54,9 +53,12 @@ class _AccurateRipResponse(object):
 
     The response is stored as a packed binary structure.
     """
+
     def __init__(self, data):
         """
-        The checksums and confidences arrays are indexed by relative track
+        Init _AccurateRipResponse.
+
+        Checksums and confidences arrays are indexed by relative track
         position, so track 1 will have array index 0, track 2 will have array
         index 1, and so forth. HTOA and other hidden tracks are not included.
         """
@@ -97,12 +99,14 @@ def _split_responses(raw_entry):
 
 def calculate_checksums(track_paths):
     """
-    Return ARv1 and ARv2 checksums as two arrays of character strings in a
-    dictionary: {'v1': ['deadbeef', ...], 'v2': [...]}
-
-    Return None instead of checksum string for unchecksummable tracks.
+    Calculate AccurateRip checksums for the given tracks.
 
     HTOA checksums are not included in the database and are not calculated.
+
+    :returns: ARv1 and ARv2 checksums as two arrays of character strings in a
+              dictionary: ``{'v1': ['deadbeef', ...], 'v2': [...]}``
+              or None instead of checksum string for unchecksummable tracks.
+    :rtype: dict(string, list()) or None
     """
     track_count = len(track_paths)
     v1_checksums = []
@@ -161,9 +165,10 @@ def _save_entry(raw_entry, path):
 def get_db_entry(path):
     """
     Retrieve cached AccurateRip disc entry as array of _AccurateRipResponses.
+
     Downloads entry from accuraterip.com on cache fault.
 
-    `path' is in the format of the output of table.accuraterip_path().
+    ``path`` is in the format of the output of ``table.accuraterip_path()``.
     """
     cached_path = join(_CACHE_DIR, path)
     if exists(cached_path):
@@ -191,11 +196,11 @@ def _assign_checksums_and_confidences(tracks, checksums, responses):
 
 def _match_responses(tracks, responses):
     """
-    Match and save track accuraterip response checksums against
-    all non-hidden tracks.
+    Match and save track AR response checksums against all non-hidden tracks.
 
-    Returns True if every track has a match for every entry for either
-    AccurateRip version.
+    :returns: True if every track has a match for every entry for either
+              AccurateRip version, False otherwise.
+    :rtype: bool
     """
     for r in responses:
         for i, track in enumerate(tracks):
@@ -218,7 +223,8 @@ def _match_responses(tracks, responses):
 def verify_result(result, responses, checksums):
     """
     Verify track AccurateRip checksums against database responses.
-    Stores track checksums and database values on result.
+
+    Store track checksums and database values on result.
     """
     if not (result and responses and checksums):
         return False
@@ -233,9 +239,7 @@ def verify_result(result, responses, checksums):
 
 
 def print_report(result):
-    """
-    Print AccurateRip verification results.
-    """
+    """Print AccurateRip verification results."""
     for _, track in enumerate(result.tracks):
         status = 'rip NOT accurate'
         conf = '(not found)'

whipper/common/cache.py

@@ -45,6 +45,7 @@ class Persister:
     def __init__(self, path=None, default=None):
         """
         If path is not given, the object will not be persisted.
+
         This allows code to transparently deal with both persisted and
         non-persisted objects, since the persist method will just end up
         doing nothing.
@@ -56,8 +57,7 @@ def __init__(self, path=None, default=None):
 
     def persist(self, obj=None):
         """
-        Persist the given object, if we have a persistence path and the
-        object changed.
+        Persist the given obj if we have a persist. path and the obj changed.
 
         If object is not given, re-persist our object, always.
         If object is given, only persist if it was changed.
@@ -116,9 +116,7 @@ def delete(self):
 
 
 class PersistedCache:
-    """
-    I wrap a directory of persisted objects.
-    """
+    """Wrap a directory of persisted objects."""
 
     path = None
 
@@ -134,9 +132,7 @@ def _getPath(self, key):
         return os.path.join(self.path, '%s.pickle' % key)
 
     def get(self, key):
-        """
-        Returns the persister for the given key.
-        """
+        """Return the persister for the given key."""
         persister = Persister(self._getPath(key))
         if persister.object:
             if hasattr(persister.object, 'instanceVersion'):
@@ -159,8 +155,9 @@ def __init__(self, path=None):
 
     def getRipResult(self, cddbdiscid, create=True):
         """
-        Retrieve the persistable RipResult either from our cache (from a
-        previous, possibly aborted rip), or return a new one.
+        Get the persistable RipResult either from our cache or ret. a new one.
+
+        The cached RipResult may come from an aborted rip.
 
         :rtype: Persistable for result.RipResult
         """
@@ -188,9 +185,8 @@ def getIds(self):
 
 
 class TableCache:
-
     """
-    I read and write entries to and from the cache of tables.
+    Read and write entries to and from the cache of tables.
 
     If no path is specified, the cache will write to the current cache
     directory and read from all possible cache directories (to allow for

whipper/common/common.py

@@ -39,28 +39,27 @@
 
 
 class EjectError(SystemError):
-    """
-    Possibly ejects the drive in command.main.
-    """
+    """Possibly eject the drive in command.main."""
 
     def __init__(self, device, *args):
         """
-        args is a tuple used by BaseException.__str__
-        device is the device path to eject
+        Init EjectError.
+
+        :param args: a tuple used by ``BaseException.__str__``
+        :param device: device path to eject
         """
         self.args = args
         self.device = device
 
 
 def msfToFrames(msf):
     """
-    Converts a string value in MM:SS:FF to frames.
+    Convert a string value in MM:SS:FF to frames.
 
     :param msf: the MM:SS:FF value to convert
-    :type  msf: str
-
-    :rtype:   int
+    :type msf: str
     :returns: number of frames
+    :rtype: int
     """
     if ':' not in msf:
         return int(msf)
@@ -97,21 +96,19 @@ def framesToHMSF(frames):
 
 def formatTime(seconds, fractional=3):
     """
-    Nicely format time in a human-readable format, like
-    HH:MM:SS.mmm
+    Nicely format time in a human-readable format, like HH:MM:SS.mmm.
 
     If fractional is zero, no seconds will be shown.
     If it is greater than 0, we will show seconds and fractions of seconds.
     As a side consequence, there is no way to show seconds without fractions.
 
-    :param seconds:    the time in seconds to format.
-    :type  seconds:    int or float
+    :param seconds: the time in seconds to format
+    :type seconds: int or float
     :param fractional: how many digits to show for the fractional part of
-                       seconds.
-    :type  fractional: int
-
+                       seconds
+    :type fractional: int
+    :returns: a nicely formatted time string
     :rtype: string
-    :returns: a nicely formatted time string.
     """
     chunks = []
 
@@ -149,16 +146,13 @@ class EmptyError(Exception):
 
 
 class MissingFrames(Exception):
-    """
-    Less frames decoded than expected.
-    """
+    """Less frames decoded than expected."""
+
     pass
 
 
 def truncate_filename(path):
-    """
-    Truncate filename to the max. len. allowed by the path's filesystem
-    """
+    """Truncate filename to the max. len. allowed by the path's filesystem."""
     p, f = os.path.split(os.path.normpath(path))
     f, e = os.path.splitext(f)
     # Get the filename length limit in bytes
@@ -172,7 +166,8 @@ def truncate_filename(path):
 def shrinkPath(path):
     """
     Shrink a full path to a shorter version.
-    Used to handle ENAMETOOLONG
+
+    Used to handle ``ENAMETOOLONG``.
     """
     parts = list(os.path.split(path))
     length = len(parts[-1])
@@ -204,14 +199,15 @@ def shrinkPath(path):
 def getRealPath(refPath, filePath):
     """
     Translate a .cue or .toc's FILE argument to an existing path.
+
     Does Windows path translation.
-    Will look for the given file name, but with .flac and .wav as extensions.
 
-    :param refPath:  path to the file from which the track is referenced;
-                     for example, path to the .cue file in the same directory
-    :type  refPath:  unicode
+    Will look for the given file name, but with .flac and .wav as extensions.
 
-    :type  filePath: unicode
+    :param refPath: path to the file from which the track is referenced;
+                    for example, path to the .cue file in the same directory
+    :type refPath: unicode
+    :type filePath: unicode
     """
     assert isinstance(filePath, unicode), "%r is not unicode" % filePath
 
@@ -258,10 +254,9 @@ def getRealPath(refPath, filePath):
 
 def getRelativePath(targetPath, collectionPath):
     """
-    Get a relative path from the directory of collectionPath to
-    targetPath.
+    Get a relative path from the directory of collectionPath to targetPath.
 
-    Used to determine the path to use in .cue/.m3u files
+    Used to determine the path to use in .cue/.m3u files.
     """
     logger.debug('getRelativePath: target %r, collection %r',
                  targetPath, collectionPath)
@@ -280,9 +275,7 @@ def getRelativePath(targetPath, collectionPath):
 
 
 def validate_template(template, kind):
-    """
-    Raise exception if disc/track template includes invalid variables
-    """
+    """Raise exception if disc/track template includes invalid variables."""
     if kind == 'disc':
         matches = re.findall(r'%[^ARSXdrxy]', template)
     elif kind == 'track':
@@ -294,20 +287,22 @@ def validate_template(template, kind):
 
 class VersionGetter(object):
     """
-    I get the version of a program by looking for it in command output
-    according to a regexp.
+    Get the version of a program.
+
+    It is extracted by looking for it in command output according to a RegEX.
     """
 
     def __init__(self, dependency, args, regexp, expander):
         """
+        Init VersionGetter.
+
         :param dependency: name of the dependency providing the program
-        :param args:       the arguments to invoke to show the version
-        :type  args:       list of str
-        :param regexp:     the regular expression to get the version
-        :param expander:   the expansion string for the version using the
-                           regexp group dict
+        :param args: the arguments to invoke to show the version
+        :type args: list(str)
+        :param regexp: the regular expression to get the version
+        :param expander: the expansion string for the version using the
+                         regexp group dict
         """
-
         self._dep = dependency
         self._args = args
         self._regexp = regexp

whipper/common/config.py

@@ -95,9 +95,7 @@ def setReadOffset(self, vendor, model, release, offset):
         self.write()
 
     def getReadOffset(self, vendor, model, release):
-        """
-        Get a read offset for the given drive.
-        """
+        """Get a read offset for the given drive."""
         section = self._findDriveSection(vendor, model, release)
 
         try: