PyPI policy-blocks the plain name: the 0.12.1 upload was rejected with "The name 'daedalus' isn't allowed" (near the existing daedalus-cli and pydaedalus projects). The distribution is now daedalus-tools; command, imports, registry, and the repository name stay daedalus. hello's installed-version lookup follows. publish now derives artifact file names from the PEP 625 normalized name (daedalus_tools-<version>.tar.gz) - with a hyphenated project name the previously constructed names would have missed what setuptools writes to dist/ (publish spec 3.2, new regression test). Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
7.3 KiB
Installing and using daedalus
Python 3.11 or newer. This checkout is an empty template (no scripts in
SCRIPTS yet). Once you add scripts, the installed daedalus command
bundles every registered one and works from any directory.
Back to the script list. Repository rules: SPEC.
Install
With pipx (recommended)
pipx installs the daedalus-tools distribution
(from PyPI or Git) into its own environment and puts the daedalus
command on PATH — the project name and the command differ on purpose
(plain daedalus is policy-blocked on PyPI; see SPEC item 9.1).
Linux (Debian 12): paste once; open a new shell if pipx was just
installed. Run the same block again to refresh from Git (main); do not
use pipx upgrade daedalus-tools for Git installs — it does not pull the repo.
daedalus_pipx_install() {
r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
command -v pipx >/dev/null || sudo apt install -y pipx
pipx ensurepath 2>/dev/null || pipx ensurepath --force
pipx install --force "$r"
daedalus --version
}; daedalus_pipx_install
No SSH key on the Git host: daedalus_pipx_install git+https://example.com/your-org/daedalus.git
Windows (PowerShell):
python -m pip install --user pipx
python -m pipx ensurepath # once; then open a new terminal
pipx install git+ssh://git@example.com/your-org/daedalus.git
Without an SSH key for the Git host, use
git+https://example.com/your-org/daedalus.git instead.
From a checkout
git clone git@example.com:your-org/daedalus.git
cd daedalus
pipx install . # or, inside a virtual environment: pip install .
On Debian 12, pip install into the system Python is blocked
(externally managed environment). Use pipx or a virtual environment.
Without installing
Linux: add to ~/.bashrc, call daedalus_checkout (clone once,
then git pull --ff-only).
daedalus_checkout() {
d="${1:-$HOME/daedalus}"
[[ -d "$d/.git" ]] && git -C "$d" pull --ff-only \
|| git clone git@example.com:your-org/daedalus.git "$d"
export PATH="$d/bin:$PATH"
}; daedalus_checkout
Windows: add <checkout>\bin to PATH (bin\daedalus.bat).
Check, upgrade, remove
daedalus --version # confirm the install
daedalus_pipx_install # reinstall from Git (same as first paste block)
pipx uninstall daedalus
Usage
daedalus --help # usage
daedalus [--list] # list the available scripts
daedalus <name> [args...] # run a script; every argument after the name goes to it
daedalus <category> [category...] # list scripts that have every category
daedalus <category> <name> [args...] # run when the script has every category
daedalus --path <name> # print where the script file is
daedalus --version # print the installed version
daedalus NAME --helpshows the help of the script, not of daedalus.- The exit code is the script's exit code. daedalus's own errors, such as an unknown name, exit with 2 and suggest close matches.
- Listings print
Daedalus Version:, a table ofscript,type, andcategories, and the wrapped description under each row. Colors followNO_COLOR/FORCE_COLORand the terminal.
Environment variables:
| Variable | Effect |
|---|---|
DAEDALUS_PYTHON |
Interpreter for .py scripts (default: the interpreter running daedalus) |
DAEDALUS_BASH |
Override the bash used for .sh scripts |
DAEDALUS_LOGLEVEL |
Console log level for Python scripts (default INFO) |
DAEDALUS_NO_LOGGING |
Non-empty: Python scripts start without the daedalus logging setup |
NO_COLOR / FORCE_COLOR |
Colors on listings and console logs |
Python scripts run through daedalus/run_python_script.py: they get
REPO_ROOT on PYTHONPATH (so import daedalus.<folder> works for
shared code), file and console logging to ~/.daedalus/debug.log, and
their sys.argv and exit code passed through unchanged.
Tab completion
Completion is built with argcomplete; it completes script names, category labels, and options — including script names after category labels.
Bash: register once per shell, e.g. in ~/.bashrc (the program on
PATH must be able to import argcomplete):
eval "$(register-python-argcomplete daedalus)"
zsh:
autoload -U bashcompinit && bashcompinit
eval "$(register-python-argcomplete daedalus)"
Try it in a new shell:
daedalus hel<TAB> # completes hello
daedalus test <TAB><TAB> # lists the scripts (and labels) for the prefix
daedalus --<TAB> # completes the daedalus options
Notes:
register-python-argcompleteships with the argcomplete package; it comes with the pipx/pip install (a daedalus dependency since 0.3.0) or with your system package (Debian:python3-argcomplete).- Arguments after the script name belong to the script: a Python script
that calls
argcomplete.autocomplete(parser)(SPEC item 6.9) completes its own arguments —daedalus hello -<TAB>offers hello's-h,--help. Otherwise the shell offers file names there. - Bash scripts share
bash/daedalus_common.sh(SPEC item 6.10): the script sources it, defineshelp()andmain(), and ends withdaedalus_bash_dispatch "$@". After the script name, TAB offers--help,-h, andhelp; running one of them prints the script'shelp(). - A checkout run through
bin/daedaluscompletes when thepython3it runs canimport argcompleteand the marker comment stays in the launcher (SPEC item 3.13.7).
Add a script
- Put the file in the folder for its type:
Type Folder Python python/src/<name>/<name>.pybash bash/<name>.shPowerShell powershell/<name>.ps1Batch batch/<name>.bat(CRLF line endings, Windows only) - Register it in
SCRIPTSindaedalus/registry.py(setcategorieswhen it belongs to a group such asmediaorlinux; the default isgeneral). - Add a row to the Available scripts
table in
README.md. A test fails when a registered script is missing from that table. - Add tests under
python/tests/orbash/tests/. Python tests import the script withfrom daedalus.<name> import <name>; a newpython/src/<folder>/also needs a matchingdaedalus.<folder>entry inpyproject.toml(SPEC section 9). - Bump
versioninpyproject.toml, then rundaedalus_pipx_install(orpipx install --forcefrom the Git URL) so pipx picks up the change. - Run
python autotest.py.
Details: SPEC section 6.
Development
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
pip install -e . # daedalus command runs the checkout
python autotest.py # every check; CI runs the same
python autotest.py pytest # only some checks
autotest.py runs sanity (line endings, private keys, file size),
Python syntax, pycodestyle, shellcheck, JSON, YAML, markdown lint, and
pytest with coverage.