_cli

_render_help_state 1 str ▼

Render Milo help metadata through Pounce's branded template.

def _render_help_state(state: HelpState) -> str

Parameters

Name	Type	Description
`state`	`HelpState`

Returns

str

_render_plain_help 1 str ▼

Render dependency-free plain help when the branded template fails.

def _render_plain_help(state: HelpState) -> str

Parameters

Name	Type	Description
`state`	`HelpState`

Returns

str

_write_help 1 None ▼

Write one complete help report to stdout.

def _write_help(state: HelpState) -> None

Parameters

Name	Type	Description
`state`	`HelpState`

_config_epilog_for 1 str ▼

Return the TOML escape-hatch footer for serve/check help.

def _config_epilog_for(prog: str) -> str

Parameters

Name	Type	Description
`prog`	`str`

Returns

str

serve 36 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, no_http2: bool = False, 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, write_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, debug: bool = False, trusted_hosts: str | None = None, metrics: bool = False, 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`	ASGI application (e.g.,`myapp:app` or `myapp:create_app()`).
`config`	`str \| None`	Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None`
`host`	`str \| None`	Bind address. Default:`None`
`port`	`int \| None`	Bind port. Default:`None`
`workers`	`int \| None`	Number of workers; zero selects the automatic default. Default:`None`
`worker_mode`	`str \| None`	Worker model: auto, sync, async, or subinterpreter. Default:`None`
`cpu_affinity`	`bool`	Pin each worker to a CPU core on Linux. Default:`False`
`log_level`	`str \| None`	Log level. Default:`None`
`log_format`	`str \| None`	Log format: auto, text, or json. Default:`None`
`root_path`	`str \| None`	ASGI root path for reverse-proxy setups. Default:`None`
`no_compression`	`bool`	Disable response compression. Default:`False`
`server_timing`	`bool`	Enable Server-Timing header injection. Default:`False`
`no_access_log`	`bool`	Disable access logging. Default:`False`
`ssl_certfile`	`str \| None`	TLS certificate path; enables HTTPS. Default:`None`
`ssl_keyfile`	`str \| None`	TLS private-key path. Default:`None`
`no_http2`	`bool`	Disable h2 ALPN advertisement and force HTTP/1.1 at the origin. Default:`False`
`http3`	`bool`	Enable HTTP/3; requires TLS and the h3 extra. Default:`False`
`reload`	`bool`	Reload automatically when source files change. Default:`False`
`reload_include`	`str \| None`	Extra file extensions to watch, comma-separated. Default:`None`
`reload_dir`	`list[str] \| None`	Extra directories to watch; may be repeated. Default:`None`
`keep_alive_timeout`	`float \| None`	Idle keep-alive timeout in seconds. Default:`None`
`header_timeout`	`float \| None`	Header receive timeout in seconds. Default:`None`
`request_timeout`	`float \| None`	Request-body receive timeout in seconds. Default:`None`
`write_timeout`	`float \| None`	Blocked response-write timeout in seconds. Default:`None`
`startup_timeout`	`float \| None`	Maximum lifespan-startup wait in seconds. Default:`None`
`max_requests_per_connection`	`int \| None`	Requests per connection; zero is unlimited. Default:`None`
`shutdown_timeout`	`float \| None`	Maximum worker-shutdown wait in seconds. Default:`None`
`uds`	`str \| None`	Unix domain socket path. Default:`None`
`health_check_path`	`str \| None`	Built-in readiness endpoint path. Default:`None`
`debug`	`bool`	Enable rich error pages; never enable in production. Default:`False`
`trusted_hosts`	`str \| None`	Trusted proxy hostnames, comma-separated. Default:`None`
`metrics`	`bool`	Enable the Prometheus metrics endpoint. Default:`False`
`app_name`	`str \| None`	Application name displayed in the startup banner. Default:`None`
`app_tagline`	`str \| None`	Short description displayed below the application name. Default:`None`
`app_version`	`str \| None`	Application version displayed in the startup banner. Default:`None`
`signage`	`str \| None`	Banner layout: full, minimal, or off. Default:`None`

_serve_impl 36 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, no_http2: bool, 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, write_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, debug: bool, trusted_hosts: str | None, metrics: bool, 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`
`no_http2`	`bool`
`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`
`write_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`
`debug`	`bool`
`trusted_hosts`	`str \| None`
`metrics`	`bool`
`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, ...]

parse_hosts 1 tuple[str, ...] ▼

Parse a comma-separated host list into a normalized tuple.

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

Parameters

Name	Type	Description
`raw`	`str \| None`	Comma-separated hostnames (e.g.`"localhost,127.0.0.1"`), or None.

