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:
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user