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

47
whipper/extern/freedb.py vendored
View File

@@ -18,21 +18,23 @@
def digit_sum(i):
"""returns the sum of all digits for the given integer"""
"""Return the sum of all digits for the given integer."""
return sum(map(int, str(i)))
class DiscID:
def __init__(self, offsets, total_length, track_count, playable_length):
"""offsets is a list of track offsets, in CD frames
total_length is the total length of the disc, in seconds
track_count is the total number of tracks on the disc
playable_length is the playable length of the disc, in seconds
"""
Init DiscID.
the first three items are for generating the hex disc ID itself
while the last is for performing queries"""
:param offsets: list of track offsets, in CD frames
:param total_length: total length of the disc, in seconds
:param track_count: total number of tracks on the disc
:param playable_length: playable length of the disc, in seconds
The first three items are for generating the hex disc ID itself
while the last is for performing queries.
"""
assert(len(offsets) == track_count)
for o in offsets:
assert(o >= 0)
@@ -61,16 +63,15 @@ class DiscID:
def perform_lookup(disc_id, freedb_server, freedb_port):
"""performs a web-based lookup using a DiscID
on the given freedb_server string and freedb_int port
iterates over a list of MetaData objects per successful match, like:
[track1, track2, ...], [track1, track2, ...], ...
may raise HTTPError if an error occurs querying the server
or ValueError if the server returns invalid data
"""
Perform a web-based lookup using a DiscID on the given server and port.
Iterate over a list of MetaData objects per successful match, like:
``[track1, track2, ...], [track1, track2, ...], ...``
:raises HTTPError: if an error occurs querying the server
:raises ValueError: if the server returns invalid data
"""
import re
from time import sleep
@@ -154,8 +155,18 @@ def perform_lookup(disc_id, freedb_server, freedb_port):
def freedb_command(freedb_server, freedb_port, cmd, *args):
"""given a freedb_server string, freedb_port int,
command string and argument strings, yields a list of strings"""
"""
Generate and perform a query against FreeDB using the given command.
Yields a list of Unicode strings.
:param freedb_server: URL of FreeDB server to be queried
:type freedb_server: str
:param freedb_port: port number of FreeDB server to be queried
:type freedb_port: int
:param cmd: CDDB command
:type cmd: str
"""
from urllib.error import URLError
from urllib.request import urlopen

89
whipper/extern/task/task.py vendored
View File

@@ -27,9 +27,7 @@ logger = logging.getLogger(__name__)
class TaskException(Exception):
"""
I wrap an exception that happened during task execution.
"""
"""Wrap an exception that happened during task execution."""
exception = None # original exception
@@ -44,6 +42,7 @@ class TaskException(Exception):
def _getExceptionMessage(exception, frame=-1, filename=None):
"""
Return a short message based on an exception, useful for debugging.
Tries to find where the exception was triggered.
"""
import traceback
@@ -69,9 +68,7 @@ def _getExceptionMessage(exception, frame=-1, filename=None):
class LogStub:
"""
I am a stub for a log interface.
"""
"""Stub for a log interface."""
@staticmethod
def log(message, *args):
@@ -88,18 +85,20 @@ class LogStub:
class Task(LogStub):
"""
I wrap a task in an asynchronous interface.
I can be listened to for starting, stopping, description changes
Wrap a task in an asynchronous interface.
Can be listened to for starting, stopping, description changes
and progress updates.
I communicate an error by setting self.exception to an exception and
stopping myself from running.
The listener can then handle the Task.exception.
:cvar description: what am I doing
:cvar exception: set if an exception happened during the task
execution. Will be raised through run() at the end.
:cvar description: what am I doing
:cvar exception: set if an exception happened during the task
execution. Will be raised through ``run()`` at the end
"""
logCategory = 'Task'
description = 'I am doing something.'
@@ -126,7 +125,7 @@ class Task(LogStub):
using those methods.
If start doesn't raise an exception, the task should run until
complete, or setException and stop().
complete, or ``setException()`` and ``stop()``.
"""
self.debug('starting')
self.setProgress(self.progress)
@@ -137,6 +136,7 @@ class Task(LogStub):
def stop(self):
"""
Stop the task.
Also resets the runner on the task.
Subclasses should chain up to me at the end.
@@ -160,6 +160,7 @@ class Task(LogStub):
def setProgress(self, value):
"""
Notify about progress changes bigger than the increment.
Called by subclass implementations as the task progresses.
"""
if (value - self.progress > self.increment or
@@ -177,8 +178,9 @@ class Task(LogStub):
# FIXME: unify?
def setExceptionAndTraceback(self, exception):
"""
Call this to set a synthetically created exception (and not one
that was actually raised and caught)
Call this to set a synthetically created exception.
Not one that was actually raised and caught.
"""
import traceback
@@ -201,9 +203,7 @@ class Task(LogStub):
setAndRaiseException = setExceptionAndTraceback
def setException(self, exception):
"""
Call this to set a caught exception on the task.
"""
"""Call this to set a caught exception on the task."""
import traceback
self.exception = exception
@@ -244,35 +244,36 @@ class Task(LogStub):
# FIXME: should this become a real interface, like in zope ?
class ITaskListener:
"""
I am an interface for objects listening to tasks.
"""
"""An interface for objects listening to tasks."""
# listener callbacks
def progressed(self, task, value):
"""
Implement me to be informed about progress.
:type value: float
:param task: a task
:type task: Task
:param value: progress, from 0.0 to 1.0
:type value: float
"""
def described(self, task, description):
"""
Implement me to be informed about description changes.
:type description: str
:param task: a task
:type task: Task
:param description: description
:type description: str
"""
def started(self, task):
"""
Implement me to be informed about the task starting.
"""
"""Implement me to be informed about the task starting."""
def stopped(self, task):
"""
Implement me to be informed about the task stopping.
If the task had an error, task.exception will be set.
"""
@@ -297,8 +298,8 @@ class BaseMultiTask(Task, ITaskListener):
"""
I perform multiple tasks.
:ivar tasks: the tasks to run
:type tasks: list of :any:`Task`
:cvar tasks: the tasks to run
:vartype tasks: list(Task)
"""
description = 'Doing various tasks'
@@ -322,7 +323,7 @@ class BaseMultiTask(Task, ITaskListener):
"""
Start tasks.
Tasks can still be added while running. For example,
Tasks can still be added while running. For example,
a first task can determine how many additional tasks to run.
"""
Task.start(self, runner)
@@ -335,9 +336,7 @@ class BaseMultiTask(Task, ITaskListener):
self.next()
def next(self):
"""
Start the next task.
"""
"""Start the next task."""
try:
# start next task
task = self.tasks[self._task]
@@ -364,9 +363,10 @@ class BaseMultiTask(Task, ITaskListener):
def progressed(self, task, value):
pass
def stopped(self, task):
def stopped(self, task): # noqa: D401
"""
Subclasses should chain up to me at the end of their implementation.
They should fall through to chaining up if there is an exception.
"""
self.debug('BaseMultiTask.stopped: task %r (%d of %d)',
@@ -391,9 +391,11 @@ class BaseMultiTask(Task, ITaskListener):
class MultiSeparateTask(BaseMultiTask):
"""
I perform multiple tasks.
I track progress of each individual task, going back to 0 for each task.
Perform multiple tasks.
Track progress of each individual task, going back to 0 for each task.
"""
description = 'Doing various tasks separately'
def start(self, runner):
@@ -417,8 +419,9 @@ class MultiSeparateTask(BaseMultiTask):
class MultiCombinedTask(BaseMultiTask):
"""
I perform multiple tasks.
I track progress as a combined progress on all tasks on task granularity.
Perform multiple tasks.
Track progress as a combined progress on all tasks on task granularity.
"""
description = 'Doing various tasks combined'
@@ -436,16 +439,18 @@ class MultiCombinedTask(BaseMultiTask):
class TaskRunner(LogStub):
"""
I am a base class for task runners.
Base class for task runners.
Task runners should be reusable.
"""
logCategory = 'TaskRunner'
def run(self, task):
"""
Run the given task.
:type task: Task
:type task: Task
"""
raise NotImplementedError
@@ -456,16 +461,16 @@ class TaskRunner(LogStub):
Subclasses should implement this.
:type delta: float
:param delta: time in the future to schedule call for, in seconds.
:type delta: float
:param callable_task: a task
:type callable_task: Task
"""
raise NotImplementedError
class SyncRunner(TaskRunner, ITaskListener):
"""
I run the task synchronously in a GObject MainLoop.
"""
"""Run the task synchronously in a GObject MainLoop."""
def __init__(self, verbose=True):
self._verbose = verbose