topmark.cli.commands.version

topmark / cli / commands / version

TopMark version command.

Prints the current TopMark version as installed in the active Python environment.

version_command

version_command(
    *,
    verbosity,
    color_mode,
    no_color,
    semver=False,
    output_format,
)

Print the installed TopMark version.

Renders the installed package version for human-readable or machine-readable output, optionally normalized to SemVer when possible.

Parameters:

Name	Type	Description	Default
verbosity	int	Increase TEXT output detail.	required
color_mode	ColorMode | None	Set the color mode (default: auto).	required
no_color	bool	bool: If set, disable color mode.	required
semver	bool	Whether to attempt to render the version as SemVer (default: PEP 440).	False
output_format	OutputFormat | None	Output format to use (text, markdown, json, or ndjson). Verbosity applies only to TEXT output; version does not support --quiet.	required

Raises:

Type	Description
ValueError	If an unsupported output format is requested.

Source code in src/topmark/cli/commands/version.py

@click.command(
    name=CliCmd.VERSION,
    context_settings=GROUP_CONTEXT_SETTINGS,
    help="Print the installed TopMark version.",
    epilog=(
        "\b\n"
        "Examples:\n"
        "  # Print the installed TopMark version\n"
        f"  topmark {CliCmd.VERSION}\n"
        "  # Print the version in SemVer form when possible\n"
        f"  topmark {CliCmd.VERSION} {CliOpt.SEMVER_VERSION}\n"
        "  # Emit machine-readable version metadata\n"
        f"  topmark {CliCmd.VERSION} "
        f"{CliOpt.OUTPUT_FORMAT}={OutputFormat.JSON.value}\n"
        "Notes:\n"
        "  • Default output uses the installed package version.\n"
        "  • Machine-readable formats emit structured version metadata.\n"
    ),
)
@common_color_options
@common_text_output_verbosity_options
@version_format_options
@common_output_format_options
def version_command(
    *,
    # common_ui_options (verbosity, color):
    verbosity: int,
    color_mode: ColorMode | None,
    no_color: bool,
    # version_format_options:
    semver: bool = False,
    # common_output_format_options:
    output_format: OutputFormat | None,
) -> None:
    """Print the installed TopMark version.

    Renders the installed package version for human-readable or machine-readable
    output, optionally normalized to SemVer when possible.

    Args:
        verbosity: Increase TEXT output detail.
        color_mode: Set the color mode (default: auto).
        no_color: bool: If set, disable color mode.
        semver: Whether to attempt to render the version as SemVer (default: PEP 440).
        output_format: Output format to use (``text``, ``markdown``, ``json``, or ``ndjson``).
            Verbosity applies only to TEXT output; `version` does not support `--quiet`.

    Raises:
        ValueError: If an unsupported output format is requested.
    """
    ctx: click.Context = click.get_current_context()
    state: TopmarkCliState = bootstrap_cli_state(ctx)

    # Effective output format (stored early so shared initialization sees it).
    state.output_format = output_format or OutputFormat.TEXT

    # Initialize the common state (verbosity, color mode) and initialize console
    init_common_state(
        ctx,
        verbosity=verbosity,
        quiet=False,  # Pure informational command; no ``--quiet`` option is registered.
        color_mode=color_mode,
        no_color=no_color,
    )

    # Select the console
    console: ConsoleProtocol = state.console

    # Machine metadata
    meta: MetaPayload = build_meta_payload()

    # Output format
    fmt: OutputFormat = state.output_format

    apply_color_policy_for_output_format(ctx, fmt=fmt)
    enable_color: bool = state.color_enabled

    # `version` is file-agnostic: ignore positional PATHS
    apply_ignore_positional_paths_policy(ctx, warn_stdin_dash=True)

    # Machine-readable formats
    if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):
        serialized: str | Iterable[str] = serialize_version(
            meta=meta,
            fmt=fmt,
            semver=semver,
        )
        # Do not emit trailing newline for JSON
        nl: bool = fmt != OutputFormat.JSON
        emit_machine(serialized, console=console, nl=nl)
        return

    report: VersionHumanReport = make_version_human_report(
        verbosity_level=state.verbosity,
        styled=enable_color,
        semver=semver,
    )

    if fmt == OutputFormat.TEXT:
        rendered: str = render_version_text(report)
        # Avoid emitting a blank line if a future renderer returns an empty string.
        if rendered:
            console.print(rendered)
        return

    if fmt == OutputFormat.MARKDOWN:
        console.print(
            render_version_markdown(report),
            nl=False,
        )
        return

    # Defensive guard
    raise ValueError(f"Unsupported output format: {fmt!r}")