Skip to main content

pyclisteno

A learned shortcut and hint layer for Python CLIs built on Click or Typer.

Stenography compresses language by rule rather than by lookup table, which is why trained stenographers reach speed without memorizing a second vocabulary. clisteno does the same thing to a command tree: each level contributes a prefix of its own name and they run together into one stroke, so dectl saglsoru is dectl salesdata glue source-copy run with less of it, not an alias that has to be learned separately.

What it provides

Two surfaces over one model, each independently opt-in:

  • Teaching — the short form and its description shown beside the long form in help output, so ordinary use trains the fast path.
  • Compression — a resolver that expands a prefix sequence into the full command.

attach also keeps a flat index in the cache, whichever surfaces are on. It holds one line per published sequence: the sequence, the full command and its summary, separated by tabs. The index is for a shell widget, such as a completion or a suggestion, to read on every keystroke. A shell reads a TSV with no subprocess, where parsing JSON would cost one per keystroke. The library ships no shell code that reads it.

Attaching it

Enrollment is one call after the command tree is complete. It is not a decorator on each command, because a tree assembled at runtime from config has no functions to decorate:

from pyclisteno import attach

app = typer.Typer()
# ... build the tree, including anything driven by config ...
attach(app)

Removing the library is deleting those two lines. Nothing about the CLI changes: with attach() as written above, stdout, stderr and exit codes are byte-identical without it, at every level of the tree and for every --help, which the test suite asserts rather than assumes.

Teaching is the one surface that changes what a CLI prints, so it is asked for explicitly:

attach(app, teaching=True)

Each row in a parent's help then carries the short form of the command it names.

run      (ru) Run the thing, and keep running it until something says otherwise.
runs     List previous runs.
destroy  Delete everything, permanently and without confirmation.

destroy shows no short form because of @no_shortcut below. runs shows none for a different reason: run is a strict prefix of it, so its own sequence is runs, and a sequence that is already a command name is withheld — typing it should reach that command, not be reinterpreted.

Compression is the other half, and the half that makes the offer true: without it the short form is advice the tool would reject.

attach(app, teaching=True, expanding=True)

expanding rewrites a typed sequence into the command it stands for before the CLI parses it, so tool exgsr runs tool example-pipeline glue source-copy run. The whole sequence is matched before the per-token walk, because exgsr also starts with ex and the walk alone would answer it with example-pipeline and drop the rest. It is the only surface that can make a CLI run something other than what was typed, so it declines wherever it is not certain: an unknown token, a retired sequence, or anything after a leading option is passed through untouched for the CLI itself to answer. A real command name expands to itself, because a name starts with its own prefix and no sibling's can outmatch it.

Decorators exist only for exceptions:

@app.command()
@shortcut('ru')  # pin, rather than accept the computed prefix
def run(): ...


@app.command()
@no_shortcut  # keep a destructive verb off the fast path
def destroy(): ...

How prefixes are assigned

Each node gets the shortest prefix of its own name that is unambiguous among its siblings, so run and review become ru and re, and a command's sequence is its ancestors' prefixes and its own run together. Two paths that run together into the same string are published by neither, since nothing could tell which one was meant. Assignments are recorded and grandfathered: once a prefix has been handed out it is never shortened, lengthened, or reassigned, because the whole point is protecting a sequence already in someone's fingers. Resolution is longest-match, which is what lets an incumbent r coexist with a later re. A removed command's prefix is retired permanently rather than recycled — a recycled sequence still works and silently does something else, which is the worst failure available here.

Where it keeps things

Path What Class
$XDG_CONFIG_HOME/<tool>/clisteno-shortcuts.toml User pins Config — you write it, nothing else does
$XDG_STATE_HOME/clisteno/<tool>.json The assignment ledger State — synced, so a sequence means the same thing on every machine
$XDG_CACHE_HOME/clisteno/<tool>.json The grammar model Cache
$XDG_CACHE_HOME/clisteno/<tool>.tsv Flat index for the shell Cache

The config file sits beside the tool's own config and is never merged into it, so the tool never parses shortcuts and never needs to know this library exists. Its keys are node paths and its values are that node's prefix at its own level, which is also how the ledger is keyed:

[shortcuts]
run = "ru"
"glue nightly" = "ni"

A pin that is unusable — not a prefix of the command's own name, or already spoken for — is dropped and the prefix computed as if it were absent. Nothing in that file can stop the CLI starting, including a syntax error in it.

The files are written for other languages to share

The model, the index, the ledger and the pin file carry nothing specific to Python. A library in another language could implement the same assignment and read and write the same files, so one shell widget would serve CLIs written in either. The model's schema field versions the node fields and the index columns. pyclisteno.fixture is a deliberately hostile command tree, shipped in the package, for such an implementation to test against. Importing it needs typer.

Metadata

Release files for pyclisteno 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyclisteno 0.8.1
File Size Uploaded Provenance Actions
pyclisteno-0.8.1.tar.gz 23.4 kB Without provenance Details for pyclisteno-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyclisteno 0.8.1
File Interpreter ABI Platform Actions
pyclisteno-0.8.1-py3-none-any.whl Python 3 none any Details for pyclisteno-0.8.1-py3-none-any.whl

Total release size: 52.0 kB

Release files / pyclisteno-0.8.1.tar.gz

Download URL pyclisteno-0.8.1.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
eff43ab1ccb70124b2fe37888dc598e28b5c29c66b09a75a07ceaa05f67643f1
BLAKE2b-256 checksum
How to use checksums
9ee0208f82a3305a80698f1ea2942aba4b2223a7cf12980e8c05a2cb34f2bf95
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pyclisteno-0.8.1-py3-none-any.whl

Download URL pyclisteno-0.8.1-py3-none-any.whl
Size 28.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
65cf71a4c1a143dfa9c035cc12c061afddbc06b7c47aaabfcd524d56372925c5
BLAKE2b-256 checksum
How to use checksums
ae93839899c83dad0fa1bbcad551cff8f162f940f9d1780c896e528bdacb13e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pyclisteno 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page