_cli

_render_branded_help 1 str ▼

Render help for a parser through pounce's help.kida template.

def _render_branded_help(parser: argparse.ArgumentParser) -> str

Parameters

Name	Type	Description
`parser`	`argparse.ArgumentParser`

Returns

str

_install_branded_help 1 None ▼

Patch format_help on a parser and all its subparsers to use branded templates.

def _install_branded_help(parser: argparse.ArgumentParser) -> None

Patch format_help on a parser and all its subparsers to use branded templates.

Parameters

Name	Type	Description
`parser`	`argparse.ArgumentParser`

_enrich_subparser_help 1 None ▼

Add help text to subparser arguments that milo left blank.

def _enrich_subparser_help(parser: argparse.ArgumentParser) -> None

Parameters

Name	Type	Description
`parser`	`argparse.ArgumentParser`

serve 31 None ▼

Start the ASGI server. Accepts an ASGI application reference (e.g., 'myapp:app…

def serve(app: str, config: str | None = None, host: str | None = None, port: int | None = None, workers: int | None = None, worker_mode: str | None = None, cpu_affinity: bool = False, log_level: str | None = None, log_format: str | None = None, root_path: str | None = None, no_compression: bool = False, server_timing: bool = False, no_access_log: bool = False, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, http3: bool = False, reload: bool = False, reload_include: str | None = None, reload_dir: list[str] | None = None, keep_alive_timeout: float | None = None, header_timeout: float | None = None, request_timeout: float | None = None, startup_timeout: float | None = None, max_requests_per_connection: int | None = None, shutdown_timeout: float | None = None, uds: str | None = None, health_check_path: str | None = None, app_name: str | None = None, app_tagline: str | None = None, app_version: str | None = None, signage: str | None = None) -> None

Start the ASGI server.

Accepts an ASGI application reference (e.g., 'myapp:app' or 'myapp:create_app()') and starts serving it.

Parameters

Name	Type	Description
`app`	`str`
`config`	`str \| None`	Default:`None`
`host`	`str \| None`	Default:`None`
`port`	`int \| None`	Default:`None`
`workers`	`int \| None`	Default:`None`
`worker_mode`	`str \| None`	Default:`None`
`cpu_affinity`	`bool`	Default:`False`
`log_level`	`str \| None`	Default:`None`
`log_format`	`str \| None`	Default:`None`
`root_path`	`str \| None`	Default:`None`
`no_compression`	`bool`	Default:`False`
`server_timing`	`bool`	Default:`False`
`no_access_log`	`bool`	Default:`False`
`ssl_certfile`	`str \| None`	Default:`None`
`ssl_keyfile`	`str \| None`	Default:`None`
`http3`	`bool`	Default:`False`
`reload`	`bool`	Default:`False`
`reload_include`	`str \| None`	Default:`None`
`reload_dir`	`list[str] \| None`	Default:`None`
`keep_alive_timeout`	`float \| None`	Default:`None`
`header_timeout`	`float \| None`	Default:`None`
`request_timeout`	`float \| None`	Default:`None`
`startup_timeout`	`float \| None`	Default:`None`
`max_requests_per_connection`	`int \| None`	Default:`None`
`shutdown_timeout`	`float \| None`	Default:`None`
`uds`	`str \| None`	Default:`None`
`health_check_path`	`str \| None`	Default:`None`
`app_name`	`str \| None`	Default:`None`
`app_tagline`	`str \| None`	Default:`None`
`app_version`	`str \| None`	Default:`None`
`signage`	`str \| None`	Default:`None`

_serve_impl 31 None ▼

Inner serve implementation — raises on error, no catching.

def _serve_impl(*, app: str, config: str | None, host: str | None, port: int | None, workers: int | None, log_level: str | None, log_format: str | None, root_path: str | None, no_compression: bool, server_timing: bool, no_access_log: bool, ssl_certfile: str | None, ssl_keyfile: str | None, http3: bool, reload: bool, reload_include: str | None, reload_dir: list[str] | None, keep_alive_timeout: float | None, header_timeout: float | None, request_timeout: float | None, startup_timeout: float | None, max_requests_per_connection: int | None, shutdown_timeout: float | None, uds: str | None, health_check_path: str | None, worker_mode: str | None, cpu_affinity: bool, app_name: str | None, app_tagline: str | None, app_version: str | None, signage: str | None) -> None

Parameters

Name	Type	Description
`app`	`str`
`config`	`str \| None`
`host`	`str \| None`
`port`	`int \| None`
`workers`	`int \| None`
`log_level`	`str \| None`
`log_format`	`str \| None`
`root_path`	`str \| None`
`no_compression`	`bool`
`server_timing`	`bool`
`no_access_log`	`bool`
`ssl_certfile`	`str \| None`
`ssl_keyfile`	`str \| None`
`http3`	`bool`
`reload`	`bool`
`reload_include`	`str \| None`
`reload_dir`	`list[str] \| None`
`keep_alive_timeout`	`float \| None`
`header_timeout`	`float \| None`
`request_timeout`	`float \| None`
`startup_timeout`	`float \| None`
`max_requests_per_connection`	`int \| None`
`shutdown_timeout`	`float \| None`
`uds`	`str \| None`
`health_check_path`	`str \| None`
`worker_mode`	`str \| None`
`cpu_affinity`	`bool`
`app_name`	`str \| None`
`app_tagline`	`str \| None`
`app_version`	`str \| None`
`signage`	`str \| None`

_die 5 None ▼

Render a branded error and exit. ``code`` is a semantic ``POUNCE__`` identifie…

def _die(message: str, *, hint: str | None = None, code: str | None = None, doc: str | None = None, diagnostics: list[dict[str, str]] | None = None) -> None

Render a branded error and exit.

code is a semantic POUNCE_<CATEGORY>_<SPECIFIC> identifier; doc is the troubleshooting anchor (e.g.docs/troubleshooting.md#POUNCE_X_Y). Both are surfaced through_output.error to error.kidafor rendering and let an agent reading stderr navigate from a failure to its catalog entry without grepping.

Parameters

Name	Type	Description
`message`	`str`
`hint`	`str \| None`	Default:`None`
`code`	`str \| None`	Default:`None`
`doc`	`str \| None`	Default:`None`
`diagnostics`	`list[dict[str, str]] \| None`	Default:`None`

_hint_for_import_error 1 str | None ▼

Return a hint for common import/app-path errors.

def _hint_for_import_error(exc: Exception) -> str | None

Parameters

Name	Type	Description
`exc`	`Exception`

Returns

str | None

_diagnostics_for_import_error 1 list[dict[str, str]] | N… ▼

Return diagnostic context for import errors.

def _diagnostics_for_import_error(exc: Exception) -> list[dict[str, str]] | None

Parameters

Name	Type	Description
`exc`	`Exception`

Returns

list[dict[str, str]] | None

_hint_for_os_error 1 str | None ▼

Return a hint for common OS-level errors.

def _hint_for_os_error(exc: OSError) -> str | None

Parameters

Name	Type	Description
`exc`	`OSError`

Returns

str | None

_diagnostics_for_os_error 1 list[dict[str, str]] | N… ▼

Return diagnostic context for OS errors (e.g. who holds the port).

def _diagnostics_for_os_error(exc: OSError) -> list[dict[str, str]] | None

Parameters

Name	Type	Description
`exc`	`OSError`

Returns

list[dict[str, str]] | None

_hint_for_pounce_error 1 str | None ▼

Return a hint for pounce-specific errors.

def _hint_for_pounce_error(exc: Exception) -> str | None

Parameters

Name	Type	Description
`exc`	`Exception`

Returns

str | None

parse_extensions 1 tuple[str, ...] ▼

Parse a comma-separated extensions string into a normalized tuple. Ensures eac…

def parse_extensions(raw: str | None) -> tuple[str, ...]

Parse a comma-separated extensions string into a normalized tuple.

Ensures each extension starts with a dot and strips whitespace. Empty entries are filtered out.

Parameters

Name	Type	Description
`raw`	`str \| None`	Comma-separated string (e.g.`".html,.css,md"`), or None.

Returns

tuple[str, ...]

parse_dirs 1 tuple[str, ...] ▼

Parse a list of directory strings into a cleaned tuple. Strips whitespace and …

def parse_dirs(raw: list[str] | None) -> tuple[str, ...]

Parse a list of directory strings into a cleaned tuple.

Strips whitespace and filters empty entries.

Parameters

Name	Type	Description
`raw`	`list[str] \| None`	List of directory paths, or None.

Returns

tuple[str, ...]

info 0 None ▼

Display system info, dependency status, and environment diagnostics.

def info() -> None

check 31 None ▼

Run pre-flight validation checks. Takes the same arguments as ``serve`` and va…

def check(app: str, config: str | None = None, host: str | None = None, port: int | None = None, workers: int | None = None, worker_mode: str | None = None, cpu_affinity: bool = False, log_level: str | None = None, log_format: str | None = None, root_path: str | None = None, no_compression: bool = False, server_timing: bool = False, no_access_log: bool = False, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, http3: bool = False, reload: bool = False, reload_include: str | None = None, reload_dir: list[str] | None = None, keep_alive_timeout: float | None = None, header_timeout: float | None = None, request_timeout: float | None = None, startup_timeout: float | None = None, max_requests_per_connection: int | None = None, shutdown_timeout: float | None = None, uds: str | None = None, health_check_path: str | None = None, app_name: str | None = None, app_tagline: str | None = None, app_version: str | None = None, signage: str | None = None) -> None

Run pre-flight validation checks.

Takes the same arguments asserveand validates them without starting the server. Exits with code 1 if any check fails.

Parameters

Name	Type	Description
`app`	`str`
`config`	`str \| None`	Default:`None`
`host`	`str \| None`	Default:`None`
`port`	`int \| None`	Default:`None`
`workers`	`int \| None`	Default:`None`
`worker_mode`	`str \| None`	Default:`None`
`cpu_affinity`	`bool`	Default:`False`
`log_level`	`str \| None`	Default:`None`
`log_format`	`str \| None`	Default:`None`
`root_path`	`str \| None`	Default:`None`
`no_compression`	`bool`	Default:`False`
`server_timing`	`bool`	Default:`False`
`no_access_log`	`bool`	Default:`False`
`ssl_certfile`	`str \| None`	Default:`None`
`ssl_keyfile`	`str \| None`	Default:`None`
`http3`	`bool`	Default:`False`
`reload`	`bool`	Default:`False`
`reload_include`	`str \| None`	Default:`None`
`reload_dir`	`list[str] \| None`	Default:`None`
`keep_alive_timeout`	`float \| None`	Default:`None`
`header_timeout`	`float \| None`	Default:`None`
`request_timeout`	`float \| None`	Default:`None`
`startup_timeout`	`float \| None`	Default:`None`
`max_requests_per_connection`	`int \| None`	Default:`None`
`shutdown_timeout`	`float \| None`	Default:`None`
`uds`	`str \| None`	Default:`None`
`health_check_path`	`str \| None`	Default:`None`
`app_name`	`str \| None`	Default:`None`
`app_tagline`	`str \| None`	Default:`None`
`app_version`	`str \| None`	Default:`None`
`signage`	`str \| None`	Default:`None`

_check_app_importable 1 dict[str, str] ▼

Try to import the app and return a check result.

def _check_app_importable(app: str) -> dict[str, str]

Parameters

Name	Type	Description
`app`	`str`

Returns

dict[str, str]

_check_port_available 2 dict[str, str] ▼

Try to bind the port and return a check result.

def _check_port_available(host: str, port: int) -> dict[str, str]

Parameters

Name	Type	Description
`host`	`str`
`port`	`int`

Returns

dict[str, str]

_check_tls_cert 2 dict[str, str] ▼

Validate TLS certificate file exists and is loadable.

def _check_tls_cert(certfile: str, keyfile: str | None = None) -> dict[str, str]

Parameters

Name	Type	Description
`certfile`	`str`
`keyfile`	`str \| None`	Default:`None`

Returns

dict[str, str]

_check_deps_for_config 2 list[dict[str, str]] ▼

Check that optional deps are installed for requested features.

def _check_deps_for_config(*, http3: bool, ssl_certfile: str | None) -> list[dict[str, str]]

Parameters

Name	Type	Description
`http3`	`bool`
`ssl_certfile`	`str \| None`

Returns

list[dict[str, str]]

_check_config_valid 25 dict[str, str] ▼

Try to construct ServerConfig and catch validation errors.

def _check_config_valid(*, host: str, port: int, workers: int, worker_mode: str, cpu_affinity: bool, log_level: str, log_format: str, root_path: str, no_compression: bool, server_timing: bool, no_access_log: bool, ssl_certfile: str | None, ssl_keyfile: str | None, http3: bool, reload: bool, reload_include: str | None, reload_dir: list[str] | None, keep_alive_timeout: float, header_timeout: float, request_timeout: float, startup_timeout: float, max_requests_per_connection: int, shutdown_timeout: float, uds: str | None, health_check_path: str | None) -> dict[str, str]

Parameters

Name	Type	Description
`host`	`str`
`port`	`int`
`workers`	`int`
`worker_mode`	`str`
`cpu_affinity`	`bool`
`log_level`	`str`
`log_format`	`str`
`root_path`	`str`
`no_compression`	`bool`
`server_timing`	`bool`
`no_access_log`	`bool`
`ssl_certfile`	`str \| None`
`ssl_keyfile`	`str \| None`
`http3`	`bool`
`reload`	`bool`
`reload_include`	`str \| None`
`reload_dir`	`list[str] \| None`
`keep_alive_timeout`	`float`
`header_timeout`	`float`
`request_timeout`	`float`
`startup_timeout`	`float`
`max_requests_per_connection`	`int`
`shutdown_timeout`	`float`
`uds`	`str \| None`
`health_check_path`	`str \| None`

Returns

dict[str, str]

_check_merged_config_valid 1 dict[str, str] ▼

Try to construct ServerConfig from merged config dict and catch validation erro…

def _check_merged_config_valid(merged: dict[str, object]) -> dict[str, str]

Try to construct ServerConfig from merged config dict and catch validation errors.

Parameters

Name	Type	Description
`merged`	`dict[str, object]`

Returns

dict[str, str]

_check_signage 1 dict[str, str] ▼

Validate signage value.

def _check_signage(signage: str) -> dict[str, str]

Parameters

Name	Type	Description
`signage`	`str`

Returns

dict[str, str]

init 2 None ▼

Write ``app.py``, ``pounce.toml``, and ``.gitignore`` into *directory* (current…

def init(directory: str | None = None, force: bool = False) -> None

Writeapp.py, pounce.toml, and .gitignoreinto directory (current working directory by default).

Refuses to overwrite existing scaffold files unless--forceis set. Intended for fresh directories — real projects already have their own app and config.

Parameters

Name	Type	Description
`directory`	`str \| None`	Default:`None`
`force`	`bool`	Default:`False`

config_schema 1 None ▼

Print a machine-readable description of every ServerConfig field. ``--output-f…

def config_schema(output_format: str = 'json') -> None

Print a machine-readable description of every ServerConfig field.

--output-format json(default) emits a JSON Schema Draft 2020-12 document with types, defaults, and enum constraints. --output-format toml-template emits a commented pounce.toml skeleton ready to uncomment and edit.

Parameters

Name	Type	Description
`output_format`	`str`	Default:`'json'`

config_show 5 None ▼

Print the active ServerConfig through the Sprint 0.3 redaction allowlist. ``co…

def config_show(config: str | None = None, output_format: str = 'toml', host: str | None = None, port: int | None = None, workers: int | None = None) -> None

Print the active ServerConfig through the Sprint 0.3 redaction allowlist.

config showmerges TOML, defaults, and its limited display overrides (host, port, and workers). It is not a full mirror of every serveflag.

Secrets and filesystem paths are never printed — fields classified as REDACT_TO_BOOL appear as <name>_set = true|false, and fields outside the allowlist are omitted entirely.

Parameters

Name	Type	Description
`config`	`str \| None`	Default:`None`
`output_format`	`str`	Default:`'toml'`
`host`	`str \| None`	Default:`None`
`port`	`int \| None`	Default:`None`
`workers`	`int \| None`	Default:`None`

main 1 None ▼

Entry point for the ``pounce`` CLI command.

def main(args: list[str] | None = None) -> None

Parameters

Name	Type	Description
`args`	`list[str] \| None`	Command-line arguments (defaults to sys.argv[1:]). Default:`None`

Classes

Methods

Returns

Functions

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

`_cli`