Hook Specifications

Hook specifications are the entry-points provided by pytask to change the behavior of the program.

The following sections provide an overview of the different phases while executing the tasks the purpose of the entry-points.

Naming

The names of hooks always start with pytask_ by convention. The following term usually specifies the phase during the execution of tasks if there exist a group of hook specifications.

If you encounter hooks which are suffixed with _protocol, it means that subsequent hooks are allowed to raise exceptions which are handled and stored in a report.

General

_pytask.hookspecs.pytask_add_hooks(pm: PluginManager) → None

Add hook specifications and implementations to the plugin manager.

This hook is the first to be called to let plugins register their hook specifications and implementations.

If you want to register plugins dynamically depending on the configuration, use pytask_post_parse() instead. See _pytask.debugging for an example.

Command Line Interface

_pytask.hookspecs.pytask_extend_command_line_interface(cli: click.Group) → None

Extend the command line interface.

The hook can be used to extend the command line interface either by providing new commands or adding options and arguments to existing commands.

• Add commands via cli.add_command.

• Add options and arguments by extending cli.params or cli.commands["<name>"].params if the parameters only apply to a certain command.

Configuration

The following hooks are used to configure pytask with the information from the command line and the configuration file as well as making sure that all options play nicely together.

_pytask.hookspecs.pytask_configure(pm: PluginManager, raw_config: dict[str, Any]) → dict[str, Any]

Configure pytask.

The main hook implementation which controls the configuration and calls subordinated hooks.

_pytask.hookspecs.pytask_parse_config(config: dict[str, Any]) → None

Parse configuration that is from CLI or file.

_pytask.hookspecs.pytask_post_parse(config: dict[str, Any]) → None

Post parsing.

This hook allows to consolidate the configuration in case some plugins might be mutually exclusive. For example, the parallel execution provided by pytask-parallel does not work with any form of debugging. If debugging is turned on, parallelization can be turned of in this step.

_pytask.hookspecs.pytask_unconfigure(session: Session) → None

Unconfigure a pytask session before the process is exited.

The hook allows to return resources previously borrowed like pdb.set_trace() by _pytask.debugging.PytaskPDB and do other stuff at the end of a session.

Collection

The following hooks traverse directories and collect tasks from files.

_pytask.hookspecs.pytask_collect(session: Session) → Any

Collect tasks from paths.

The main hook implementation which controls the collection and calls subordinated hooks.

_pytask.hookspecs.pytask_ignore_collect(path: Path, config: dict[str, Any]) → bool

Ignore collected path.

This hook is indicates for each directory and file whether it should be ignored. This speeds up the collection.

_pytask.hookspecs.pytask_collect_modify_tasks(session: Session, tasks: list[PTask]) → None

Modify tasks after they have been collected.

This hook can be used to deselect tasks when they match a certain keyword or mark.

_pytask.hookspecs.pytask_collect_file_protocol(session: Session, path: Path, reports: list[CollectionReport]) → list[CollectionReport]

Start protocol to collect files.

The protocol calls the subordinate hook pytask_collect_file() which might error if the file has a SyntaxError.

_pytask.hookspecs.pytask_collect_file(session: Session, path: Path, reports: list[CollectionReport]) → list[CollectionReport] | None

Collect tasks from a file.

If you want to collect tasks from other files, modify this hook.

_pytask.hookspecs.pytask_collect_task_protocol(session: Session, path: Path | None, name: str, obj: Any) → CollectionReport | None

Start protocol to collect tasks.

_pytask.hookspecs.pytask_collect_task_setup(session: Session, path: Path | None, name: str, obj: Any) → None

Set up collecting a task.

_pytask.hookspecs.pytask_collect_task(session: Session, path: Path | None, name: str, obj: Any) → PTask

Collect a single task.

_pytask.hookspecs.pytask_collect_task_teardown(session: Session, task: PTask) → None

Perform tear-down operations when a task was collected.

Use this hook specification to, for example, perform checks on the collected task.

_pytask.hookspecs.pytask_collect_node(session: Session, path: Path, node_info: NodeInfo) → PNode | None

Collect a node which is a dependency or a product of a task.

_pytask.hookspecs.pytask_collect_log(session: Session, reports: list[CollectionReport], tasks: list[PTask]) → None

Log errors occurring during the collection.

This hook reports errors during the collection.

Resolving Dependencies

The following hooks are designed to build a DAG from tasks and dependencies and check which files have changed and need to be re-run.

Warning

This step is still experimental and likely to change in the future. If you are planning to write a plugin which extends pytask in this dimension, please, start a discussion before writing a plugin. It may make your life easier if changes in pytask anticipate your plugin.

_pytask.hookspecs.pytask_dag(session: Session) → None

Create a DAG.

The main hook implementation which controls the resolution of dependencies and calls subordinated hooks.

_pytask.hookspecs.pytask_dag_create_dag(session: Session, tasks: list[PTask]) → nx.DiGraph

Create the DAG.

This hook creates the DAG from tasks, dependencies and products. The DAG can be used by a scheduler to find an execution order.

_pytask.hookspecs.pytask_dag_log(session: Session, report: DagReport) → None

Log errors during resolving dependencies.

Execution

The following hooks execute the tasks and log information on the result in the terminal.

_pytask.hookspecs.pytask_execute(session: Session) → Any | None

Loop over all tasks for the execution.

The main hook implementation which controls the execution and calls subordinated hooks.

_pytask.hookspecs.pytask_execute_log_start(session: Session) → None

Start logging of execution.

This hook allows to provide a header with information before the execution starts.

_pytask.hookspecs.pytask_execute_create_scheduler(session: Session) → Any

Create a scheduler for the execution.

The scheduler provides information on which tasks are able to be executed. Its foundation is likely a topological ordering of the tasks based on the DAG.

_pytask.hookspecs.pytask_execute_build(session: Session) → Any

Execute the build.

This hook implements the main loop to execute tasks.

_pytask.hookspecs.pytask_execute_task_protocol(session: Session, task: PTask) → ExecutionReport

Run the protocol for executing a test.

This hook runs all stages of the execution process, setup, execution, and teardown and catches any exception.

Then, the exception or success is stored in a report and logged.

_pytask.hookspecs.pytask_execute_task_log_start(session: Session, task: PTask) → None

Start logging of task execution.

This hook can be used to provide more verbose output during the execution.

_pytask.hookspecs.pytask_execute_task_setup(session: Session, task: PTask) → None

Set up the task execution.

This hook is called before the task is executed and can provide an entry-point to fast-fail a task. For example, raise and exception if a dependency is missing instead of letting the error occur in the execution.

_pytask.hookspecs.pytask_execute_task(session: Session, task: PTask) → Any

Execute a task.

_pytask.hookspecs.pytask_execute_task_teardown(session: Session, task: PTask) → None

Tear down task execution.

This hook is executed after the task has been executed. It allows to perform clean- up operations or checks for missing products.

_pytask.hookspecs.pytask_execute_task_process_report(session: Session, report: ExecutionReport) → Any | None

Process the report of a task.

This hook allows to process each report generated by a task which is either based on an exception or a success. Set the color and the symbol for logging.

Some exceptions are intentionally raised like skips, but they should not be reported as failures.

_pytask.hookspecs.pytask_execute_task_log_end(session: Session, report: ExecutionReport) → None

Log the end of a task execution.

_pytask.hookspecs.pytask_execute_log_end(session: Session, reports: list[ExecutionReport]) → None

Log the footer of the execution report.