cordon-emit (Python)

The Python reference emitter for Cordon. Where the bash toolchain declares a surface in a DSL, a Python CLI already has an argparse parser — so you don't declare anything twice: this introspects that parser and projects it to the one Cordon v4 contract. --describe becomes a machine-readable view of the exact parser that produces --help, so the two can't drift.

Pure stdlib, zero dependencies, published to PyPI as cordon-emit on the same version as cordon. Add it as a dependency; never copy it, since a copy drifts from the schema it targets.

So easy — one line

Add the parser you already build, then one line. That's the whole integration:

import argparse
from cordon_emit import describe_main, set_effect

def build_parser():
    p = argparse.ArgumentParser(prog="hq", description="Operate the deploy.")
    sub = p.add_subparsers(dest="command")

    logs = sub.add_parser("logs", help="Show app container logs")
    logs.add_argument("-f", "--follow", action="store_true", help="Stream live output")
    set_effect(logs, "read", network=True)

    set_effect(sub.add_parser("restart", help="Restart the app"), "deploy", network=True)
    return p

def main():
    parser = build_parser()
    describe_main(parser, group="Integrations", order=130)  # ← handles --describe / --pretty, exits
    args = parser.parse_args()
    ...

Now hq --describe emits a valid contract and hq --help reads from the same parser. The only thing you add by hand is the one fact a parser can't tell you: each command's blast radius, via set_effect() on the effect ladder (read < local_write < vault_write < remote_write < deploy, plus network / interactive). Unannotated commands default to read, and the emitter warns on stderr for each one so a forgotten blast radius isn't a silent fail-open. Pass --effect-required (or effect_required=True) to make an undeclared command a hard error instead — the strict, multi-tenant posture.

So powerful — zero-touch on any parser

Don't even need to edit the tool. Point the module at any importable factory that returns an ArgumentParser (module:attribute) and pipe it straight into cordon's validator:

python -m cordon_emit myapp.cli:build_parser -g Integrations -o 130
python -m cordon_emit myapp.cli:build_parser -g X -o 1 \
  | npx --yes --package cordon-spec@2 cordon-validate -      # exit 0 = conformant

That's a contract — and a conformance check — for an existing Python CLI with no code change.

API

describe_parser returns the canonical, byte-deterministic document (no timestamps, stable order) — a guard can diff it.

Install

uv add cordon-emit

Verify

python3 emitters/python/selftest.py            # structural + byte-parity with the bash leaf fixture
python3 emitters/python/selftest.py --emit | node ../../conformance/validate.ts -

The selftest also proves convergence: introspecting an encrypt-shaped parser yields a contract byte-identical to the bash-DSL-emitted fixtures/valid/leaf-tool.json — same schema, two emitters, one output.