daedalus 0.3.0: argparse CLI + argcomplete shell completion, script-arg delegation

- cli.py rewritten on argparse (build_parser, REMAINDER pass-through: everything
  after the script name still belongs to the script); help/errors are
  argparse-rendered, exit code 2 kept for all daedalus errors
- completions.py (new): category-aware candidates for argcomplete - script names
  + unused labels narrowed by typed labels (daedalus test h<TAB> -> hello);
  --path completes scripts; after a completed script name daedalus offers
  nothing of its own and delegates .py scripts to their own parser via the
  run_python_script child with a rewritten COMP_LINE (daedalus hello -<TAB> ->
  hello's -h --help); SPEC 6.9 documents the autocomplete(parser) opt-in
- SPEC: item 1.5 reuse-first third-party policy, 3.8/3.10/3.11 argparse texts,
  3.13 completion catalog, 6.9 script opt-in, 9.6 argcomplete dependency
- argcomplete>=3.3 as runtime dep (guarded import: CLI runs without it);
  register-python-argcomplete line for ~/.bashrc; PYTHON_ARGCOMPLETE_OK marker
  in bin/daedalus; README/INSTALL/CHANGELOG updated; hello opts in
- tests: argparse CLI suites, completer units, end-to-end argcomplete probes
  through the bash fd-8 protocol and the delegation exec chain (autotest green,
  coverage 97%)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-18 22:09:04 +01:00
parent 5d4f9417fd
commit c210e17661
13 changed files with 699 additions and 74 deletions
+127 -37
View File
@@ -49,8 +49,13 @@ added (section 6).
- **1.4** Scripts are written in Python, bash, PowerShell, or batch. The
CLI picks the interpreter from the file suffix and passes arguments,
terminal, and exit code straight through.
- **1.5** The CLI itself uses only the Python standard library. Python
3.11 or newer.
- **1.5** Reuse first: when a popular, widely tested, trusted
third-party package already solves a problem, use it instead of
writing our own code; the Python standard library covers the rest.
Python 3.11 or newer. Dependency policy: SPEC item 9.6. Today the one
dependency is argcomplete, for shell completion (SPEC item 3.13);
its import is guarded, so the CLI also runs where it is not
installed — completion is then off.
## 2. Layout
@@ -59,12 +64,13 @@ added (section 6).
```text
daedalus/
├── bin/
│ ├── daedalus # Linux launcher (bash), no install needed
│ ├── daedalus # Linux launcher (bash), no install needed; PYTHON_ARGCOMPLETE_OK marker
│ └── daedalus.bat # Windows launcher (cmd / PowerShell)
├── daedalus/ # The CLI package
│ ├── __init__.py # PACKAGE_DIR, REPO_ROOT, LIBRARY_ROOT, checkout imports
│ ├── __main__.py # python -m daedalus
│ ├── cli.py # Argument handling, list, path, dispatch
│ ├── cli.py # argparse parser, list, path, dispatch
│ ├── completions.py # Completion candidates for argcomplete
│ ├── registry.py # Script, SCRIPTS, category helpers
│ ├── runners.py # Suffix -> interpreter command, run
│ ├── run_python_script.py # Child entry for .py scripts (logging, argv)
@@ -170,16 +176,28 @@ sample_script_name py general, linux
- **3.7.3** `python -m daedalus` from the repository root.
- **3.7.4** The installed command is the entry point
`daedalus = daedalus.cli:main`.
- **3.8** `--help` prints this text:
- **3.8** `-h` / `--help` prints the argparse rendering of the parser in
SPEC item 3.10 (80 columns shown; wrapped to the terminal width):
```text
usage: daedalus <name> [args...] run a script; args go to the script
daedalus <category> [category...] list scripts (AND when multiple)
daedalus <category>… <name> [args...] run when script has every category
daedalus [-l | --list] list all registered scripts
daedalus --path <name> print the path of a script
daedalus --version print the installed version
daedalus -h | --help show this help
usage: daedalus [-h] [-l | --list] [--version] [--path <name>] [<category> ...] [<name> [args ...]]
One CLI, many small scripts, each with tests (SPEC.md).
positional arguments:
<category|name> category labels to filter or list, then the script name to
run
[args ...] arguments passed to the script
options:
-h, --help show this help message and exit
-l, --list list all registered scripts
--version print the installed version
--path <name> print the path of a script
Forms: daedalus <name> [args...] runs a script; daedalus <category>
[category...] lists the scripts with every category (AND when several);
daedalus <category>... <name> [args...] runs a script that has every category.
```
- **3.9** The version is resolved in this order:
@@ -187,39 +205,60 @@ usage: daedalus <name> [args...] run a script; args go to the
- **3.9.2** `project.version` from `REPO_ROOT/pyproject.toml` (a
checkout that is not installed).
- **3.9.3** The string `unknown`.
- **3.10** Argument resolution. Options are recognized only as the first
token:
- **3.10** Argument resolution. One `argparse.ArgumentParser`
(`prog="daedalus"`, `allow_abbrev=False`, subclass whose `error()`
raises `UsageError` instead of exiting):
```text
dispatch(argv):
if argv is empty or argv[0] in ("-l", "--list"): list(all scripts); return 0
if argv[0] in ("-h", "--help"): print usage; return 0
if argv[0] == "--version": print "daedalus " + version; return 0
if argv[0] == "--path":
require exactly one more token, else usage error
print absolute path of lookup(argv[1]) # file need not exist
parser arguments:
-l | --list store_true flag
--version store_true flag
--path <name>
words positional, nargs "*", metavar <category|name>
script_args positional, argparse.REMAINDER, metavar [args ...]
main(argv = sys.argv[1:]):
parser = build_parser()
argcomplete.autocomplete(parser) when importable (SPEC item 3.13)
try:
parsed = parser.parse_args(argv)
return dispatch(parsed)
on usage or runner error: print "daedalus: <message>" to stderr; return 2
dispatch(parsed):
if --list or ((words and script_args both empty) and no option set):
list(all scripts); return 0
if --version: print "daedalus " + version; return 0
if --path:
if words or script_args is not empty: usage error "usage: daedalus --path <name>"
print absolute path of lookup(--path value) # file need not exist
return 0
if argv[0] starts with "-": usage error "unknown option"
prefix = leading tokens while is_category_label(token)
rest = remaining tokens
prefix = leading words entries while is_category_label(entry)
rest = remaining words entries
if prefix and rest is empty:
scripts = scripts having every label in prefix
if none: usage error "no scripts for categories"
list(scripts); return 0
if prefix: script = lookup_in(prefix, rest[0]); return run(script, rest[1:])
return run(lookup(argv[0]), argv[1:])
main(argv = sys.argv[1:]):
try dispatch(argv)
on usage or runner error: print "daedalus: <message>" to stderr; return 2
if rest: script = lookup_in(prefix, rest[0]) when prefix else lookup(rest[0])
return run(script, rest[1:] + script_args)
```
- **3.11** Error messages (each printed as `daedalus: <message>`):
With argparse, options are parsed wherever argparse sees them before
the positionals start (the old first-token-only rule is gone), but
everything after the first positional word that argparse cannot bind
to `words` is captured by `script_args` (REMAINDER) and passed through
(SPEC item 3.1): `daedalus <name> --help` still shows the **script's**
help.
- **3.11** Error messages: parser errors carry the argparse message,
registry errors keep their exact texts; each is printed as
`daedalus: <message>` on stderr with exit code 2:
| Case | Message |
| --- | --- |
| `--path` without exactly one name | `usage: daedalus --path <name>` |
| Unknown option | `unknown option '<opt>'; run 'daedalus --help'` |
| `--path` without a value | `argument --path: expected one argument` |
| `--path` with extra words | `usage: daedalus --path <name>` |
| Unknown option | `unrecognized arguments: <opt>` |
| Unknown script, close matches exist | `unknown script '<name>'; did you mean: <m1>, <m2>` |
| Unknown script, no close match | `unknown script '<name>'; run 'daedalus --list'` |
| Categories match no script | `no scripts for categories: <a>, <b>` |
@@ -229,6 +268,45 @@ main(argv = sys.argv[1:]):
- **3.12** Close matches are up to 3 names with similarity ratio at least
0.6 (Python `difflib.get_close_matches` defaults). After a category
prefix, only scripts in those categories are candidates.
- **3.13** Shell completion for the parser above (SPEC item 3.10) comes
from argcomplete (SPEC item 1.5):
- **3.13.1** `main` calls `argparse` completion via
`argcomplete.autocomplete(parser)` before `parse_args`, when
argcomplete is importable. Without argcomplete the CLI runs
unchanged, with completion off.
- **3.13.2** Activation (bash): `eval "$(register-python-argcomplete
daedalus)"` in `~/.bashrc`; `register-python-argcomplete` ships with
argcomplete. Other shells argcomplete supports (zsh, fish, tcsh,
powershell) register the same way.
- **3.13.3** Completing a `words` entry (SPEC item 3.10):
`daedalus/completions.py` offers every registered script name and
every category label in use, narrowed by prefix; category labels
already typed are not offered again, and script candidates narrow to
the scripts that have every typed label (SPEC item 3.4): `daedalus
test h<TAB>` completes `hello`. Candidates are sorted.
- **3.13.4** `--path <name>` completes script names.
- **3.13.5** After a registered script name has been typed (completed,
before the word being completed), the rest of the line belongs to
the script (SPEC item 3.1): daedalus offers nothing of its own —
not its options, and never the working-directory file listing (the
`script_args` action keeps its empty completer, SPEC 3.10).
- **3.13.5.1** A `.py` script is asked to complete its own
arguments: daedalus re-execs the interpreter command of its
runner (SPEC item 5.8) with the argument words as the script's
argv, `COMP_LINE` rewritten to start at the script name,
`COMP_POINT` adjusted, the completion environment passed
through, and the completion channel (fd 8) inherited. The script
completes its arguments (SPEC item 6.9); quoting in the words is
not preserved in the rewrite.
- **3.13.5.2** bash, PowerShell, and batch scripts get no
candidates: the shell default completion (file names) applies.
- **3.13.6** The completion hook re-runs the `daedalus` command on
`PATH`: the program that runs on TAB must import argcomplete
(installed dependency, or the dev venv, or the system package) and
must reach `autocomplete` before parsing.
- **3.13.7** `bin/daedalus` carries a `# PYTHON_ARGCOMPLETE_OK` comment
in its first kilobyte: argcomplete versions that scan for the
marker require it.
## 4. Registry
@@ -380,6 +458,14 @@ SCRIPTS: dict[str, Script] = {
- **6.7** Bump `version` in `pyproject.toml` and add a `CHANGELOG.md`
entry.
- **6.8** Run `python autotest.py`. It must pass before pushing.
- **6.9** A Python script opts in to completing its own arguments
(SPEC item 3.13.5.1): right after building its parser it calls
`argcomplete.autocomplete(parser)` behind a guarded import (SPEC item
1.5). `daedalus <category>... <name> -<TAB>` then completes the
script's own options; without the call, such words fall back to the
shell default, and a TAB can run the script itself (argcomplete
semantics — scripts that must not run on TAB do not opt in or keep
their parser behind a subcommand).
## 7. Quality gates
@@ -445,7 +531,8 @@ autotest results
`pip install -r requirements.txt`, then `python autotest.py`. The
sanity diff base is passed as `SANITY_DIFF_BASE`.
- **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`,
`pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`.
`pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`,
and `argcomplete` (the runtime dependency, so the completion tests run).
## 8. Conventions
@@ -499,9 +586,11 @@ autotest results
resolve to (section 10).
- **9.5** Tests under `*/tests/`, bytecode, and `.gitkeep` are not
packaged.
- **9.6** Runtime dependencies: none; the CLI uses only the standard
library. A script that needs third-party packages says so in its own
help text and fails with a clear message when they are missing;
- **9.6** Runtime dependencies follow SPEC item 1.5 (reuse first): the
wheel declares `argcomplete >= 3` for shell completion (SPEC item
3.13); everything else is the standard library. A script that needs
other third-party packages says so in its own help text and fails
with a clear message when they are missing;
`DAEDALUS_PYTHON` (SPEC item 5.2) points it at their environment.
Test and lint tools stay in `requirements.txt`.
- **9.7** Tests build the wheel from a copy of the checkout and check:
@@ -587,3 +676,4 @@ on import daedalus:
| 16 | `run_python_script.py` and `daedalus_logging` (section 11) | Done |
| 17 | `daedalus.<folder>` imports in checkouts and installs (section 10) | Done |
| 18 | Listing table with version line, wrapped descriptions, and color (SPEC item 3.3) | Done |
| 19 | argparse parser and argcomplete shell completion (SPEC items 3.10, 3.13) | Done |