craftr.core.task

craftr.core.task.task

Task Objects

class Task(abc.ABC)

The raw base class for tasks that represents a logically closed unit of work. It is common to subclass the DefaultTask class instead.

dependencies

A list of direct dependencies of this task.

do_first_actions

A list of actions to perform before any other actions in the task.

do_last_actions

A list of actions to perform after any other actions in the task.

default

Whether the task should be included if no explicit set of tasks is selected for execution. This is True by default for all tasks (but can be overwritten by subclasses).

description

A short description of the task.

group

A name for the group that the task belongs to. Task groups are used to select tasks via common identifiers (e.g. run, compile or debug are generic terms that could apply to a variety of tasks).

always_outdated

A boolean flag that indicates whether the task is always to be considered outdated.

finalized

 | @property
 | finalized() -> bool

True if finalize() was called.

init

 | init() -> None

Called from __init__().

finalize

 | finalize() -> None

Called to finalize the state of the task. Raises a RuntimeError if the task has already been finalized.

get_dependencies

 | get_dependencies() -> t.List['Task']

Return a list of the task's dependencies. This does not not need to include dependencies as they will be taken into account by the executor automatically.

get_actions

 | get_actions() -> t.List['Action']

Return the actions that need to be executed for this task. This does not have to include do_first_actions and do_last_actions as they will be handled separately by the executor.

is_outdated

 | is_outdated() -> bool

Check if the task is outdated and needs to be re-run. This does not have to take into account always_outdated, because the executor can check it separately. The default implementation returns always True.

Tasks should use the Context.metadata_store to read and write previous information about itself.

on_completed

 | on_completed() -> None

Called when the task has finished executing.

depends_on

 | depends_on(*tasks: t.Union[str, 'Task']) -> None

Specify that the task dependends on the specified other tasks. Strings are resolved from the tasks own project.

__call__

 | __call__(closure: Closure) -> 'Task'

Allows the task to be configured using a closure in Craftr DSL land.

DefaultTask Objects

class DefaultTask(Task,  HavingProperties)

This task implementation is what is commonly used to implement custom tasks, as it provides capabilities to automatically deduce dependencies between tasks via property relationships (see HavingProperties). If you use the property of one task to set the value of another, that first task becomes a dependency of the latter.

Furthermore, the type of the property can define how the task's properties are handled in respect to its up-to-date calculation. E.g. if a property is marked as a TaskPropertyType.OutputFile, the task is considered out-of-date if the output file does not exist or if any of the task's input files (marked with TaskPropertyType.InputFile) have been changed since the output file was produced.

finalize

 | finalize() -> None

Called to finalize the task. This is called automatically after the task is configured. Properties are finalized in this call. The subclass gets a chance to set any output properties that are derived other properties.

get_dependencies

 | get_dependencies() -> t.List['Task']

Get all direct dependencies of the task, including those inherited through properties.

is_outdated

 | is_outdated() -> bool

Checks if the task is outdated.

on_completed

 | on_completed() -> None

Called when the task was executed.

craftr.core.task.state

calculate_task_hash

calculate_task_hash(task: 'DefaultTask', hash_algo: str = 'sha1') -> str

Calculates a hash for the task that represents the state of it's inputs (property values and input file contents). That hash is used to determine if the task is up to date with it's previous execution or if it needs to be executed.

Implementation detail: Expects that all important information of a property value is included in it's repr(), and that the repr() is consistent.

craftr.core.task.selector

craftr.core.task.selector.default

DefaultTaskSelector Objects

class DefaultTaskSelector(ITaskSelector)

The default task selector employs the following selector syntax:

[:][subProject:]+[taskName]

If the selector is prefixed with a semi-colon (:), the task path must be exact and relative to the current project. The taskName may refer to an individial task's name or a task group.

Without the : prefix, the path must only match exactly at the end of the path (e.g. a:b matches both tasks with an absolute path foo:a:b and egg:spam:a:b).

craftr.core.task.selector.api

ITaskSelector Objects

@t.runtime_checkable
class ITaskSelector(t.Protocol, metaclass=abc.ABCMeta)

An interface to expand a string into a set of tasks in the context of a project.