Module

context

Execution context for CLI command handlers.

5Classes2Functions

Classes

OutputSink 2 ▼
Minimal text destination used by Context diagnostics and progress.

Minimal text destination used by Context diagnostics and progress.

Methods

write 1 int | None ▼
Write text and optionally return the number of characters consumed.
def write(self, data: str, /) -> int | None
Parameters
Name Type Description
data —
Returns
int | None
flush 0 ▼
Flush buffered text.
def flush(self) -> None
ConfirmStrategy 1 ▼
Host-provided approval policy for `confirm`().

Host-provided approval policy forconfirm().

Methods

Internal Methods 1 ▼
__call__ 2 bool ▼
Return whether the named action is approved.
def __call__(self, message: str, *, default: bool = False) -> bool
Parameters
Name Type Description
message —
default — Default:False
Returns
bool
NullOutputSink 2 ▼
Output sink that intentionally discards all text.

Output sink that intentionally discards all text.

Methods

write 1 int ▼
Discard *data* while honoring the text sink contract.
def write(self, data: str, /) -> int
Parameters
Name Type Description
data —
Returns
int
flush 0 ▼
No-op because this sink never buffers output.
def flush(self) -> None
Context 27 ▼
Execution context available to all command handlers. Handlers opt in by adding a ``ctx: Context`` …

Execution context available to all command handlers.

Handlers opt in by adding actx: Contextparameter::

@cli.command("build", description="Build the site")
def build(output: str = "_site", ctx: Context = None) -> str:
    ctx.log("Starting build...", level=1)  # verbose only
    return f"Built to {output}"

The context is injected automatically by the CLI dispatcher and excluded from argparse and MCP schemas.

Attributes

Name Type Description
verbosity int —
format str —
color bool —
dry_run bool —
output_file str —
globals dict[str, Any] —
output_sink OutputSink | None —
interactive bool | None —
confirm_strategy ConfirmStrategy | None —

Methods