Returns

tuple[str, ...]

info 1 None ▼

Display system info, dependency status, and environment diagnostics. Pass ``--…

def info(output_format: str = 'text') -> None

Display system info, dependency status, and environment diagnostics.

Pass--output-format jsonfor a stable, machine-readable dict suitable forpounce info --output-format json | jq.

Parameters

Name	Type	Description
`output_format`	`str`	Output format: text or json. Default:`'text'`

check 36 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, no_http2: bool = False, 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, write_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, debug: bool = False, trusted_hosts: str | None = None, metrics: bool = False, 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`	ASGI application (e.g.,`myapp:app` or `myapp:create_app()`).
`config`	`str \| None`	Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None`
`host`	`str \| None`	Bind address. Default:`None`
`port`	`int \| None`	Bind port. Default:`None`
`workers`	`int \| None`	Number of workers; zero selects the automatic default. Default:`None`
`worker_mode`	`str \| None`	Worker model: auto, sync, async, or subinterpreter. Default:`None`
`cpu_affinity`	`bool`	Pin each worker to a CPU core on Linux. Default:`False`
`log_level`	`str \| None`	Log level. Default:`None`
`log_format`	`str \| None`	Log format: auto, text, or json. Default:`None`
`root_path`	`str \| None`	ASGI root path for reverse-proxy setups. Default:`None`
`no_compression`	`bool`	Disable response compression. Default:`False`
`server_timing`	`bool`	Enable Server-Timing header injection. Default:`False`
`no_access_log`	`bool`	Disable access logging. Default:`False`
`ssl_certfile`	`str \| None`	TLS certificate path; enables HTTPS. Default:`None`
`ssl_keyfile`	`str \| None`	TLS private-key path. Default:`None`
`no_http2`	`bool`	Disable h2 ALPN advertisement and force HTTP/1.1 at the origin. Default:`False`
`http3`	`bool`	Enable HTTP/3; requires TLS and the h3 extra. Default:`False`
`reload`	`bool`	Reload automatically when source files change. Default:`False`
`reload_include`	`str \| None`	Extra file extensions to watch, comma-separated. Default:`None`
`reload_dir`	`list[str] \| None`	Extra directories to watch; may be repeated. Default:`None`
`keep_alive_timeout`	`float \| None`	Idle keep-alive timeout in seconds. Default:`None`
`header_timeout`	`float \| None`	Header receive timeout in seconds. Default:`None`
`request_timeout`	`float \| None`	Request-body receive timeout in seconds. Default:`None`
`write_timeout`	`float \| None`	Blocked response-write timeout in seconds. Default:`None`
`startup_timeout`	`float \| None`	Maximum lifespan-startup wait in seconds. Default:`None`
`max_requests_per_connection`	`int \| None`	Requests per connection; zero is unlimited. Default:`None`
`shutdown_timeout`	`float \| None`	Maximum worker-shutdown wait in seconds. Default:`None`
`uds`	`str \| None`	Unix domain socket path. Default:`None`
`health_check_path`	`str \| None`	Built-in readiness endpoint path. Default:`None`
`debug`	`bool`	Enable rich error pages; never enable in production. Default:`False`
`trusted_hosts`	`str \| None`	Trusted proxy hostnames, comma-separated. Default:`None`
`metrics`	`bool`	Enable the Prometheus metrics endpoint. Default:`False`
`app_name`	`str \| None`	Application name displayed in the startup banner. Default:`None`
`app_tagline`	`str \| None`	Short description displayed below the application name. Default:`None`
`app_version`	`str \| None`	Application version displayed in the startup banner. Default:`None`
`signage`	`str \| None`	Banner layout: full, minimal, or off. 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 27 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, no_http2: bool, http3: bool, reload: bool, reload_include: str | None, reload_dir: list[str] | None, keep_alive_timeout: float, header_timeout: float, request_timeout: float, write_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`
`no_http2`	`bool`
`http3`	`bool`
`reload`	`bool`
`reload_include`	`str \| None`
`reload_dir`	`list[str] \| None`
`keep_alive_timeout`	`float`
`header_timeout`	`float`
`request_timeout`	`float`
`write_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`	Target directory; defaults to the current directory. Default:`None`
`force`	`bool`	Overwrite existing scaffold files. 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`	Output format: json or toml-template. 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`	Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None`
`output_format`	`str`	Output format: toml or json. Default:`'toml'`
`host`	`str \| None`	Override the displayed bind address. Default:`None`
`port`	`int \| None`	Override the displayed bind port. Default:`None`
`workers`	`int \| None`	Override the displayed worker count. 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

Functions

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

`_cli`