Invoking pytask¶
Invoke pytask from the command line with
$ pytask
Use the following flags to learn more about pytask and its configuration.
$ pytask --version
$ pytask -h | --help
Commands¶
pytask has multiple commands listed on the main help page.
$ pytask --help
<center>pytask <span class="termynal-dim">v0.5.3</span></center>
Usage: <b>pytask [OPTIONS] [COMMAND] [PATHS]</b>
<span class="termynal-dim">Manage your tasks with pytask.</span>
<font color="#5f5f5f">╭─</font> Commands <font color="#5f5f5f">────────────────────────────────────────────────────────────╮</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">build *</span> Collect tasks, execute them and report the results. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">clean </span> Clean the provided paths by removing files unknown to pytask. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">collect</span> Collect tasks and report information about them. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">dag </span> Create a visualization of the directed acyclic graph. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">markers</span> Show all registered markers. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-command">profile</span> Show information about resource consumption <font color="#5f5f5f">│</font>
<font color="#5f5f5f">╰───────────────────────────────────────────────────────────────────────╯</font>
<font color="#5f5f5f">╭─</font> Options <font color="#5f5f5f">─────────────────────────────────────────────────────────────╮</font>
<font color="#5f5f5f">│</font> <span class="termynal-option">--version</span> Show the version and exit. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">│</font> <span class="termynal-switch">-h</span> <span class="termynal-option">--help</span> Show this message and exit. <font color="#5f5f5f">│</font>
<font color="#5f5f5f">╰───────────────────────────────────────────────────────────────────────╯</font>
<p align="right"><font color="#cd3131">♥</font> <a style="color: #f2f2f2" href="https://pytask-dev.readthedocs.io">https://pytask-dev.readthedocs.io</a> </p>
The build command is the default command, meaning the following two calls are
identical.
$ pytask
$ pytask build
Display command-specific information by adding the help flag after the command.
$ pytask <command-name> -h/--help
The build command¶
The build command accepts many options paths as positional arguments. If no paths are
passed via the command line interface, pytask will look for the paths key in the
configuration file. At last, pytask will collect tasks from the current working
directory and subsequent folders.
You can also pass any number of paths of directories or modules to the program.
$ pytask path/to/task_module.py path/to/folder
Don’t use paths to run task subsets. Use expressions instead. When pytask collects tasks from subpaths of your project, it cannot infer the whole structure of dependencies and products and might run your tasks with missing or outdated dependencies.
Options¶
Here are a few selected options for the build command.
Showing errors immediately¶
To show errors immediately when they occur, use
$ pytask --show-errors-immediately
It can be helpful when you have a long-running workflow but want feedback as soon as it is available.
Stopping after the first (N) failures¶
To stop the build of the project after the first n failures, use
$ pytask -x | --stop-after-first-failure # Stop after the first failure
$ pytask --max-failures 2 # Stop after the second failure
Performing a dry-run¶
Do a dry run to see which tasks will be executed without executing them.
$ pytask --dry-run
────────────────────────── Start pytask session ─────────────────────────
Platform: win32 -- Python 3.12.0, pytask 0.5.3, pluggy 1.3.0
Root: C:\Users\pytask-dev\git\my_project
Collected 1 task.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Task ┃ Outcome ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ <span class="termynal-dim">task_dry_run.py::</span>task_dry_run │ <span class="termynal-success">w</span> │
└───────────────────────────────────────────────────┴─────────┘
<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
<span class="termynal-success">╭───────────</span> <span style="font-weight: bold;">Summary</span> <span class="termynal-success">──────────────╮</span>
<span class="termynal-success">│</span> <span style="font-weight: bold;"> 1 Collected task </span> <span class="termynal-success">│</span>
<span class="termynal-success">│</span> <span class="termynal-success-textonly"> 1 Would be executed (100.0%) </span> <span class="termynal-success">│</span>
<span class="termynal-success">╰──────────────────────────────────╯</span>
<span class="termynal-success">─────────────────────── Succeeded in 0.02 seconds ───────────────────────</span>
Explaining why tasks are executed¶
Use the --explain flag to understand why tasks need to be executed. This shows what
changed (source files, dependencies, products, previous tasks) and helps you understand
pytask’s execution decisions.
$ pytask --explain
────────────────────────── Start pytask session ─────────────────────────
Platform: darwin -- Python 3.12.0, pytask 0.5.6, pluggy 1.6.0
Root: /Users/pytask-dev/git/my_project
Collected 3 tasks.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Task ┃ Outcome ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ <span class="termynal-dim">task_data.py::</span>task_create_data │ <span class="termynal-success">w</span> │
│ <span class="termynal-dim">task_analysis.py::</span>task_analyze │ <span class="termynal-success">w</span> │
│ <span class="termynal-dim">task_plot.py::</span>task_plot │ <span class="termynal-dim">s</span> │
└───────────────────────────────────────────────────┴─────────┘
<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
<span style="color: var(--termynal-blue); font-weight: bold;">────────────────────────────── Explanation ──────────────────────────────</span>
<span class="termynal-success">─── Tasks that would be executed ────────────────────────────────────────</span>
<span style="font-weight: bold;">task_data.py::task_create_data</span>
• task_data.py::task_create_data: Changed
<span style="font-weight: bold;">task_analysis.py::task_analyze</span>
• Preceding task_data.py::task_create_data would be executed
<span class="termynal-skipped">─── Skipped tasks ───────────────────────────────────────────────────────</span>
<span style="font-weight: bold;">task_plot.py::task_plot</span>
• Skipped by marker
1 persisted task(s) (use -vv to show details)
<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
<span class="termynal-success">╭───────────</span> <span style="font-weight: bold;">Summary</span> <span class="termynal-success">──────────────╮</span>
<span class="termynal-success">│</span> <span style="font-weight: bold;"> 3 Collected tasks </span> <span class="termynal-success">│</span>
<span class="termynal-success">│</span> <span class="termynal-success-textonly"> 2 Would be executed (66.7%) </span> <span class="termynal-success">│</span>
<span class="termynal-success">│</span> <span class="termynal-dim-textonly"> 1 Skipped (33.3%) </span> <span class="termynal-success">│</span>
<span class="termynal-success">╰──────────────────────────────────╯</span>
<span class="termynal-success">─────────────────────── Succeeded in 0.02 seconds ───────────────────────</span>
The explanation output respects the --verbose flag:
Default verbosity: Shows tasks that would be executed and skipped tasks
-vor--verbose 1: Same as default, with summary for persisted and unchanged tasks--verbose 2: Shows detailed information including persisted and unchanged tasks with change reasons
Functional interface¶
pytask also has a functional interface that is explained in this article.