httk.core.project.cli

The umbrella httk project command and its extension registry.

httk project owns the anchor: init creates one (like git init) and show describes it. It is deliberately extensible. A capability that layers on top of the anchor — httk-workflow contributes signed manifests, a doctor, and the workspace rows of show — registers into this command rather than adding a parallel one, so an operator sees a single httk project whose leaves come from whatever is installed.

The registration machinery mirrors httk.core.register_cli_command(): a capability registers lazily, by "module:callable" reference, from its httk.handlers.* package during core plugin discovery, and nothing heavy is imported until httk project actually runs. Registrations are strict — reserved names and duplicates are errors — and the command tree is assembled in a stable order.

Attributes

CallableRef
Handler
ParserBuilder

Classes

ProjectShowSection

One capability's contribution to httk project show.

Functions

register_project_subcommand(→ None)	Register one lazy subcommand of httk project.
register_project_show_section(→ None)	Register one contributor to httk project show.
known_project_subcommands(→ list[str])	Return the registered extension subcommand names, in stable order.
known_project_show_sections(→ list[str])	Return the registered show-section names, in stable order.
describe_project(→ tuple[dict[str, object], ...)	Describe one project's anchor, merging every registered show section.
build_parser(→ argparse.ArgumentParser)	Build the whole httk project tree, including registered extensions.
command(→ int)	Handle the registered top-level project command.

Module Contents

httk.core.project.cli.CallableRef

httk.core.project.cli.Handler

httk.core.project.cli.ParserBuilder

class httk.core.project.cli.ProjectShowSection

One capability’s contribution to httk project show.

json is merged into the top level of the --json description; rows are appended, in order, to the human-readable listing as label/value pairs.

json: dict[str, object]

rows: list[tuple[str, str]] = []

httk.core.project.cli.register_project_subcommand(name: str, build_parser: CallableRef, handler: CallableRef | None = None, *, summary: str = '', description: str = '') → None

Register one lazy subcommand of httk project.

build_parser is a callable — or a "module:callable" reference — that receives the subcommand’s argparse.ArgumentParser and declares its arguments on it. A leaf passes handler, the (argv, context) -> int function that runs it; a group passes handler=None and sets the handler of each of its own nested leaves inside build_parser.

Registration is strict: names are lowercase and hyphenated, the built-in init and show cannot be shadowed, and a duplicate name is an error rather than an order-dependent override.

httk.core.project.cli.register_project_show_section(name: str, section: CallableRef) → None

Register one contributor to httk project show.

section is a callable — or a "module:callable" reference — invoked as section(root, verify=...) with the discovered project root and expected to return a ProjectShowSection. Sections are rendered in stable order by name; a duplicate name is an error.

httk.core.project.cli.known_project_subcommands() → list[str]

Return the registered extension subcommand names, in stable order.

httk.core.project.cli.known_project_show_sections() → list[str]

Return the registered show-section names, in stable order.

httk.core.project.cli.describe_project(root: str | pathlib.Path | None = None, *, verify: bool = True) → tuple[dict[str, object], list[tuple[str, str]]]

Describe one project’s anchor, merging every registered show section.

Returns the JSON description and the extra human-readable rows the sections contributed; the anchor’s own rows are added when the result is rendered.

httk.core.project.cli.build_parser(program: str) → argparse.ArgumentParser

Build the whole httk project tree, including registered extensions.

httk.core.project.cli.command(argv: collections.abc.Sequence[str], context: httk.core.cli_context.CLIContext) → int

Handle the registered top-level project command.