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'