benya/whipper-gui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve docstrings

Browse Source 
Signed-off-by: JoeLametta <JoeLametta@users.noreply.github.com>
This commit is contained in:
JoeLametta
2019-03-20 21:12:56 +00:00
parent 3b269e7a3b
commit e56c636fd3
26 changed files with 583 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
whipper/program/cdparanoia.py
View File

@@ -37,13 +37,10 @@ logger = logging.getLogger(__name__)
class FileSizeError(Exception):
"""The given path does not have the expected size."""
message = None
"""
The given path does not have the expected size.
"""
def __init__(self, path, message):
self.args = (path, message)
self.path = path
@@ -51,9 +48,7 @@ class FileSizeError(Exception):
class ReturnCodeError(Exception):
"""
The program had a non-zero return code.
"""
"""The program had a non-zero return code."""
def __init__(self, returncode):
self.args = (returncode, )
@@ -88,10 +83,12 @@ class ProgressParser:
def __init__(self, start, stop):
"""
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive)
:type stop: int
Init ProgressParser.
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive)
:type stop: int
"""
self.start = start
self.stop = stop
@@ -102,9 +99,7 @@ class ProgressParser:
self._reads = {} # read count for each sector
def parse(self, line):
"""
Parse a line.
"""
"""Parse a line."""
m = _PROGRESS_RE.search(line)
if m:
# code = int(m.group('code'))
@@ -185,6 +180,7 @@ class ProgressParser:
def getTrackQuality(self):
"""
Each frame gets read twice.
More than two reads for a frame reduce track quality.
"""
frames = self.stop - self.start + 1 # + 1 since stop is inclusive
@@ -203,9 +199,7 @@ class ProgressParser:
class ReadTrackTask(task.Task):
"""
I am a task that reads a track using cdparanoia.
"""
"""Task that reads a track using cdparanoia."""
description = "Reading track"
quality = None # set at end of reading
@@ -219,22 +213,22 @@ class ReadTrackTask(task.Task):
"""
Read the given track.
:param path: where to store the ripped track
:type path: str
:param table: table of contents of CD
:type table: table.Table
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive); >= start
:type stop: int
:param path: where to store the ripped track
:type path: str
:param table: table of contents of CD
:type table: table.Table
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive); >= start
:type stop: int
:param offset: read offset, in samples
:type offset: int
:type offset: int
:param device: the device to rip from
:type device: str
:type device: str
:param action: a string representing the action; e.g. Read/Verify
:type action: str
:param what: a string representing what's being read; e.g. Track
:type what: str
:type action: str
:param what: a string representing what's being read; e.g. Track
:type what: str
"""
assert isinstance(path, str), "%r is not str" % path
@@ -395,22 +389,23 @@ class ReadTrackTask(task.Task):
class ReadVerifyTrackTask(task.MultiSeparateTask):
"""
I am a task that reads and verifies a track using cdparanoia.
I also encode the track.
Task that reads and verifies a track using cdparanoia.
It also encodes the track.
The path where the file is stored can be changed if necessary, for
example if the file name is too long.
:cvar checksum: the checksum of the track; set if they match.
:cvar testchecksum: the test checksum of the track.
:cvar copychecksum: the copy checksum of the track.
:cvar testspeed: the test speed of the track, as a multiple of
track duration.
:cvar copyspeed: the copy speed of the track, as a multiple of
track duration.
:cvar testduration: the test duration of the track, in seconds.
:cvar copyduration: the copy duration of the track, in seconds.
:cvar peak: the peak level of the track
:cvar checksum: the checksum of the track; set if they match
:cvar testchecksum: the test checksum of the track
:cvar copychecksum: the copy checksum of the track
:cvar testspeed: the test speed of the track, as a multiple of
track duration
:cvar copyspeed: the copy speed of the track, as a multiple of
track duration
:cvar testduration: the test duration of the track, in seconds
:cvar copyduration: the copy duration of the track, in seconds
:cvar peak: the peak level of the track
"""
checksum = None
@@ -429,20 +424,22 @@ class ReadVerifyTrackTask(task.MultiSeparateTask):
def __init__(self, path, table, start, stop, overread, offset=0,
device=None, taglist=None, what="track", coverArtPath=None):
"""
:param path: where to store the ripped track
:type path: str
:param table: table of contents of CD
:type table: table.Table
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive)
:type stop: int
:param offset: read offset, in samples
:type offset: int
:param device: the device to rip from
:type device: str
Init ReadVerifyTrackTask.
:param path: where to store the ripped track
:type path: str
:param table: table of contents of CD
:type table: table.Table
:param start: first frame to rip
:type start: int
:param stop: last frame to rip (inclusive)
:type stop: int
:param offset: read offset, in samples
:type offset: int
:param device: the device to rip from
:type device: str
:param taglist: a dict of tags
:type taglist: dict
:type taglist: dict
"""
task.MultiSeparateTask.__init__(self)

