Document lock workflows

Author: tobiasraabe

.pre-commit-config.yaml

@@ -33,6 +33,13 @@ repos:
     rev: 0.11.6
     hooks:
       - id: uv-lock
+-   repo: local
+    hooks:
+    -   id: check-termynal-line-lengths
+        name: Check Termynal line lengths
+        entry: uv run python scripts/check_termynal_line_lengths.py
+        language: system
+        files: ^docs/source/_static/md/.*\.md$
 -   repo: https://github.com/executablebooks/mdformat
     rev: 1.0.0
     hooks:

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

@@ -0,0 +1,16 @@
+<div class="termy">
+
+```console
+$ pytask lock accept -k train --dry-run
+
+<span class="termynal-dim">──────────────────────────</span> Start pytask session <span class="termynal-dim">──────────────────────────</span>
+Platform: &lt;platform&gt; -- Python &lt;version&gt;, pytask &lt;version&gt;
+Root: &lt;path&gt;
+Collected 2 tasks.
+<span class="termynal-success">Would accept recorded state for task_train.py::task_train.</span>
+<span class="termynal-success">Would accept recorded state for task_evaluate.py::task_evaluate.</span>
+
+<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
+```
+
+</div>

docs/source/_static/md/lock-accept-interactive.md

@@ -0,0 +1,16 @@
+<div class="termy">
+
+```console
+$ pytask lock accept -k train
+<span class="termynal-dim">──────────────────────────</span> Start pytask session <span class="termynal-dim">──────────────────────────</span>
+Platform: &lt;platform&gt; -- Python &lt;version&gt;, pytask &lt;version&gt;
+Root: &lt;path&gt;
+Collected 2 tasks.
+# Accept recorded state for task_train.py::task_train? [y/N]: $ y
+# Accept recorded state for task_evaluate.py::task_evaluate? [y/N]: $ n
+<span class="termynal-success">Accept recorded state for task_train.py::task_train.</span>
+
+<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
+```
+
+</div>

docs/source/_static/md/lock-clean.md

@@ -0,0 +1,17 @@
+<div class="termy">
+
+```console
+$ pytask lock clean
+<span class="termynal-dim">──────────────────────────</span> Start pytask session <span class="termynal-dim">──────────────────────────</span>
+Platform: &lt;platform&gt; -- Python &lt;version&gt;, pytask &lt;version&gt;
+Root: &lt;path&gt;
+Collected 2 tasks.
+# Remove recorded state for task_old.py::task_train? [y/N]: $ y
+# Remove recorded state for task_old.py::task_evaluate? [y/N]: $ y
+<span class="termynal-success">Remove recorded state for task_old.py::task_train.</span>
+<span class="termynal-success">Remove recorded state for task_old.py::task_evaluate.</span>
+
+<span class="termynal-dim">─────────────────────────────────────────────────────────────────────────</span>
+```
+
+</div>

docs/source/how_to_guides/index.md

@@ -10,6 +10,7 @@ specific tasks with pytask.
 - [Migrating From Scripts To Pytask](migrating_from_scripts_to_pytask.md)
 - [Interfaces For Dependencies Products](interfaces_for_dependencies_products.md)
 - [Portability](portability.md)
+- [Reconciling Lockfile State](reconciling_lockfile_state.md)
 - [Remote Files](remote_files.md)
 - [Functional Interface](functional_interface.md)
 - [Capture Warnings](capture_warnings.md)

docs/source/how_to_guides/portability.md

