CLI Reference¶

Running pytask without a subcommand is equivalent to pytask build.

Command Index¶

• pytask build: Collect tasks, execute them and report the results.
• pytask clean: Clean the provided paths by removing files unknown to pytask.
• pytask collect: Collect tasks and report information about them.
• pytask dag: Create a visualization of the directed acyclic graph.
• pytask lock: Inspect and update recorded task state in the lockfile.
• pytask markers: Show all registered markers.
• pytask profile: Show information about resource consumption.

pytask¶

Manage your tasks with pytask.

Usage

pytask [OPTIONS] COMMAND [ARGS]...

Commands

• pytask build: Collect tasks, execute them and report the results.
• pytask clean: Clean the provided paths by removing files unknown to pytask.
• pytask collect: Collect tasks and report information about them.
• pytask dag: Create a visualization of the directed acyclic graph.
• pytask lock: Inspect and update recorded task state in the lockfile.
• pytask markers: Show all registered markers.
• pytask profile: Show information about resource consumption.

Options

--version

Show the version and exit.

--help

Show this message and exit.

pytask build¶

Collect tasks, execute them and report the results.

Usage

pytask build [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

--capture [fd|no|sys|tee-sys]

Per task capturing method.

Default: fd
Accepted values: fd, no, sys, tee-sys

--database-url TEXT

Url to the database.

--debug-pytask

Trace all function calls in the plugin framework.

Default: false

--disable-warnings

Disables the summary for warnings.

Default: false

--dry-run

Perform a dry-run.

Default: false

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--explain

Explain why tasks need to be executed by showing what changed.

Default: false

-f, --force

Execute a task even if it succeeded successfully before.

Default: false

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

-k EXPRESSION

Select tasks via expressions on task ids.

--log-cli / --no-log-cli

Enable live log display during task execution.

Default: --no-log-cli

--log-cli-date-format TEXT

Log date format used by the logging module for live logs.

--log-cli-format TEXT

Log format used by the logging module for live logs.

--log-cli-level LEVEL

CLI logging level.

--log-date-format TEXT

Log date format used by the logging module.

Default: %H:%M:%S

--log-file TEXT

Path to a file where logging will be written.

--log-file-date-format TEXT

Log date format used by the logging module for the log file.

--log-file-format TEXT

Log format used by the logging module for the log file.

--log-file-level LEVEL

Log file logging level.

--log-file-mode [w|a]

Log file open mode.

Default: w
Accepted values: w, a

--log-format TEXT

Log format used by the logging module.

Default: %(levelname)-8s %(name)s:%(filename)s:%(lineno)d %(message)s

--log-level LEVEL

Level of messages to catch/display. Not set by default, so it depends on the logger configuration.

-m MARKER_EXPRESSION

Select tasks via marker expressions.

--max-failures FLOAT RANGE

Stop after some failures.

Default: inf

--n-entries-in-table INTEGER RANGE

How many entries to display in the table during the execution. Tasks which are running are always displayed.

Default: 15

--pdb

Start the interactive debugger on errors.

Default: false

--pdbcls module_name:class_name

Start a custom debugger on errors. For example: --pdbcls=IPython.terminal.debugger:TerminalPdb

-s

Shortcut for --capture=no.

Default: false

--show-capture [no|stdout|stderr|log|all]

Choose which captured output should be shown for failed tasks.

Default: all
Accepted values: no, stdout, stderr, log, all

--show-errors-immediately

Show errors with tracebacks as soon as the task fails.

Default: false

--show-locals

Show local variables in tracebacks.

Default: false

--show-traceback / --show-no-traceback

Choose whether tracebacks should be displayed or not.

Default: --show-traceback

--sort-table / --do-not-sort-table

Sort the table of tasks at the end of the execution.

Default: --sort-table

--strict-markers

Raise errors for unknown markers.

Default: false

--trace

Enter debugger in the beginning of each task.

Default: false

-v, --verbose INTEGER RANGE

Make pytask verbose (>= 0) or quiet (= 0).

Default: 1

-x, --stop-after-first-failure

Stop after the first failure.

Default: false

--help

Show this message and exit.

pytask clean¶

Clean the provided paths by removing files unknown to pytask.

Usage

pytask clean [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

-d, --directories

Remove whole directories.

Default: false

--database-url TEXT

Url to the database.

-e, --exclude PATTERN

A filename pattern to exclude files from the cleaning process.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

-k EXPRESSION

Select tasks via expressions on task ids.

-m MARKER_EXPRESSION

Select tasks via marker expressions.

--mode [dry-run|force|interactive]

Choose 'dry-run' to print the paths of files/directories which would be removed, 'interactive' for a confirmation prompt for every path, and 'force' to remove all unknown paths at once.

Default: dry-run
Accepted values: dry-run, force, interactive

-q, --quiet

Do not print the names of the removed paths.

Default: false

--strict-markers

Raise errors for unknown markers.

Default: false

--help

Show this message and exit.

pytask collect¶

Collect tasks and report information about them.

Usage

pytask collect [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

--database-url TEXT

Url to the database.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

-k EXPRESSION

Select tasks via expressions on task ids.

-m MARKER_EXPRESSION

Select tasks via marker expressions.

--nodes

Show a task's dependencies and products.

Default: false

--strict-markers

Raise errors for unknown markers.

Default: false

--help

Show this message and exit.

pytask dag¶

Create a visualization of the directed acyclic graph.

Usage

pytask dag [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

--database-url TEXT

Url to the database.

--hook-module TEXT

Path to a Python module that contains hook implementations.

-l, --layout TEXT

The layout determines the structure of the graph. Here you find an overview of all available layouts: https://graphviz.org/docs/layouts.

Default: dot

-o, --output-path FILE

The output path of the visualization. The format is inferred from the file extension.

Default: dag.pdf

-r, --rank-direction [TB|LR|BT|RL]

The direction of the directed graph. It can be ordered from top to bottom, TB, left to right, LR, bottom to top, BT, or right to left, RL.

Default: TB
Accepted values: TB, LR, BT, RL

--help

Show this message and exit.

pytask lock¶

Inspect and update recorded task state in the lockfile.

Usage

pytask lock [OPTIONS] COMMAND [ARGS]...

Commands

• pytask lock accept: Accept the current state for selected tasks and their ancestors.
• pytask lock clean: Remove stale lockfile entries which no longer correspond to collected tasks.
• pytask lock reset: Remove recorded state for selected tasks.

Options

--help

Show this message and exit.

pytask lock accept¶

Accept the current state for selected tasks and their ancestors.

Usage

pytask lock accept [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-y, --yes

Apply the changes without prompting for confirmation.

Default: false

--dry-run

Show which recorded states would be updated without writing changes.

Default: false

--strict-markers

Raise errors for unknown markers.

Default: false

-m MARKER_EXPRESSION

Select tasks via marker expressions.

-k EXPRESSION

Select tasks via expressions on task ids.

-c, --config FILE

Path to configuration file.

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--help

Show this message and exit.

pytask lock clean¶

Remove stale lockfile entries which no longer correspond to collected tasks.

Usage

pytask lock clean [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-y, --yes

Apply the changes without prompting for confirmation.

Default: false

--dry-run

Show which stale entries would be removed without writing changes.

Default: false

-c, --config FILE

Path to configuration file.

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--help

Show this message and exit.

pytask lock reset¶

Remove recorded state for selected tasks.

Usage

pytask lock reset [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-y, --yes

Apply the changes without prompting for confirmation.

Default: false

--dry-run

Show which recorded states would be removed without writing changes.

Default: false

--strict-markers

Raise errors for unknown markers.

Default: false

-m MARKER_EXPRESSION

Select tasks via marker expressions.

-k EXPRESSION

Select tasks via expressions on task ids.

-c, --config FILE

Path to configuration file.

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--help

Show this message and exit.

pytask markers¶

Show all registered markers.

Usage

pytask markers [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

--hook-module TEXT

Path to a Python module that contains hook implementations.

--help

Show this message and exit.

pytask profile¶

Show information about resource consumption.

Usage

pytask profile [OPTIONS] [PATHS]...

Arguments

[PATHS]...

Paths where pytask looks for task files and configuration.

Options

-c, --config FILE

Path to configuration file.

--database-url TEXT

Url to the database.

--editor-url-scheme TEXT

Use file, vscode, pycharm or a custom url scheme to add URLs to task ids to quickly jump to the task definition. Use no_link to disable URLs.

Default: file

--export [no|json|csv]

Export the profile in the specified format.

Default: no
Accepted values: no, json, csv

--hook-module TEXT

Path to a Python module that contains hook implementations.

--ignore TEXT

A pattern to ignore files or directories. Refer to 'pathlib.Path.match' for more info.

--help

Show this message and exit.