28
whipper/program/cdrdao.py
View File

@@ -59,24 +59,22 @@ class ProgressParser:
class ReadTOCTask(task.Task):
"""
Task that reads the TOC of the disc using cdrdao
"""
"""Task that reads the TOC of the disc using cdrdao."""
description = "Reading TOC"
toc = None
def __init__(self, device, fast_toc=False, toc_path=None):
"""
Read the TOC for 'device'.
Read the TOC for ``device``.
:param device: block device to read TOC from
:type device: str
:param fast_toc: If to use fast-toc cdrdao mode
:type fast_toc: bool
:param toc_path: Where to save TOC if wanted.
:type toc_path: str
:param device: block device to read TOC from
:type device: str
:param fast_toc: whether to use fast-toc cdrdao mode
:type fast_toc: bool
:param toc_path: where to save TOC if wanted
:type toc_path: str
"""
self.device = device
self.fast_toc = fast_toc
self.toc_path = toc_path
@@ -161,9 +159,7 @@ class ReadTOCTask(task.Task):
def DetectCdr(device):
"""
Return whether cdrdao detects a CD-R for 'device'.
"""
"""Whether cdrdao detects a CD-R for ``device``."""
cmd = [CDRDAO, 'disk-info', '-v1', '--device', device]
logger.debug("executing %r", cmd)
p = Popen(cmd, stdout=PIPE, stderr=PIPE)
@@ -171,9 +167,7 @@ def DetectCdr(device):
def version():
"""
Return cdrdao version as a string.
"""
"""Return cdrdao version as a string."""
cdrdao = Popen(CDRDAO, stderr=PIPE)
_, err = cdrdao.communicate()
if cdrdao.returncode != 1:

5
whipper/program/flac.py
View File

@@ -6,8 +6,9 @@ logger = logging.getLogger(__name__)
def encode(infile, outfile):
"""
Encodes infile to outfile, with flac.
Uses '-f' because whipper already creates the file.
Encode infile to outfile, with flac.
Uses ``-f`` because whipper already creates the file.
"""
try:
# TODO: Replace with Popen so that we can catch stderr and write it to

6
whipper/program/sox.py
View File

@@ -9,10 +9,10 @@ SOX = 'sox'
def peak_level(track_path):
"""
Accepts a path to a sox-decodable audio file.
Accept a path to a sox-decodable audio file.
Returns track peak level from sox ('maximum amplitude') as a float.
Returns None on error.
:returns: track peak level from sox ('maximum amplitude')
:rtype: float or None
"""
if not os.path.exists(track_path):
logger.warning("SoX peak detection failed: file not found")

11
whipper/program/soxi.py
View File

@@ -11,17 +11,22 @@ SOXI = 'soxi'
class AudioLengthTask(ctask.PopenTask):
"""
I calculate the length of a track in audio samples.
Calculate the length of a track in audio samples.
:cvar length: length of the decoded audio file, in audio samples.
:cvar length: length of the decoded audio file, in audio samples
:vartype length: int
"""
logCategory = 'AudioLengthTask'
description = 'Getting length of audio track'
length = None
def __init__(self, path):
"""
:type path: str
Init AudioLengthTask.
:param path: path to audio track
:type path: str
"""
assert isinstance(path, str), "%r is not str" % path

13
whipper/program/utils.py
View File

@@ -6,9 +6,7 @@ logger = logging.getLogger(__name__)
def eject_device(device):
"""
Eject the given device.
"""
"""Eject the given device."""
logger.debug("ejecting device %s", device)
try:
# `eject device` prints nothing to stdout
@@ -19,9 +17,7 @@ def eject_device(device):
def load_device(device):
"""
Load the given device.
"""
"""Load the given device."""
logger.debug("loading (eject -t) device %s", device)
try:
# `eject -t device` prints nothing to stdout
@@ -34,8 +30,9 @@ def load_device(device):
def unmount_device(device):
"""
Unmount the given device if it is mounted, as happens with automounted
data tracks.
Unmount the given device if it is mounted.
This usually happens with automounted data tracks.
If the given device is a symlink, the target will be checked.
"""