Convert docstrings to reStructuredText

This commit also includes:

  - whitespace / code formatting fixes
  - slight syntax related changes: except <exception_name>, e -> except <exception_name> as e
  - 3 pointless instructions instances have been rewritten [sorted] (spotted by semi-automatic check)

The unrelated changes shouldn't have any real impact on whipper's behaviour.

setup.py

@@ -13,6 +13,6 @@
     entry_points={
         'console_scripts': [
             'whipper = whipper.command.main:main'
-         ]
+        ]
     }
 )

whipper/command/basecommand.py

@@ -26,8 +26,7 @@
 
 
 class BaseCommand():
-    """
-    A base command class for whipper commands.
+    """A base command class for whipper commands.
 
     Creates an argparse.ArgumentParser.
     Override add_arguments() and handle_arguments() to register
@@ -46,6 +45,7 @@ class BaseCommand():
     arguments, the current options namespace, and the full command path
     name.
     """
+
     device_option = False
     no_add_help = False  # for rip.main.Whipper
     formatter_class = argparse.RawDescriptionHelpFormatter

whipper/command/cd.py

@@ -175,7 +175,7 @@ def do(self):
             try:
                 self.program.result.cdparanoiaDefeatsCache = \
                     self.config.getDefeatsCache(*info)
-            except KeyError, e:
+            except KeyError as e:
                 logger.debug('Got key error: %r' % (e, ))
         self.program.result.artist = self.program.metadata \
             and self.program.metadata.artist \
@@ -414,7 +414,7 @@ def _ripIfNotRipped(number):
                                                   len(self.itable.tracks),
                                                   extra))
                         break
-                    except Exception, e:
+                    except Exception as e:
                         logger.debug('Got exception %r on try %d',
                                      e, tries)
 

whipper/command/debug.py

@@ -118,9 +118,9 @@ class ResultCache(BaseCommand):
     description = summary
 
     subcommands = {
-        'cue':  RCCue,
+        'cue': RCCue,
         'list': RCList,
-        'log':  RCLog,
+        'log': RCLog,
     }
 
 
@@ -291,10 +291,10 @@ class Debug(BaseCommand):
     description = "debug internals"
 
     subcommands = {
-        'checksum':       Checksum,
-        'encode':         Encode,
-        'tag':            Tag,
+        'checksum': Checksum,
+        'encode': Encode,
+        'tag': Tag,
         'musicbrainzngs': MusicBrainzNGS,
-        'resultcache':    ResultCache,
-        'version':        Version,
+        'resultcache': ResultCache,
+        'version': Version,
     }

whipper/command/main.py

@@ -38,20 +38,20 @@ def main():
     try:
         cmd = Whipper(sys.argv[1:], os.path.basename(sys.argv[0]), None)
         ret = cmd.do()
-    except SystemError, e:
+    except SystemError as e:
         sys.stderr.write('whipper: error: %s\n' % e)
         if (type(e) is common.EjectError and
                 cmd.options.eject in ('failure', 'always')):
             eject_device(e.device)
         return 255
-    except RuntimeError, e:
+    except RuntimeError as e:
         print(e)
         return 1
     except KeyboardInterrupt:
         return 2
-    except ImportError, e:
+    except ImportError as e:
         raise
-    except task.TaskException, e:
+    except task.TaskException as e:
         if isinstance(e.exception, ImportError):
             raise ImportError(e.exception)
         elif isinstance(e.exception, common.MissingDependencyException):
@@ -80,11 +80,11 @@ class Whipper(BaseCommand):
     no_add_help = True
     subcommands = {
         'accurip': accurip.AccuRip,
-        'cd':      cd.CD,
-        'debug':   debug.Debug,
-        'drive':   drive.Drive,
-        'offset':  offset.Offset,
-        'image':   image.Image
+        'cd': cd.CD,
+        'debug': debug.Debug,
+        'drive': drive.Drive,
+        'offset': offset.Offset,
+        'image': image.Image
     }
 
     def add_arguments(self):

whipper/command/offset.py

@@ -119,7 +119,7 @@ def match(archecksums, track, responses):
             sys.stdout.write('Trying read offset %d ...\n' % offset)
             try:
                 archecksums = self._arcs(runner, table, 1, offset)
-            except task.TaskException, e:
+            except task.TaskException as e:
 
                 # let MissingDependency fall through
                 if isinstance(e.exception,
@@ -152,7 +152,7 @@ def match(archecksums, track, responses):
                 for track in range(2, (len(table.tracks) + 1) - 1):
                     try:
                         archecksums = self._arcs(runner, table, track, offset)
-                    except task.TaskException, e:
+                    except task.TaskException as e:
                         if isinstance(e.exception, cdparanoia.FileSizeError):
                             sys.stdout.write(
                                 'WARNING: cannot rip with offset %d...\n' %
@@ -195,11 +195,11 @@ def _arcs(self, runner, table, track, offset):
         runner.run(t)
 
         v1 = arc.accuraterip_checksum(
-                path, track, len(table.tracks), wave=True, v2=False
-            )
+            path, track, len(table.tracks), wave=True, v2=False
+        )
         v2 = arc.accuraterip_checksum(
-                path, track, len(table.tracks), wave=True, v2=True
-            )
+            path, track, len(table.tracks), wave=True, v2=True
+        )
 
         os.unlink(path)
         return ("%08x" % v1, "%08x" % v2)

whipper/common/accurip.py

@@ -41,7 +41,8 @@ class EntryNotFound(Exception):
 
 
 class _AccurateRipResponse(object):
-    """
+    """I represent an AccurateRip response with its metadata.
+
     An AccurateRip response contains a collection of metadata identifying a
     particular digital audio compact disc.
 
@@ -52,14 +53,14 @@ class _AccurateRipResponse(object):
     the disc index, which excludes any audio hidden in track pre-gaps (such as
     HTOA).
 
+    The 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.
+
     The response is stored as a packed binary structure.
     """
