explosion/radicli

Purpose and Public Entry Points

radicli is a Python 3.8+ zero-dependency library for declaring argparse CLIs directly from typed Python functions. Its public API is exported from radicli/__init__.py; primary runtime classes and decorators are implemented in radicli/cli.py. Consumer applications instantiate Radicli, register functions with decorators, then invoke run() or call().

Command Registration and Internal Model

Radicli maintains registries of top-level commands and one-level subcommands. Decorators convert function signatures, annotations, defaults, docstrings, and optional Arg metadata into a structured Command representation. Placeholder parent commands support subcommand-only groups.

• radicli/cli.py

• radicli/parser.py

Type-Driven Argument Construction

The parser layer translates Command argument metadata into argparse definitions. Function type hints control coercion and validation for primitives, booleans, lists, literals, enums, unions/optionals, and registered custom types. Per-argument converters override type-derived conversion; global converters are selected by exact generic type or origin.

• radicli/parser.py

• radicli/util.py

• radicli/cli.py

Runtime Dispatch and Error Boundary

Radicli.run() reads sys.argv (or supplied args), resolves a command/subcommand, parses values, and invokes the original function with keyword arguments. Commands allowing extras preserve unrecognized tokens under a configurable parameter name. Exceptions remain normal Python exceptions for direct invocation, but CLI dispatch can map configured exception classes to presentation/exit handlers.

• radicli/cli.py

• radicli/parser.py

Built-In Conversion Utilities

Reusable utility types and converters provide filesystem validation, path-or-stdin conventions, UUID handling, and list-converter construction. These are a boundary between raw CLI strings and application-level typed inputs, while retaining a standard-library-only runtime.

• radicli/util.py

• radicli/__init__.py

Static CLI Fast Path

A live CLI can serialize command topology and argument metadata to JSON. StaticRadicli loads that representation and performs help rendering plus basic command/argument validation before expensive application imports. It exits for help or invalid input; otherwise callers proceed to import and execute the live CLI for conversion and function execution.

• radicli/static.py

• radicli/cli.py

• radicli/parser.py

Documentation and Distribution

Markdown CLI documentation is generated from the same command model, preventing a separate documentation schema. The package is distributed as a typed Python library via setuptools configuration; CI tests and publishes releases through GitHub Actions. There are no runtime external services or infrastructure dependencies beyond Python’s standard library and argparse.

• radicli/document.py

• pyproject.toml

• setup.py

• .github/workflows/publish.yml