@@ -17,13 +17,11 @@ Use this checklist when you move a project to another machine or environment.
 Run a normal build with [`pytask build`](../reference_guides/commands.md#pytask-build)
 so `pytask.lock` is up to date:
 
-````
 ```console
 $ pytask build
 ```
 
 If you already have a recent lockfile and up-to-date outputs, you can skip this step.
-````
 
 1. **Ship the right files.**
 

docs/source/how_to_guides/reconciling_lockfile_state.md

@@ -0,0 +1,133 @@
+# Reconciling Lockfile State
+
+Use [`pytask lock`](../reference_guides/commands.md#pytask-lock) when the current files
+in the project are already correct and only the recorded state in `pytask.lock` needs to
+catch up.
+
+This is an advanced workflow. Most of the time,
+[`pytask build`](../reference_guides/commands.md#pytask-build) is the right command.
+Reach for `pytask lock` when you want to change the lockfile without executing tasks.
+
+!!! warning
+
+    `pytask lock` is a sharp tool. It updates recorded state without proving that the files
+    were produced by the current task definitions.
+
+## When is this useful?
+
+Typical situations are:
+
+- You reformatted or reorganized a task file and do not want to rerun an expensive task.
+- You renamed or moved a task and want to accept the current outputs for the new task.
+- You produced outputs manually or elsewhere and now want to register them in the
+    lockfile.
+- You deleted or renamed tasks and want to remove their stale lockfile entries.
+
+## Preview changes first
+
+By default, `pytask lock` runs interactively. It shows the planned changes and then asks
+for confirmation one by one. Only entries which would actually change appear in the
+prompt sequence.
+
+To preview changes without writing them, use `--dry-run`:
+
+--8<-- "docs/source/_static/md/lock-accept-dry-run.md"
+
+To apply all planned changes without prompting, use `--yes`:
+
+```console
+$ pytask lock accept -k train --yes
+```
+
+## Accept the current state
+
+Use [`pytask lock accept`](../reference_guides/commands.md#pytask-lock-accept) when the
+current dependencies, products, and task definition are already correct and should
+become the new recorded state.
+
+--8<-- "docs/source/_static/md/lock-accept-interactive.md"
+
+If no selectors are provided, `pytask lock accept` applies to all collected tasks in the
+provided paths.
+
+If selectors are provided with `-k` or `-m`, `accept` automatically includes the
+ancestors of the selected tasks. This is useful when you target a downstream task and
+want the accepted state to stay consistent with its upstream dependencies.
+
+```console
+$ pytask lock accept -k evaluate
+```
+
+In this example, `pytask` accepts `evaluate` and its ancestors. It does not
+automatically include descendants. If you want to accept a wider part of the DAG, widen
+the task selection yourself.
+
+```console
+$ pytask lock accept -k "train or evaluate"
+```
+
+If a selected task is missing a required dependency or product, the command fails
+instead of accepting incomplete state.
+
+## Reset recorded state
+
+Use [`pytask lock reset`](../reference_guides/commands.md#pytask-lock-reset) to remove
+recorded state for selected tasks.
+
+```console
+$ pytask lock reset -k train
+```
+
+Unlike `accept`, `reset` works on the exact selected tasks. It does not automatically
+include ancestors.
+
+On the next build, `pytask` determines again whether these tasks require execution. This
+is useful when state was accepted too broadly or when you want a specific task to be
+reconsidered from scratch.
+
+## Remove stale lockfile entries
+
+Use [`pytask lock clean`](../reference_guides/commands.md#pytask-lock-clean) to remove
+entries from the lockfile which no longer correspond to collected tasks in the current
+project.
+
+--8<-- "docs/source/_static/md/lock-clean.md"
+
+This is useful after deleting, renaming, or moving tasks when old entries should no
+longer remain in the lockfile.
+
+## Example workflow
+
+One common workflow looks like this:
+
+1. Run a normal build once.
+1. Change a task file in a way that should not force a rerun.
+1. Accept the current state.
+1. Verify that a later build skips the task.
+1. Reset the task if you want `pytask` to reconsider it again.
+
+```console
+$ pytask build
+$ pytask lock accept -k train --yes
+$ pytask build
+$ pytask lock reset -k train --yes
+$ pytask build
+```
+
+After `accept`, the next build skips unchanged tasks according to the updated lockfile.
+After `reset`, the selected tasks are reconsidered on the next build.
+
+## Be explicit about scope
+
+Start with narrow task selections, preview changes with `--dry-run`, and widen the
+selection only when needed.
+
+This is especially important for `accept`: it is often better to accept a small part of
+the DAG first and then inspect the result than to update the whole project at once.
+
+## Related
+
+- [`pytask lock`](../reference_guides/commands.md#pytask-lock)
+- [`pytask build`](../reference_guides/commands.md#pytask-build)
+- [Portability](portability.md)
+- [The lockfile](../reference_guides/lockfile.md)

mkdocs.yml

@@ -38,6 +38,7 @@ nav:
       - Migrating From Scripts To pytask: how_to_guides/migrating_from_scripts_to_pytask.md
       - Interfaces For Dependencies And Products: how_to_guides/interfaces_for_dependencies_products.md
       - Portability: how_to_guides/portability.md
+      - Reconciling Lockfile State: how_to_guides/reconciling_lockfile_state.md
       - Remote Files: how_to_guides/remote_files.md
       - Functional Interface: how_to_guides/functional_interface.md
       - Capture Warnings: how_to_guides/capture_warnings.md

scripts/check_termynal_line_lengths.py

@@ -0,0 +1,74 @@
+"""Check visible line lengths in Termynal documentation snippets."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from html import unescape
+from pathlib import Path
+
+# Existing Termynal snippets top out at 78 visible characters.
+MAX_TERMYNAL_LINE_LENGTH = 78
+
+_CONSOLE_BLOCK_PATTERN = re.compile(r"```console\n(.*?)\n```", re.DOTALL)
+_HTML_TAG_PATTERN = re.compile(r"<[^>]+>")
+
+
+def _visible_text(line: str) -> str:
+    return unescape(_HTML_TAG_PATTERN.sub("", line))
+
+
+def _iter_violations(path: Path, max_length: int) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    if 'class="termy"' not in text:
+        return []
+
+    violations = []
+    for match in _CONSOLE_BLOCK_PATTERN.finditer(text):
+        start_line = text.count("\n", 0, match.start(1)) + 1
+        for offset, raw_line in enumerate(match.group(1).splitlines()):
+            rendered_line = _visible_text(raw_line)
+            line_length = len(rendered_line)
+            if line_length > max_length:
+                violations.append(
+                    f"{path}:{start_line + offset}: rendered line has "
+                    f"{line_length} characters, maximum is {max_length}:\n"
+                    f"    {rendered_line}"
+                )
+
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        type=Path,
+        default=sorted(Path("docs/source/_static/md").rglob("*.md")),
+        help="Markdown files with Termynal snippets.",
+    )
+    parser.add_argument(
+        "--max-length",
+        type=int,
+        default=MAX_TERMYNAL_LINE_LENGTH,
+        help="Maximum visible line length for rendered terminal lines.",
+    )
+    args = parser.parse_args()
+
+    violations = [
+        violation
+        for path in args.paths
+        if path.is_file()
+        for violation in _iter_violations(path, args.max_length)
+    ]
+    if violations:
+        sys.stderr.write("\n\n".join(violations))
+        sys.stderr.write("\n")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())