Explain why tasks will be executed. (#704)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: tobiasraabe

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
     -   id: python-no-log-warn
     -   id: text-unicode-replacement-char
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.13.2
+    rev: v0.13.3
     hooks:
       - id: ruff-format
       - id: ruff-check

CHANGELOG.md

@@ -8,6 +8,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 ## 0.5.6 - 2025-xx-xx
 
 - {pull}`703` fixes {issue}`701` by allowing `--capture tee-sys` again.
+- {pull}`704` adds the `--explain` flag to show why tasks would be executed. Closes {issue}`466`.
 
 ## 0.5.5 - 2025-07-25
 

docs/source/_static/md/capture.md

@@ -6,7 +6,7 @@ $ pytask
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">2</span> tasks.
+Collected 2 tasks.
 
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
 ┃ Task                         ┃ Outcome ┃

docs/source/_static/md/clean-dry-run-directories.md

@@ -6,7 +6,7 @@ $ pytask clean --directories
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">1</span> task.
+Collected 1 task.
 
 Files which can be removed:
 

docs/source/_static/md/clean-dry-run.md

@@ -6,7 +6,7 @@ $ pytask clean
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">1</span> task.
+Collected 1 task.
 
 Files which can be removed:
 

docs/source/_static/md/collect-nodes.md

@@ -6,7 +6,7 @@ $ pytask
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">1</span> task.
+Collected 1 task.
 
 Collected tasks:
 └── 🐍 &lt;Module task_module.py&gt;

docs/source/_static/md/collect.md

@@ -6,7 +6,7 @@ $ pytask
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">1</span> task.
+Collected 1 task.
 
 Collected tasks:
 └── 🐍 &lt;Module task_module.py&gt;

docs/source/_static/md/defining-dependencies-products.md

@@ -6,7 +6,7 @@ $ pytask
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">2</span> task.
+Collected 2 task.
 
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
 ┃ Task                                              ┃ Outcome ┃

docs/source/_static/md/dry-run.md

@@ -6,7 +6,7 @@ $ pytask --dry-run
 ────────────────────────── Start pytask session ─────────────────────────
 Platform: win32 -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.3</span>, pluggy <span style="color: var(--termynal-blue)">1.3.0</span>
 Root: C:\Users\pytask-dev\git\my_project
-Collected <span style="color: var(--termynal-blue)">1</span> task.
+Collected 1 task.
 
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
 ┃ Task                                              ┃ Outcome ┃

docs/source/_static/md/explain.md

@@ -0,0 +1,46 @@
+<div class="termy">
+
+```console
+
+$ pytask --explain
+────────────────────────── Start pytask session ─────────────────────────
+Platform: darwin -- Python <span style="color: var(--termynal-blue)">3.12.0</span>, pytask <span style="color: var(--termynal-blue)">0.5.6</span>, pluggy <span style="color: var(--termynal-blue)">1.6.0</span>
+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>
+```
+
+</div>