cli.core package

Submodules

cli.core.app module

class cli.core.app.Flags(log_dir: 'Path | None' = None, git_clean: 'bool' = False, infinite: 'bool' = False, help_all: 'bool' = False, tree: 'bool' = False, tree_depth: 'int | None' = None, version: 'bool' = False)

Bases: object

git_clean: bool = False
help_all: bool = False
infinite: bool = False
log_dir: Path | None = None
tree: bool = False
tree_depth: int | None = None
version: bool = False
cli.core.app.main() → None
cli.core.app.parse_flags(argv: list[str]) → Flags

cli.core.colors module

class cli.core.colors.Fore

Bases: object

BLACK = '\x1b[30m'
BLUE = '\x1b[34m'
CYAN = '\x1b[36m'
GREEN = '\x1b[32m'
MAGENTA = '\x1b[35m'
RED = '\x1b[31m'
WHITE = '\x1b[37m'
YELLOW = '\x1b[33m'
class cli.core.colors.Style

Bases: object

BRIGHT = '\x1b[1m'
DIM = '\x1b[2m'
ITALIC = '\x1b[3m'
RESET_ALL = '\x1b[0m'
cli.core.colors.color_text(text: str, color: str) → str

cli.core.discovery module

class cli.core.discovery.Command(parts: tuple[str, ...], module: str, main_path: Path)

Bases: object

A CLI command is a Python package directory under cli/ that contains __main__.py.

Example

cli/build/tree/__main__.py -> parts=(“build”,”tree”), module=”cli.build.tree”

property folder: str | None
main_path: Path
module: str
property name: str
parts: tuple[str, ...]
property subcommand: str
class cli.core.discovery.DirEntry(name: str, is_command: bool, relative_parts: tuple[str, ...])

Bases: object

One-level-deep entry under a cli/ directory.

is_command is True when the directory itself contains __main__.py (a runnable subcommand); False for category folders that only group further commands and have no entry point of their own.

is_command: bool
property module: str
name: str
relative_parts: tuple[str, ...]
cli.core.discovery.discover_commands(cli_dir: Path) → list[Command]

Recursively find all packages under cli_dir that contain __main__.py.

cli.core.discovery.iter_dir_entries(cli_dir: Path, parts: tuple[str, ...]) → list[DirEntry]

Return the immediate subdirectories of cli/<parts>/, split into runnable commands (__main__.py present) and category folders. Empty support packages (no command anywhere underneath) are skipped.

cli.core.discovery.resolve_command_module(cli_dir: Path, argv_parts: list[str]) → tuple[str | None, list[str]]

Resolve the longest argv prefix that matches a discovered command module.

Returns:

(module, remaining_args)

Example

argv_parts=[“deploy”,”container”,”–foo”,”bar”] -> (“cli.administration.deploy.container”, [”–foo”,”bar”])

cli.core.git module

cli.core.git.git_clean_repo() → None

cli.core.help module

cli.core.help.extract_description_via_help(module: str) → str

Best-effort: run “python -m <module> –help” and extract the first paragraph after usage.

cli.core.help.format_command_help(name: str, description: str, indent: int = 2, col_width: int = 36, width: int = 80) → str

Two-column help line: name, then the description in DIM.

Reserves at least two spaces between the columns; a name that would crowd into the description column drops the description onto the next line so the two never collide.

cli.core.help.print_dir_overview(cli_dir: Path, parts: list[str]) → None

Print a category-folder overview. The H1 title from the folder’s README.md is used as the heading (with the invocation path shown underneath as a dim subtitle); a fallback to the bare invocation path is used when the README is absent. The README description paragraph follows, then the one-level-deep index of immediate sub-folders and commands.

cli.core.help.print_global_help(cli_dir: Path) → None
cli.core.help.print_tree(cli_dir: Path, parts: list[str], max_depth: int | None = None) → None

Recursive tree listing under cli/<parts>/ with Unicode tree connectors, per-entry emoji glyphs, and multi-line wrapped descriptions aligned to a single description column. max_depth is 1-based: None (default) walks the full tree, 1 shows only the immediate children.

cli.core.help.read_folder_description(folder: Path) → str

Return the first paragraph below the H1 heading in <folder>/README.md. Headings, leading blank lines, and trailing paragraphs are skipped. Returns "-" when no readable description is available.

cli.core.help.read_folder_title(folder: Path) → str | None

Return the H1 heading text of <folder>/README.md with any trailing emoji preserved. Returns None when the file is missing or its first non-blank line is not an H1 heading.

cli.core.help.show_full_help_for_all(cli_dir: Path) → None
cli.core.help.show_help_for_directory(cli_dir: Path, dir_parts: list[str]) → bool

Backwards-compat shim: defer to print_dir_overview(). Returns True when the directory exists, False otherwise.

cli.core.run module

class cli.core.run.RunConfig(log_enabled: 'bool')

Bases: object

log_enabled: bool
cli.core.run.open_log_file(log_dir: Path) → tuple[TextIO, Path]

Create/open a timestamped log file inside log_dir.

  • log_dir is mandatory (provided via –log <LOG_DIR>)

  • log_dir is created with parents=True if missing

cli.core.run.run_command_once(full_cmd: list[str], cfg: RunConfig, log_file: TextIO | None) → bool

Module contents