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

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