_common

_common

Shared building blocks for the per-verb command modules.

Small, dependency-light helpers reused across control, observe, and launch: the argument-value splitter, the container-argument definitions, the extras marker maps read by needs_container / standalone_only, and the version/environment formatting used by the status-style verbs.

CONTAINER_ARG = ArgDef(name='container', help='Container name or ID') module-attribute

CONTAINER_ID_ARG = ArgDef(name='--container-id', required=True, help='Full podman container UUID — routes hub events to the per-container supervisor socket') module-attribute

NEEDS_CTR = {'needs_container': True} module-attribute

STANDALONE = {'standalone_only': True} module-attribute

NEEDS_CTR_STANDALONE = {'needs_container': True, 'standalone_only': True} module-attribute

csv_list(value)

Split a comma-separated CLI value into a list, stripping whitespace.

Used as ArgDef.type for multi-value optional flags so they don't rely on argparse's greedy nargs="+" (which silently slurps the following positional, turning --profiles a b mycontainer into profiles=["a","b","mycontainer"]). Comma-separated single-value matches podman's convention (--cap-add=A,B,C).

Source code in src/terok_shield/verbs/_common.py

def csv_list(value: str) -> list[str]:
    """Split a comma-separated CLI value into a list, stripping whitespace.

    Used as ``ArgDef.type`` for multi-value optional flags so they don't
    rely on argparse's greedy ``nargs="+"`` (which silently slurps the
    following positional, turning ``--profiles a b mycontainer`` into
    ``profiles=["a","b","mycontainer"]``).  Comma-separated single-value
    matches podman's convention (``--cap-add=A,B,C``).
    """
    return [p.strip() for p in value.split(",") if p.strip()]

format_version(v)

Format a version tuple as a dotted string.

Source code in src/terok_shield/verbs/_common.py

def format_version(v: tuple[int, ...]) -> str:
    """Format a version tuple as a dotted string."""
    return ".".join(str(p) for p in v) if v != (0,) else "unknown"

print_env_hint(env)

Print human-readable environment issues and setup hint.

Source code in src/terok_shield/verbs/_common.py

def print_env_hint(env: EnvironmentCheck) -> None:
    """Print human-readable environment issues and setup hint."""
    if env.issues:
        print()
        for issue in env.issues:
            print(f"  {issue}")
    if env.setup_hint:
        print()
        print(env.setup_hint)