topmark.cli.option_meta

topmark / cli / option_meta

CLI option metadata helpers.

This module contains small, parser-adjacent metadata used by TopMark-owned validation and diagnostic rendering. Click option declarations remain in topmark.cli.options; this module must not become a second parser model.

CLI_OPTION_META_BY_LONG module-attribute

CLI_OPTION_META_BY_LONG = {
    INCLUDE_FILE_TYPES: CliOptionMeta(
        long=INCLUDE_FILE_TYPES,
        short=INCLUDE_FILE_TYPES,
        hidden_aliases=(INCLUDE_FILE_TYPE,),
    ),
    EXCLUDE_FILE_TYPES: CliOptionMeta(
        long=EXCLUDE_FILE_TYPES,
        short=EXCLUDE_FILE_TYPES,
        hidden_aliases=(EXCLUDE_FILE_TYPE,),
    ),
    VERBOSE: CliOptionMeta(long=VERBOSE, short=VERBOSE),
    QUIET: CliOptionMeta(long=QUIET, short=QUIET),
}

Known CLI option metadata keyed by canonical long spelling.

CLI_HIDDEN_ALIAS_TARGETS module-attribute

CLI_HIDDEN_ALIAS_TARGETS = {
    alias: (long)
    for meta in (values())
    for alias in (hidden_aliases)
}

Hidden compatibility aliases keyed by alias spelling.

CliOptionMeta dataclass

CliOptionMeta(long, short=None, hidden_aliases=())

Human-facing metadata for one CLI option spelling.

Attributes:

Name	Type	Description
long	str	Canonical long option spelling.
short	str | None	Optional short alias spelling.
hidden_aliases	tuple[str, ...]	Compatibility aliases accepted by Click but hidden from help.

label

label()

Return the option label used in human-facing diagnostics.

Returns:

Type	Description
str	The canonical long spelling, followed by the short alias when available.

Source code in src/topmark/cli/option_meta.py

def label(self) -> str:
    """Return the option label used in human-facing diagnostics.

    Returns:
        The canonical long spelling, followed by the short alias when available.
    """
    if self.short is None:
        return self.long
    return f"{self.long} ({self.short})"

format_option_label

format_option_label(option)

Return a user-facing option label, including a short alias when known.

Parameters:

Name	Type	Description	Default
option	str	Option spelling to render. Hidden aliases are resolved to their canonical long spelling before rendering.	required

Returns:

Type	Description
str	Human-facing option label for diagnostics.

Source code in src/topmark/cli/option_meta.py

def format_option_label(option: str) -> str:
    """Return a user-facing option label, including a short alias when known.

    Args:
        option: Option spelling to render. Hidden aliases are resolved to their
            canonical long spelling before rendering.

    Returns:
        Human-facing option label for diagnostics.
    """
    canonical: str = CLI_HIDDEN_ALIAS_TARGETS.get(option, option)
    meta: CliOptionMeta | None = CLI_OPTION_META_BY_LONG.get(canonical)
    if meta is None:
        return canonical
    return meta.label()

format_option_labels

format_option_labels(options)

Return user-facing option labels for a list of option spellings.

Parameters:

Name	Type	Description	Default
options	list[str]	Option spellings to render.	required

Returns:

Type	Description
list[str]	Rendered labels in the same order as the provided option spellings.

Source code in src/topmark/cli/option_meta.py

def format_option_labels(options: list[str]) -> list[str]:
    """Return user-facing option labels for a list of option spellings.

    Args:
        options: Option spellings to render.

    Returns:
        Rendered labels in the same order as the provided option spellings.
    """
    return [format_option_label(option) for option in options]