+
     def __init__(self, data):
-        """
-        The 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.
-        """
         self.num_tracks = struct.unpack("B", data[0])[0]
         self.discId1 = "%08x" % struct.unpack("<L", data[1:5])[0]
         self.discId2 = "%08x" % struct.unpack("<L", data[5:9])[0]
@@ -96,13 +97,17 @@ def _split_responses(raw_entry):
 
 
 def calculate_checksums(track_paths):
-    """
+    """Calculate ARv1 and ARv2 checksums of the given tracks.
+
     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.
 
     HTOA checksums are not included in the database and are not calculated.
+
+    :param track_paths:
+    :type track_paths:
     """
     track_count = len(track_paths)
     v1_checksums = []
@@ -111,23 +116,23 @@ def calculate_checksums(track_paths):
     # This is done sequentially because it is very fast.
     for i, path in enumerate(track_paths):
         v1_sum = accuraterip_checksum(
-            path, i+1, track_count, wave=True, v2=False
+            path, i + 1, track_count, wave=True, v2=False
         )
         if not v1_sum:
             logger.error(
                 'could not calculate AccurateRip v1 checksum for track %d %r' %
-                (i+1, path)
+                (i + 1, path)
             )
             v1_checksums.append(None)
         else:
             v1_checksums.append("%08x" % v1_sum)
         v2_sum = accuraterip_checksum(
-            path, i+1, track_count, wave=True, v2=True
+            path, i + 1, track_count, wave=True, v2=True
         )
         if not v2_sum:
             logger.error(
                 'could not calculate AccurateRip v2 checksum for track %d %r' %
-                (i+1, path)
+                (i + 1, path)
             )
             v2_checksums.append(None)
         else:
@@ -156,19 +161,24 @@ def _save_entry(raw_entry, path):
     # XXX: os.makedirs(exist_ok=True) in py3
     try:
         makedirs(dirname(path))
-    except OSError, e:
+    except OSError as e:
         if e.errno != EEXIST:
             logger.error('could not save entry to %s: %r' % (path, str(e)))
             return
     open(path, 'wb').write(raw_entry)
 
 
 def get_db_entry(path):
-    """
-    Retrieve cached AccurateRip disc entry as array of _AccurateRipResponses.
+    """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().
+
+    :param path:
+    :type path:
     """
     cached_path = join(_CACHE_DIR, path)
     if exists(cached_path):
@@ -195,12 +205,17 @@ 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 AccurateRip response checksums.
+
+    The checksum are matched against all non-hidden tracks.
 
     Returns True if every track has a match for every entry for either
     AccurateRip version.
+
+    :param tracks:
+    :type tracks:
+    :param responses:
+    :type responses:
     """
     for r in responses:
         for i, track in enumerate(tracks):
@@ -222,9 +237,16 @@ def _match_responses(tracks, responses):
 
 
 def verify_result(result, responses, checksums):
-    """
-    Verify track AccurateRip checksums against database responses.
+    """Verify track AccurateRip checksums against database responses.
+
     Stores track checksums and database values on result.
+
+    :param result:
+    :type result:
+    :param responses:
+    :type responses:
+    :param checksums:
+    :type checksums:
     """
     if not (result and responses and checksums):
         return False
@@ -239,8 +261,10 @@ def verify_result(result, responses, checksums):
 
 
 def print_report(result):
-    """
-    Print AccurateRip verification results to stdout.
+    """Print AccurateRip verification results to stdout.
+
+    :param result:
+    :type result:
     """
     for i, track in enumerate(result.tracks):
         status = 'rip NOT accurate'