quiet 0 bool ▼
True when --quiet was passed.
property
def quiet(self) -> bool
Returns
bool
verbose 0 bool ▼
True when --verbose was passed.
property
def verbose(self) -> bool
Returns
bool
debug 0 bool ▼
True when -vv (or higher) was passed.
property
def debug(self) -> bool
Returns
bool
is_ci 0 bool ▼
True when running in CI (CI env var is set).
property
def is_ci(self) -> bool
Returns
bool
is_interactive 0 bool ▼
Return the configured host policy or current stdin TTY state.
property
def is_interactive(self) -> bool
Returns
bool
log 2 ▼
Print a message if verbosity is at or above *level*. level 0 = normal (always …
def log(self, message: str, *, level: int = 0) -> None

Print a message if verbosity is at or above level.

level 0 = normal (always shown unless quiet) level 1 = verbose (shown with --verbose) level 2 = debug (shown with -vv)

Parameters
Name Type Description
message —
level — Default:0
info 1 ▼
Print an informational message (level 0).
def info(self, message: str) -> None
Parameters
Name Type Description
message —
success 1 ▼
Print a success message (level 0).
def success(self, message: str) -> None
Parameters
Name Type Description
message —
warning 1 ▼
Print a warning message (always shown, even in quiet mode).
def warning(self, message: str) -> None
Parameters
Name Type Description
message —
error 1 ▼
Print an error message (always shown).
def error(self, message: str) -> None
Parameters
Name Type Description
message —
confirm 2 bool ▼
Prompt for yes/no confirmation. Returns default in non-interactive mode. In dr…
def confirm(self, message: str, *, default: bool = False) -> bool

Prompt for yes/no confirmation. Returns default in non-interactive mode.

In dry-run mode, returns default (does not prompt).

Parameters
Name Type Description
message —
default — Default:False
Returns
bool
write_file 3 bool ▼
Write *content* to *path*, respecting ``--dry-run``. Returns True if the file …
def write_file(self, path: str, content: str, *, encoding: str = 'utf-8') -> bool

Write content to path, respecting--dry-run.

Returns True if the file was written, False if skipped due to dry-run.

Parameters
Name Type Description
path —
content —
encoding — Default:'utf-8'
Returns
bool
run_command 2 Any ▼
Run a subprocess, respecting ``--dry-run``. In dry-run mode, logs the command …
def run_command(self, cmd: list[str], **kwargs: Any) -> Any

Run a subprocess, respecting--dry-run.

In dry-run mode, logs the command and returns None without executing. Otherwise, delegates torun() with the given kwargs.

Parameters
Name Type Description
cmd —
**kwargs —
Returns
Any
progress 2 CLIProgress ▼
Create an inline progress indicator for CLI commands. Usage:: with ctx.pr…
def progress(self, total: int = 0, *, label: str = '') -> CLIProgress

Create an inline progress indicator for CLI commands.

Usage::

with ctx.progress(total=100, label="Downloading") as p:
    for i in range(100):
        do_work()
        p.update(1)
Parameters
Name Type Description
total — Default:0
label — Default:''
Returns
CLIProgress
render 3 str ▼
Render a kida template and return the result string. Convenience method for co…
def render(self, template: str, *, env: Any = None, **kwargs: Any) -> str

Render a kida template and return the result string.

Convenience method for commands that need styled template output without the full App event loop::

@cli.command("report", description="Show report")
def report(ctx: Context = None) -> str:
    data = [{"name": "Alice", "score": 95}]
    return ctx.render("report.kida", items=data)

Inline templates are supported with thestring:prefix::

ctx.render("string:{{ x | bold }}", x="hello")
Parameters
Name Type Description
template —

Template name (e.g."report.kida") or an inline template prefixed with "string:".
env —

Optional pre-configured kida Environment. **kwargs: Template context variables.

Default:None
**kwargs —
Returns
str Rendered string.
run_app 6 Any ▼
Launch an interactive App session and return the final state. Bridges CLI comm…
def run_app(self, reducer: Callable, template: str, initial_state: Any = None, *, env: Any = None, exit_template: str = '', tick_rate: float = 0.0) -> Any

Launch an interactive App session and return the final state.

Bridges CLI command handlers to the Elm-style App event loop. The command blocks until the user quits the App, then returns the final state for the handler to process further.

Usage in a CLI command::

@cli.command("pick", description="Pick a file")
def pick(directory: str = ".", ctx: Context = None) -> str:
    state = ctx.run_app(
        reducer=picker_reducer,
        template="picker.kida",
        initial_state=PickerState(root=directory),
        env=env,
    )
    return state.selected_file
Parameters
Name Type Description
reducer —
template —
initial_state — Default:None
env — Default:None
exit_template — Default:''
tick_rate — Default:0.0
Returns
Any
Internal Methods 2 ▼
_output 0 OutputSink ▼
Resolve the configured sink without capturing stderr at construction.
property
def _output(self) -> OutputSink
Returns
OutputSink
_write_output 1 ▼
Write and flush one diagnostic fragment through the active sink.
def _write_output(self, message: str) -> None
Parameters
Name Type Description
message —
CLIProgress 7 ▼
Inline progress bar for CLI commands.

Inline progress bar for CLI commands.

Methods

update 1 ▼
Advance progress by n steps.
def update(self, n: int = 1) -> None
Parameters
Name Type Description
n — Default:1
set 1 ▼
Set progress to an absolute value.
def set(self, n: int) -> None
Parameters
Name Type Description
n —
Internal Methods 5 ▼
_output 0 OutputSink ▼
Resolve the sink lazily for direct CLIProgress construction.
property
def _output(self) -> OutputSink
Returns
OutputSink
__init__ 5 ▼
def __init__(self, *, total: int = 0, label: str = '', color: bool = True, quiet: bool = False, output_sink: OutputSink | None = None) -> None
Parameters
Name Type Description
total — Default:0
label — Default:''
color — Default:True
quiet — Default:False
output_sink — Default:None
_write_output 1 ▼
Write and flush progress through the active sink.
def _write_output(self, message: str) -> None
Parameters
Name Type Description
message —
__enter__ 0 CLIProgress ▼
def __enter__(self) -> CLIProgress
Returns
CLIProgress
__exit__ 1 ▼
def __exit__(self, *exc: object) -> None
Parameters
Name Type Description
*exc —

Functions

get_context 0 Context ▼
Get the current execution context. Returns a default Context if none has been …
def get_context() -> Context

Get the current execution context.

Returns a default Context if none has been set.

Returns
Context
set_context 1 None ▼
Set the current execution context.
def set_context(ctx: Context) -> None
Parameters
Name Type Description
ctx Context