Subgroup: Task
Class: QgsTask¶
-
class
qgis.core.
QgsTask
¶ Bases:
PyQt5.QtCore.QObject
Abstract base class for long running background tasks. Tasks can be controlled directly, or added to a QgsTaskManager for automatic management.
Derived classes should implement the process they want to execute in the background within the run() method. This method will be called when the task commences (ie via calling run() ).
Long running tasks should periodically check the isCanceled() flag to detect if the task has been canceled via some external event. If this flag is true then the task should clean up and terminate at the earliest possible convenience.
New in version 3.0: Methods
addSubTask
Adds a subtask to this task. blockSignals
canCancel
Returns true if the task can be canceled. cancel
Notifies the task that it should terminate. childEvent
children
connectNotify
customEvent
deleteLater
dependentLayers
Returns the list of layers on which the task depends. description
Returns the task’s description. disconnect
disconnectNotify
dumpObjectInfo
dumpObjectTree
dynamicPropertyNames
event
eventFilter
findChild
findChild(self, Tuple, name: str = ‘’, options: Union[Qt.FindChildOptions, Qt.FindChildOption] = Qt.FindChildrenRecursively) -> QObject findChildren
findChildren(self, Tuple, name: str = ‘’, options: Union[Qt.FindChildOptions, Qt.FindChildOption] = Qt.FindChildrenRecursively) -> List[QObject] finished
If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination). flags
Returns the flags associated with the task. fromFunction
Creates a new QgsTask task from a python function. hold
Places the task on hold. inherits
installEventFilter
isActive
Returns true if the task is active, ie it is not complete and has not been canceled. isCanceled
Will return true if task should terminate ASAP. isSignalConnected
isWidgetType
isWindowType
killTimer
metaObject
moveToThread
objectName
parent
progress
Returns the task’s progress (between 0.0 and 100.0) property
pyqtConfigure
Each keyword argument is either the name of a Qt property or a Qt signal. receivers
removeEventFilter
run
Performs the task’s operation. sender
senderSignalIndex
setDependentLayers
Sets a list of layers on which the task depends. setObjectName
setParent
setProgress
Sets the task’s current progress. setProperty
signalsBlocked
startTimer
status
Returns the current task status. thread
timerEvent
tr
unhold
Releases the task from being held. waitForFinished
Blocks the current thread until the task finishes or a maximum of timeout
milliseconds.Attributes
AllFlags
CanCancel
Complete
OnHold
ParentDependsOnSubTask
Queued
Running
SubTaskIndependent
Terminated
begun
Will be emitted by task to indicate its commencement. destroyed
destroyed(self, QObject = None) [signal] objectNameChanged
objectNameChanged(self, str) [signal] progressChanged
Will be emitted by task when its progress changes. staticMetaObject
statusChanged
Will be emitted by task when its status changes. taskCompleted
Will be emitted by task to indicate its successful completion. taskTerminated
Will be emitted by task if it has terminated for any reason other then completion (e.g., when a task has been canceled or encountered an internal error). -
AllFlags
= 2¶
-
CanCancel
= 2¶
-
Complete
= 3¶
-
class
Flag
¶ Bases:
int
-
class
Flags
¶ Bases:
sip.wrapper
QgsTask.Flags(Union[QgsTask.Flags, QgsTask.Flag]) QgsTask.Flags(QgsTask.Flags)
-
OnHold
= 1¶
-
ParentDependsOnSubTask
= 1¶
-
Queued
= 0¶
-
Running
= 2¶
-
class
SubTaskDependency
¶ Bases:
int
-
SubTaskIndependent
= 0¶
-
class
TaskStatus
¶ Bases:
int
-
Terminated
= 4¶
-
addSubTask
(self, subTask: QgsTask, dependencies: object = QgsTaskList(), subTaskDependency: QgsTask.SubTaskDependency = QgsTask.SubTaskIndependent)¶ Adds a subtask to this task.
Subtasks allow a single task to be created which consists of multiple smaller tasks. Subtasks are not visible or indepedently controllable by users. Ownership of the subtask is transferred. Subtasks can have an optional list of dependent tasks, which must be completed before the subtask can begin. By default subtasks are considered independent of the parent task, ie they can be run either before, after, or at the same time as the parent task. This behavior can be overridden through the subTaskDependency argument. Note that subtasks should NEVER be dependent on their parent task, and violating this constraint will prevent the task from completing successfully.
The parent task must be added to a QgsTaskManager for subtasks to be utilized. Subtasks should not be added manually to a QgsTaskManager, rather, only the parent task should be added to the manager.
Subtasks can be nested, ie a subtask can legally be a parent task itself with its own set of subtasks.
-
begun
¶ Will be emitted by task to indicate its commencement.
Note
derived classes should not emit this signal directly, it will automatically be emitted when the task begins [signal]
-
canCancel
(self) → bool¶ Returns true if the task can be canceled.
-
cancel
(self)¶ Notifies the task that it should terminate. Calling this is not guaranteed to immediately end the task, rather it sets the isCanceled() flag which task subclasses can check and terminate their operations at an appropriate time. Any subtasks owned by this task will also be canceled. Derived classes must ensure that the base class implementation is called from any overridden version.
See also
-
childEvent
()¶
-
connectNotify
()¶
-
customEvent
()¶
-
dependentLayers
(self) → List[QgsMapLayer]¶ Returns the list of layers on which the task depends. The task will automatically be canceled if any of these layers are about to be removed.
See also
-
description
(self) → str¶ Returns the task’s description.
-
disconnectNotify
()¶
-
finished
(self, result: bool)¶ If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination). The result argument reflects whether the task was successfully completed or not. This method is always called from the main thread, so it is safe to create widgets and perform other operations which require the main thread. However, the GUI will be blocked for the duration of this method so tasks should avoid performing any lengthy operations here.
-
flags
(self) → QgsTask.Flags¶ Returns the flags associated with the task.
-
static
fromFunction
(description, function, *args, on_finished=None, flags=2, **kwargs)¶ Creates a new QgsTask task from a python function.
Example:
- def calculate(task):
- # pretend this is some complex maths and stuff we want # to run in the background return 5*6
- def calculation_finished(exception, value=None):
- if not exception:
- iface.messageBar().pushMessage(
- ‘the magic number is {}’.format(value))
- else:
- iface.messageBar().pushMessage(
- str(exception))
- task = QgsTask.fromFunction(‘my task’, calculate,
- on_finished=calculation_finished)
QgsApplication.taskManager().addTask(task)
-
hold
(self)¶ Places the task on hold. If the task in not queued (ie it is already running or has finished) then calling this has no effect. Calling this method only has an effect for tasks which are managed by a QgsTaskManager.
See also
-
isActive
(self) → bool¶ Returns true if the task is active, ie it is not complete and has not been canceled.
-
isCanceled
(self) → bool¶ Will return true if task should terminate ASAP. If the task reports the CanCancel flag, then derived classes’ run() methods should periodically check this and terminate in a safe manner.
-
isSignalConnected
()¶
-
progress
(self) → float¶ Returns the task’s progress (between 0.0 and 100.0)
-
progressChanged
¶ Will be emitted by task when its progress changes.
Parameters: progress – percent of progress, from 0.0 - 100.0 Note
derived classes should not emit this signal directly, instead they should call setProgress() [signal]
-
receivers
()¶
-
run
(self) → bool¶ Performs the task’s operation. This method will be called when the task commences (ie via calling start() ), and subclasses should implement the operation they wish to perform in the background within this method.
A task must return a boolean value to indicate whether the task was completed successfully or terminated before completion.
-
sender
()¶
-
senderSignalIndex
()¶
-
setDependentLayers
(self, dependentLayers: Iterable[QgsMapLayer])¶ Sets a list of layers on which the task depends. The task will automatically be canceled if any of these layers are about to be removed.
See also
dependentLayerIds()
-
setProgress
(self, progress: float)¶ Sets the task’s current progress. The derived class should call this method whenever the task wants to update its progress. Calling will automatically emit the progressChanged signal.
Parameters: progress – percent of progress, from 0.0 - 100.0
-
status
(self) → QgsTask.TaskStatus¶ Returns the current task status.
-
statusChanged
¶ Will be emitted by task when its status changes.
Parameters: status – new task status Note
derived classes should not emit this signal directly, it will automatically be emitted [signal]
-
taskCompleted
¶ Will be emitted by task to indicate its successful completion.
Note
derived classes should not emit this signal directly, it will automatically be emitted [signal]
-
taskTerminated
¶ Will be emitted by task if it has terminated for any reason other then completion (e.g., when a task has been canceled or encountered an internal error).
Note
derived classes should not emit this signal directly, it will automatically be emitted [signal]
-
timerEvent
()¶
-
unhold
(self)¶ Releases the task from being held. For tasks managed by a QgsTaskManager calling this will re-add them to the queue. If the task in not currently being held then calling this has no effect.
See also
-
waitForFinished
(self, timeout: int = 30000) → bool¶ Blocks the current thread until the task finishes or a maximum of
timeout
milliseconds. Iftimeout
is0
the thread will be blocked forever. In case of a timeout, the task will still be running. In case the task already is finished, the method will return immediately while returningtrue
.The result will be false if the wait timed out and true in any other case.
-