Module

_cli

Command-line interface for pounce.

Provides thepouncecommand with subcommands::

pounce serve --app myapp:app --host 0.0.0.0 --port 8000 --workers 4

Built on milo-cli for type-driven parsing, MCP server, and llms.txt generation.

1Class21Functions

Classes

_PounceCLI 1 ▼
CLI subclass that enables branded help output.

CLI subclass that enables branded help output.

Methods

build_parser 0 argparse.ArgumentParser ▼
def build_parser(self) -> argparse.ArgumentParser
Returns
argparse.ArgumentParser

Functions

_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 24 None ▼
Start the ASGI server. Accepts an ASGI application reference (e.g., 'myapp:app…
def serve(app: str, host: str = '127.0.0.1', port: int = 8000, workers: int = 1, worker_mode: str = 'auto', cpu_affinity: bool = False, log_level: str = 'info', log_format: str = 'auto', root_path: str = '', 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 = 5.0, header_timeout: float = 10.0, max_requests_per_connection: int = 0, shutdown_timeout: float = 10.0, uds: str | None = None, health_check_path: 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
host str Default:'127.0.0.1'
port int Default:8000
workers int Default:1
worker_mode str Default:'auto'
cpu_affinity bool Default:False
log_level str Default:'info'
log_format str Default:'auto'
root_path str Default:''
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 Default:5.0
header_timeout float Default:10.0
max_requests_per_connection int Default:0
shutdown_timeout float Default:10.0
uds str | None Default:None
health_check_path str | None Default:None
_serve_impl 24 None ▼
Inner serve implementation — raises on error, no catching.
def _serve_impl(*, app: str, host: str, port: int, workers: int, 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, max_requests_per_connection: int, shutdown_timeout: float, uds: str | None, health_check_path: str | None, worker_mode: str, cpu_affinity: bool) -> None
Parameters
Name Type Description
app str
host str
port int
workers int
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
max_requests_per_connection int
shutdown_timeout float
uds str | None
health_check_path str | None
worker_mode str
cpu_affinity bool
_die 3 None ▼
Render a branded error and exit.
def _die(message: str, *, hint: str | None = None, diagnostics: list[dict[str, str]] | None = None) -> None
Parameters
Name Type Description
message str
hint 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 24 None ▼
Run pre-flight validation checks. Takes the same arguments as ``serve`` and va…
def check(app: str, host: str = '127.0.0.1', port: int = 8000, workers: int = 1, worker_mode: str = 'auto', cpu_affinity: bool = False, log_level: str = 'info', log_format: str = 'auto', root_path: str = '', 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 = 5.0, header_timeout: float = 10.0, max_requests_per_connection: int = 0, shutdown_timeout: float = 10.0, uds: str | None = None, health_check_path: 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
host str Default:'127.0.0.1'
port int Default:8000
workers int Default:1
worker_mode str Default:'auto'
cpu_affinity bool Default:False
log_level str Default:'info'
log_format str Default:'auto'
root_path str Default:''
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 Default:5.0
header_timeout float Default:10.0
max_requests_per_connection int Default:0
shutdown_timeout float Default:10.0
uds str | None Default:None
health_check_path 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 23 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, 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
max_requests_per_connection int
shutdown_timeout float
uds str | None
health_check_path str | None
Returns
dict[str, str]
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