topmark.cli.options

topmark / cli / options

Common Click option decorators and parsing utilities for TopMark.

This module centralizes reusable Click option definitions and CLI-focused parsing utilities so command implementations can remain thin and consistent.

Structure

• Small parsing helpers for --*-from inputs and verbosity resolution.
• Underscored spelling traps (e.g. --include_from → hint --include-from).
• Reusable option-decorator builders used by CLI commands.

Conventions

• Public decorators are named common_*_options or <domain>_*_options.
• Parsing helpers are small, typed, and import-safe.
• Long option spellings come from topmark.cli.keys.CliOpt.
• Short option spellings come from topmark.cli.keys.CliShortOpt.

StdinUse

Bases: str, Enum

Identify which --*-from option (if any) consumes STDIN.

Values

NONE: Default; no --*-from option consumes STDIN. FILES_FROM: --files-from - consumes STDIN (newline-delimited file paths). INCLUDE_FROM: --include-from - consumes STDIN (newline-delimited glob patterns). EXCLUDE_FROM: --exclude-from - consumes STDIN (newline-delimited glob patterns).

FromOptionValues dataclass

FromOptionValues(*, files_from, include_from, exclude_from)

Values supplied through --*-from options.

Attributes:

Name	Type	Description
files_from	list[str]	Values passed through --files-from.
include_from	list[str]	Values passed through --include-from.
exclude_from	list[str]	Values passed through --exclude-from.

FromOptionStdinText dataclass

FromOptionStdinText(
    *, files_from=None, include_from=None, exclude_from=None
)

STDIN text routed to at most one --*-from - option.

Attributes:

Name	Type	Description
files_from	str | None	Raw STDIN text for --files-from -, or None.
include_from	str | None	Raw STDIN text for --include-from -, or None.
exclude_from	str | None	Raw STDIN text for --exclude-from -, or None.

split_nonempty_lines

split_nonempty_lines(text)

Split text into non-empty, non-comment lines.

Lines are stripped. Blank lines and lines starting with # are ignored.

Parameters:

Name	Type	Description	Default
text	str | None	Raw text (possibly None).	required

Returns:

Type	Description
list[str]	Cleaned, non-empty lines.

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

def split_nonempty_lines(text: str | None) -> list[str]:
    """Split text into non-empty, non-comment lines.

    Lines are stripped. Blank lines and lines starting with `#` are ignored.

    Args:
        text: Raw text (possibly None).

    Returns:
        Cleaned, non-empty lines.
    """
    if not text:
        return []
    out: list[str] = []
    for line in text.splitlines():
        s: str = line.strip()
        if not s or s.startswith("#"):
            continue
        out.append(s)
    return out

extend_with_stdin_lines

extend_with_stdin_lines(target, stdin_text)

Extend target with non-empty, non-comment lines from STDIN text.

Parameters:

Name	Type	Description	Default
target	list[str]	List to extend.	required
stdin_text	str | None	Raw text from STDIN (possibly None).	required

Returns:

Type	Description
list[str]	The same list instance for convenience.

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

def extend_with_stdin_lines(target: list[str], stdin_text: str | None) -> list[str]:
    """Extend `target` with non-empty, non-comment lines from STDIN text.

    Args:
        target: List to extend.
        stdin_text: Raw text from STDIN (possibly None).

    Returns:
        The same list instance for convenience.
    """
    if stdin_text:
        target.extend(split_nonempty_lines(stdin_text))
    return target

strip_dash_sentinels

strip_dash_sentinels(
    files_from, include_from, exclude_from
)

Remove '-' sentinels so downstream code never treats STDIN as a file path.

Parameters:

Name	Type	Description	Default
files_from	Iterable[str]	Values passed via --files-from (may include '-').	required
include_from	Iterable[str]	Values passed via --include-from (may include '-').	required
exclude_from	Iterable[str]	Values passed via --exclude-from (may include '-').	required

Returns:

Type	Description
FromOptionValues	Values from each --*-from option with '-' removed.

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

def strip_dash_sentinels(
    files_from: Iterable[str],
    include_from: Iterable[str],
    exclude_from: Iterable[str],
) -> FromOptionValues:
    """Remove '-' sentinels so downstream code never treats STDIN as a file path.

    Args:
        files_from: Values passed via `--files-from` (may include '-').
        include_from: Values passed via `--include-from` (may include '-').
        exclude_from: Values passed via `--exclude-from` (may include '-').

    Returns:
        Values from each `--*-from` option with `'-'` removed.
    """
    return FromOptionValues(
        files_from=[x for x in files_from if x != "-"],
        include_from=[x for x in include_from if x != "-"],
        exclude_from=[x for x in exclude_from if x != "-"],
    )

extract_stdin_for_from_options

extract_stdin_for_from_options(
    files_from, include_from, exclude_from, stdin_text=None
)

Return raw STDIN text for at most one --*-from - option.

If one of the options contains '-', this reads STDIN (unless stdin_text is provided) and returns that text for the requesting option. If multiple --*-from options request STDIN, a usage error is raised.

Parameters:

Name	Type	Description	Default
files_from	Iterable[str]	Values passed via --files-from (may include '-').	required
include_from	Iterable[str]	Values passed via --include-from (may include '-').	required
exclude_from	Iterable[str]	Values passed via --exclude-from (may include '-').	required
stdin_text	str | None	Optional pre-read STDIN content (useful for tests).	None

Returns:

Type	Description
FromOptionStdinText	Routed STDIN text for the requesting --*-from - option. At most one field
FromOptionStdinText	is non-None.

Raises:

Type	Description
TopmarkCliUsageError	If multiple options request STDIN simultaneously.

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

def extract_stdin_for_from_options(
    files_from: Iterable[str],
    include_from: Iterable[str],
    exclude_from: Iterable[str],
    stdin_text: str | None = None,
) -> FromOptionStdinText:
    """Return raw STDIN text for at most one `--*-from -` option.

    If one of the options contains `'-'`, this reads STDIN (unless `stdin_text`
    is provided) and returns that text for the requesting option. If multiple
    `--*-from` options request STDIN, a usage error is raised.

    Args:
        files_from: Values passed via `--files-from` (may include '-').
        include_from: Values passed via `--include-from` (may include '-').
        exclude_from: Values passed via `--exclude-from` (may include '-').
        stdin_text: Optional pre-read STDIN content (useful for tests).

    Returns:
        Routed STDIN text for the requesting `--*-from -` option. At most one field
        is non-`None`.

    Raises:
        TopmarkCliUsageError: If multiple options request STDIN simultaneously.
    """
    wants: list[StdinUse] = []
    if any(x == "-" for x in files_from):
        wants.append(StdinUse.FILES_FROM)
    if any(x == "-" for x in include_from):
        wants.append(StdinUse.INCLUDE_FROM)
    if any(x == "-" for x in exclude_from):
        wants.append(StdinUse.EXCLUDE_FROM)

    if len(wants) > 1:
        raise TopmarkCliUsageError(
            f"Only one of {CliOpt.FILES_FROM} / {CliOpt.INCLUDE_FROM} / {CliOpt.EXCLUDE_FROM} "
            f"may read from STDIN ('-'). Requested: {', '.join(w.value for w in wants)}"
        )

    text_files: str | None = None
    text_includes: str | None = None
    text_excludes: str | None = None

    if wants:
        text: str = stdin_text if stdin_text is not None else click.get_text_stream("stdin").read()
        # Treat empty as empty list; keep it simple (no error)
        # (No need to check for None, as text is always a string here)
        if wants[0] == StdinUse.FILES_FROM:
            text_files = text
        elif wants[0] == StdinUse.INCLUDE_FROM:
            text_includes = text
        else:
            text_excludes = text

    return FromOptionStdinText(
        files_from=text_files,
        include_from=text_includes,
        exclude_from=text_excludes,
    )

normalize_verbosity

normalize_verbosity(verbose_count)

Normalize an integer verbosity level from -v/--verbose counts.

Parameters:

Name	Type	Description	Default
verbose_count	int	Number of times -v/--verbose is passed.	required

Returns:

Type	Description
int	Normalized verbosity level in the range 0..2.

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

def normalize_verbosity(verbose_count: int) -> int:
    """Normalize an integer verbosity level from `-v/--verbose` counts.

    Args:
        verbose_count: Number of times `-v/--verbose` is passed.

    Returns:
        Normalized verbosity level in the range 0..2.
    """
    return min(2, max(0, verbose_count))

option_with_underscore_traps

option_with_underscore_traps(*param_decls, **attrs)

Like click.option, but also traps underscored spellings.

For each canonical long option declaration of the form --foo-bar, this helper also registers a hidden eager option --foo_bar that raises a helpful error suggesting the hyphenated spelling.

The trap is attached alongside the real option so call sites don't need to remember to register traps separately.

Parameters:

Name	Type	Description	Default
*param_decls	str	Click option declarations (e.g. "--verbose", "-v").	()
**attrs	Unpack[_ClickOptionKwargs]	Keyword arguments forwarded to click.option.	{}

Returns:

Type	Description
Callable[[Callable[_P, _R]], Callable[_P, _R]]	A Click option decorator.

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

def option_with_underscore_traps(
    *param_decls: str,
    **attrs: Unpack[_ClickOptionKwargs],
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
    """Like `click.option`, but also traps underscored spellings.

    For each canonical long option declaration of the form `--foo-bar`, this helper
    also registers a hidden eager option `--foo_bar` that raises a helpful error
    suggesting the hyphenated spelling.

    The trap is attached alongside the real option so call sites don't need to
    remember to register traps separately.

    Args:
        *param_decls: Click option declarations (e.g. `"--verbose"`, `"-v"`).
        **attrs: Keyword arguments forwarded to `click.option`.

    Returns:
        A Click option decorator.
    """
    canonical_longs: list[str] = [
        d
        for d in param_decls
        if d.startswith("--")  # Only long options
        and ("/" not in d)  # Keep paired flags: don't generate underscore traps for them
        and ("_" not in d)
        and ("-" in d[2:])
    ]
    trap_longs: list[str] = ["--" + d[2:].replace("-", "_") for d in canonical_longs]

    real_decorator = click.option(*param_decls, **attrs)

    if not trap_longs:
        return real_decorator

    # Deterministic hidden destination; avoid collisions with real dest names.
    key: str = canonical_longs[0][2:].replace("-", "_")
    trap_dest: str = f"_trap__{key}"

    trap_decorator = click.option(
        *trap_longs,
        trap_dest,
        hidden=True,
        expose_value=False,
        is_eager=True,
        multiple=True,
        callback=_trap_underscored_option,
    )

    def decorator(f: Callable[_P, _R]) -> Callable[_P, _R]:
        f = trap_decorator(f)
        f = real_decorator(f)
        return f

    return decorator

enum_value_help_text

enum_value_help_text(
    enum_cls, *, prefix="", default=None, suffix=None
)

Render CLI-facing help text for enum option values.

CLI help prefers kebab-case values for readability. TopMark's configuration, Python API enum values, and machine-readable output use canonical underscore values when enum members are defined with underscores. This helper renders the CLI-facing value list, marks an optional default, and appends a short underscore/canonical-value note only when needed.

Parameters:

Name	Type	Description	Default
enum_cls	type[Enum]	Enum class whose members expose string values.	required
prefix	str	Optional text placed before the rendered value list.	''
default	Enum | str | None	Optional enum member or raw value to mark as the default.	None
suffix	str | None	Optional sentence appended after the alias/canonical-value note.	None

Returns:

Type	Description
str	Help text suitable for inclusion in a Click option description.

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

def enum_value_help_text(
    enum_cls: type[Enum],
    *,
    prefix: str = "",
    default: Enum | str | None = None,
    suffix: str | None = None,
) -> str:
    """Render CLI-facing help text for enum option values.

    CLI help prefers kebab-case values for readability. TopMark's
    configuration, Python API enum values, and machine-readable output use
    canonical underscore values when enum members are defined with underscores.
    This helper renders the CLI-facing value list, marks an optional default,
    and appends a short underscore/canonical-value note only when needed.

    Args:
        enum_cls: Enum class whose members expose string values.
        prefix: Optional text placed before the rendered value list.
        default: Optional enum member or raw value to mark as the default.
        suffix: Optional sentence appended after the alias/canonical-value note.

    Returns:
        Help text suitable for inclusion in a Click option description.
    """
    default_value: str | None
    if isinstance(default, Enum):
        default_value = str(default.value)
    elif default is None:
        default_value = None
    else:
        default_value = str(default)

    rendered_values: list[str] = []
    underscore_values: list[str] = []

    for member in enum_cls:
        raw_value: str = str(member.value)
        rendered_value: str = raw_value.replace("_", "-")
        if raw_value == default_value:
            rendered_value = f"{rendered_value} (default)"
        rendered_values.append(rendered_value)
        if "_" in raw_value:
            underscore_values.append(raw_value)

    text: str = f"Accepted values: {', '.join(rendered_values)}."
    if prefix:
        text = f"{prefix} {text}"

    if underscore_values:
        text += (
            f" CLI also accepts underscore forms ({', '.join(underscore_values)}); "
            "config, API, and machine-readable output use underscore values."
        )

    if suffix:
        text += f" {suffix}"

    return text

common_text_output_verbosity_options

common_text_output_verbosity_options(f)

Adds --verbose option to a command.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function with verbosity option added.

Behavior

Adds count-based -v/--verbose detail controls for text output.

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

def common_text_output_verbosity_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Adds --verbose option to a command.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function with verbosity option added.

    Behavior:
        Adds count-based `-v/--verbose` detail controls for text output.
    """
    f = option_with_underscore_traps(
        CliOpt.VERBOSE,
        ArgKey.VERBOSITY,
        CliShortOpt.VERBOSE,
        count=True,
        help="Increase TEXT output detail. Repeat once for full detail.",
    )(f)
    return f

common_text_output_quiet_options

common_text_output_quiet_options(f)

Adds --quiet option to a command.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function with quiet option added.

Behavior

Adds boolean -q/--quiet suppression for text output.

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

def common_text_output_quiet_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Adds --quiet option to a command.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function with quiet option added.

    Behavior:
        Adds boolean `-q/--quiet` suppression for text output.
    """
    f = option_with_underscore_traps(
        CliOpt.QUIET,
        ArgKey.QUIET,
        CliShortOpt.QUIET,
        is_flag=True,
        default=False,
        help="Suppress human (TEXT) output and rely on exit status only.",
    )(f)
    return f

common_color_options

common_color_options(f)

Adds --color and --no-color options to a command.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function with color options added.

Behavior

Adds --color with choices (auto, always, never). Adds --no-color flag that disables color output. These options control colorized terminal output.

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

def common_color_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Adds --color and --no-color options to a command.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function with color options added.

    Behavior:
        Adds --color with choices (auto, always, never).
        Adds --no-color flag that disables color output.
        These options control colorized terminal output.
    """
    f = option_with_underscore_traps(
        CliOpt.COLOR_MODE,
        ArgKey.COLOR_MODE,
        type=EnumChoiceParam(
            ColorMode,
            case_sensitive=False,
            kebab_case=True,
        ),
        default=None,
        help=enum_value_help_text(
            ColorMode,
            prefix="Color output for text format.",
            default=ColorMode.AUTO,
        ),
    )(f)
    f = option_with_underscore_traps(
        CliOpt.NO_COLOR_MODE,
        ArgKey.NO_COLOR_MODE,
        is_flag=True,
        help="Disable color output for text format "
        f"(equivalent to {CliOpt.COLOR_MODE}={ColorMode.NEVER.value}).",
    )(f)
    return f

common_output_format_options

common_output_format_options(f)

Apply common output format options.

Adds the --output-format option which accepts OutputFormat values for human use (text, markdown) and machine-readable formats (json, ndjson). If not set, it will be resolved to text (ANSI-capable).

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_output_format_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common output format options.

    Adds the ``--output-format`` option which accepts OutputFormat values for human use
    (``text``, ``markdown``) and machine-readable formats (``json``, ``ndjson``).
    If not set, it will be resolved to ``text`` (ANSI-capable).

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.OUTPUT_FORMAT,
        ArgKey.OUTPUT_FORMAT,
        type=EnumChoiceParam(
            OutputFormat,
            case_sensitive=False,
            kebab_case=True,
        ),
        default=None,
        help=enum_value_help_text(
            OutputFormat,
            prefix="Output format.",
            default=OutputFormat.TEXT,
        ),
    )(f)
    return f

common_header_field_options

common_header_field_options(f)

Apply common header field selection and definition options.

Adds the folloiwng header field options: --header-fields, --field-values.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_header_field_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common header field selection and definition options.

    Adds the folloiwng header field options: ``--header-fields``,
    ``--field-values``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.HEADER_FIELDS,
        ArgKey.HEADER_FIELDS,
        default=None,
        help="Header fields (ordered list of built-in or custom header fields).",
    )(f)
    f = option_with_underscore_traps(
        CliOpt.FIELD_VALUES,
        ArgKey.FIELD_VALUES,
        default=None,
        help="Define or override header field values (for example header_field=field_value pairs).",
    )(f)
    return f

common_include_exclude_from_options

common_include_exclude_from_options(f)

Apply common file selection and filtering options.

Adds the following file source options: --include-from, --exclude-from.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_include_exclude_from_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file selection and filtering options.

    Adds the following file source options: ``--include-from``, ``--exclude-from``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.INCLUDE_FROM,
        ArgKey.INCLUDE_FROM,
        type=str,  # Ensure '-' passes through untouched
        multiple=True,
        help="Filter: read include glob patterns from file(s) "
        "(use '-' for STDIN). May be repeated.",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.EXCLUDE_FROM,
        ArgKey.EXCLUDE_FROM,
        type=str,  # Ensure '-' passes through untouched
        multiple=True,
        help="Filter: read exclude glob patterns from file(s) "
        "(use '-' for STDIN). May be repeated.",
    )(f)

    return f

common_files_from_options

common_files_from_options(f)

Apply common file selection and filtering options.

Adds the following file source options: --files-from.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_files_from_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file selection and filtering options.

    Adds the following file source options: ``--files-from``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    # Option for reading candidate file paths from files
    f = option_with_underscore_traps(
        CliOpt.FILES_FROM,
        ArgKey.FILES_FROM,
        type=str,  # Ensure '-' passes through untouched
        multiple=True,
        help=(
            "Source: add candidate files by reading newline-delimited paths from file(s) "
            "(use '-' for STDIN). "
            "These paths are added to positional PATHS/globs before filtering."
        ),
    )(f)

    return f

config_dump_files_from_options

config_dump_files_from_options(f)

Apply config dump file selection and filtering options.

Adds the following file source options: --files-from.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def config_dump_files_from_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply config dump file selection and filtering options.

    Adds the following file source options: ``--files-from``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    # Option for reading candidate file paths from files (for config dump)
    f = option_with_underscore_traps(
        CliOpt.FILES_FROM,
        ArgKey.FILES_FROM,
        type=str,  # Ensure '-' passes through untouched
        multiple=True,
        help=(
            "Accept newline-delimited paths from file(s) for compatibility "
            "(use '-' for STDIN). "
            "Listed paths do not affect the dumped configuration."
        ),
    )(f)

    return f

common_stdin_content_mode_options

common_stdin_content_mode_options(f)

Apply common file selection and filtering options.

Adds option --stdin-filename when processing file contents from STDIN.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_stdin_content_mode_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file selection and filtering options.

    Adds option ``--stdin-filename`` when processing file contents from STDIN.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    # Option for STDIN content mode (inserted before --files-from)
    f = option_with_underscore_traps(
        CliOpt.STDIN_FILENAME,
        ArgKey.STDIN_FILENAME,
        type=str,
        default=None,
        help=(
            "Assumed filename when reading a single file's content from STDIN via '-' (dash). "
            "Required when '-' is provided as a PATH."
        ),
    )(f)

    return f

common_file_filtering_options

common_file_filtering_options(f)

Apply common file selection and filtering pattern options.

Adds file inclusion / exclusion pattern options: --include, --exclude.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_file_filtering_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file selection and filtering pattern options.

    Adds file inclusion / exclusion pattern options: ``--include``, ``--exclude``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.INCLUDE_PATTERNS,
        CliShortOpt.INCLUDE_PATTERNS,
        ArgKey.INCLUDE_PATTERNS,
        multiple=True,
        help="Filter: include only files matching these glob patterns (intersection). "
        "May be repeated.",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.EXCLUDE_PATTERNS,
        CliShortOpt.EXCLUDE_PATTERNS,
        ArgKey.EXCLUDE_PATTERNS,
        multiple=True,
        help="Filter: exclude files matching these glob patterns (subtraction). May be repeated.",
    )(f)

    return f

common_file_type_filtering_options

common_file_type_filtering_options(f)

Apply common file type selection and filtering options.

Adds file type filtering options: --include-file-types, --exclude-file-types.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_file_type_filtering_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file type selection and filtering options.

    Adds file type filtering options: ``--include-file-types``, ``--exclude-file-types``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.INCLUDE_FILE_TYPES,
        CliOpt.INCLUDE_FILE_TYPE,
        CliShortOpt.INCLUDE_FILE_TYPES,
        ArgKey.INCLUDE_FILE_TYPES,
        multiple=True,
        callback=_split_csv_multi_option,
        help=(
            "Filter: restrict to given file types. Preferred spelling is "
            f"{CliOpt.INCLUDE_FILE_TYPES} (alias: {CliOpt.INCLUDE_FILE_TYPE}). "
            "Applied after path include/exclude filtering. "
            "May be repeated and/or given as a comma-separated list."
        ),
    )(f)

    f = option_with_underscore_traps(
        CliOpt.EXCLUDE_FILE_TYPES,
        CliOpt.EXCLUDE_FILE_TYPE,
        CliShortOpt.EXCLUDE_FILE_TYPES,
        ArgKey.EXCLUDE_FILE_TYPES,
        multiple=True,
        callback=_split_csv_multi_option,
        help=(
            "Filter: exclude given file types. Preferred spelling is "
            f"{CliOpt.EXCLUDE_FILE_TYPES} (alias: {CliOpt.EXCLUDE_FILE_TYPE}). "
            "Applied after path include/exclude filtering. "
            "May be repeated and/or given as a comma-separated list."
        ),
    )(f)

    return f

common_apply_and_write_options

common_apply_and_write_options(f)

Apply common file selection and filtering options.

Adds options such as --apply, --write-mode.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_apply_and_write_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common file selection and filtering options.

    Adds options such as ``--apply``, ``--write-mode``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.APPLY_CHANGES,
        ArgKey.APPLY_CHANGES,
        is_flag=True,
        help="Write changes to files (off by default).",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.WRITE_MODE,
        ArgKey.WRITE_MODE,
        type=click.Choice(["atomic", "inplace", "stdout"], case_sensitive=False),
        help=(
            "Select write strategy: 'atomic' (safe, default), "
            "'inplace' (fast, less safe), or 'stdout' (emit result to standard output)."
        ),
    )(f)

    return f

render_diff_options

render_diff_options(f)

Apply diff rendering options.

Adds the following option: --diff.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def render_diff_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply diff rendering options.

    Adds the following option: ``--diff``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.RENDER_DIFF,
        ArgKey.RENDER_DIFF,
        is_flag=True,
        help="Show unified diffs (human output only).",
    )(f)

    return f

pipeline_reporting_options

pipeline_reporting_options(f)

Apply summary/reporting options for pipeline-style commands.

Adds the following options

• --summary: show outcome counts instead of per-file details.
• --report: control which entries appear in human per-file output.

Notes

--report is a human-facing per-file listing policy. It is ignored for summary mode and machine-readable output.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def pipeline_reporting_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply summary/reporting options for pipeline-style commands.

    Adds the following options:
        - ``--summary``: show outcome counts instead of per-file details.
        - ``--report``: control which entries appear in **human per-file**
          output.

    Notes:
        `--report` is a human-facing per-file listing policy. It is ignored for
        summary mode and machine-readable output.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.RESULTS_SUMMARY_MODE,
        ArgKey.RESULTS_SUMMARY_MODE,
        is_flag=True,
        help="Show summary of outcome counts instead of per-file details.",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.REPORT,
        ArgKey.REPORT_SCOPE,
        type=EnumChoiceParam(
            ReportScope,
            case_sensitive=False,
            kebab_case=True,
        ),
        default=ReportScope.ACTIONABLE,
        help=enum_value_help_text(
            ReportScope,
            prefix=(
                "Reporting scope for human per-file output. "
                "Ignored for summary mode and machine-readable formats."
            ),
            default=ReportScope.ACTIONABLE,
            suffix=(
                "Use 'actionable' to list would-change results and other attention-worthy states; "
                "'noncompliant' to list actionable results plus unsupported entries; "
                "'all' to list every processed result, including unchanged entries. "
            ),
        ),
    )(f)

    return f

registry_details_options

registry_details_options(f)

Apply details mode output options for registry commands.

Adds the following option: --long.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def registry_details_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply details mode output options for registry commands.

    Adds the following option: ``--long``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.SHOW_DETAILS,
        ArgKey.SHOW_DETAILS,
        CliShortOpt.SHOW_DETAILS,
        is_flag=True,
        help="Show extended information (extensions, filenames, patterns, skip policy, "
        "header policy).",
    )(f)

    return f

config_strict_options

config_strict_options(f)

Add config strictness override options.

The CLI flags override the effective [config].strict value for the current run.

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

def config_strict_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Add config strictness override options.

    The CLI flags override the effective `[config].strict` value for the current run.
    """
    f = option_with_underscore_traps(
        f"{CliOpt.STRICT}/{CliOpt.NO_STRICT}",
        ArgKey.STRICT,
        is_flag=True,
        default=None,
        help="Fail if any warnings are present (in addition to errors).",
    )(f)

    return f

config_pyproject_options

config_pyproject_options(f)

Add --pyproject to generate config suitable for inclusion in pyproject.toml.

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

def config_pyproject_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Add --pyproject to generate config suitable for inclusion in pyproject.toml."""
    f = option_with_underscore_traps(
        CliOpt.CONFIG_FOR_PYPROJECT,
        ArgKey.CONFIG_FOR_PYPROJECT,
        is_flag=True,
        help="Generate config for inclusion in pyproject.toml.",
    )(f)

    return f

config_root_options

config_root_options(f)

Add --root to mark generated config as a discovery root.

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

def config_root_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Add --root to mark generated config as a discovery root."""
    f = option_with_underscore_traps(
        CliOpt.CONFIG_ROOT,
        ArgKey.CONFIG_ROOT,
        is_flag=True,
        help="Set generated config as root.",
    )(f)

    return f

common_config_resolution_options

common_config_resolution_options(f)

Apply common config resolution options to a Click command.

Adds --no-config and --config/-c options.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_config_resolution_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common config resolution options to a Click command.

    Adds ``--no-config`` and ``--config/-c`` options.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.NO_CONFIG,
        ArgKey.NO_CONFIG,
        is_flag=True,
        help="Ignore local project config files (only use defaults).",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.CONFIG_FILES,
        ArgKey.CONFIG_FILES,
        multiple=True,
        metavar="FILE",
        type=click.Path(exists=True, file_okay=True, dir_okay=False, readable=True),
        help="Additional config file(s) to load and merge.",
    )(f)

    return f

config_dump_provenance_options

config_dump_provenance_options(f)

Apply config layered dump options.

Adds --show-layers.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def config_dump_provenance_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply config layered dump options.

    Adds ``--show-layers``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.SHOW_CONFIG_LAYERS,
        ArgKey.SHOW_CONFIG_LAYERS,
        is_flag=True,
        default=False,
        help="Show layered TOML provenance followed by the final flattened config.",
    )(f)

    return f

common_header_formatting_options

common_header_formatting_options(f)

Apply common header formatting options.

Adds --align-fields/--no-align-fields and --relative-to.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def common_header_formatting_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply common header formatting options.

    Adds ``--align-fields/--no-align-fields`` and ``--relative-to``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        f"{CliOpt.ALIGN_FIELDS}/{CliOpt.NO_ALIGN_FIELDS}",
        ArgKey.ALIGN_FIELDS,
        is_flag=True,
        default=None,
        help="Override whether header fields are aligned with colons.",
    )(f)

    f = option_with_underscore_traps(
        CliOpt.RELATIVE_TO,
        ArgKey.RELATIVE_TO,
        help="Header metadata: compute `file_relpath` and `relpath` from this directory.",
    )(f)

    return f

check_policy_options

check_policy_options(f)

Attach check-only policy options.

These options control header insertion/update behavior and are only meaningful for the topmark check pipeline.

Exposed options

• --header-mutation-mode
• --allow-header-in-empty-files / --no-allow-header-in-empty-files
• --empty-insert-mode
• --render-empty-header-when-no-fields / --no-render-empty-header-when-no-fields
• --allow-reflow / --no-allow-reflow

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	Decorated Click command function.

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

def check_policy_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Attach check-only policy options.

    These options control header insertion/update behavior and are only
    meaningful for the `topmark check` pipeline.

    Exposed options:
        - `--header-mutation-mode`
        - `--allow-header-in-empty-files` / `--no-allow-header-in-empty-files`
        - `--empty-insert-mode`
        - `--render-empty-header-when-no-fields` /
          `--no-render-empty-header-when-no-fields`
        - `--allow-reflow` / `--no-allow-reflow`

    Args:
        f: Click command function to decorate.

    Returns:
        Decorated Click command function.
    """
    f = option_with_underscore_traps(
        f"{CliOpt.POLICY_ALLOW_REFLOW}/{CliOpt.POLICY_NO_ALLOW_REFLOW}",
        ArgKey.POLICY_ALLOW_REFLOW,
        is_flag=True,
        default=None,
        help=(
            "Override whether content reflow is allowed during header insertion or "
            "update in the check pipeline."
        ),
    )(f)
    f = option_with_underscore_traps(
        (
            f"{CliOpt.POLICY_RENDER_EMPTY_HEADER_WHEN_NO_FIELDS}/"
            f"{CliOpt.POLICY_NO_RENDER_EMPTY_HEADER_WHEN_NO_FIELDS}"
        ),
        ArgKey.POLICY_RENDER_EMPTY_HEADER_WHEN_NO_FIELDS,
        is_flag=True,
        default=None,
        help=(
            "Override whether an empty header may be inserted when no fields are "
            "configured in the check pipeline."
        ),
    )(f)

    f = option_with_underscore_traps(
        CliOpt.POLICY_EMPTY_INSERT_MODE,
        ArgKey.POLICY_EMPTY_INSERT_MODE,
        type=EnumChoiceParam(
            EmptyInsertMode,
            case_sensitive=False,
            kebab_case=True,
        ),
        default=None,
        help=enum_value_help_text(
            EmptyInsertMode,
            prefix=(
                "Define which inputs count as empty for header insertion in the check pipeline."
            ),
            suffix="Overrides config policy for this run.",
        ),
    )(f)
    f = option_with_underscore_traps(
        (
            f"{CliOpt.POLICY_ALLOW_HEADER_IN_EMPTY_FILES}/"
            f"{CliOpt.POLICY_NO_ALLOW_HEADER_IN_EMPTY_FILES}"
        ),
        ArgKey.POLICY_ALLOW_HEADER_IN_EMPTY_FILES,
        is_flag=True,
        default=None,
        help=(
            "Override whether headers may be inserted into files considered empty "
            "by the effective empty insert mode in the check pipeline."
        ),
    )(f)
    f = option_with_underscore_traps(
        CliOpt.POLICY_HEADER_MUTATION_MODE,
        ArgKey.POLICY_HEADER_MUTATION_MODE,
        type=EnumChoiceParam(
            HeaderMutationMode,
            case_sensitive=False,
            kebab_case=True,
        ),
        default=None,
        help=enum_value_help_text(
            HeaderMutationMode,
            prefix="Control which files `topmark check` may mutate.",
            suffix="Overrides config policy for this run.",
        ),
    )(f)

    return f

shared_policy_options

shared_policy_options(f)

Attach policy options shared by multiple pipeline commands.

These options affect common pipeline behavior such as file-type resolution and are meaningful for topmark check, topmark strip, and topmark probe.

Exposed options

• --allow-content-probe / --no-allow-content-probe

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	Decorated Click command function.

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

def shared_policy_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Attach policy options shared by multiple pipeline commands.

    These options affect common pipeline behavior such as file-type resolution
    and are meaningful for `topmark check`, `topmark strip`, and `topmark probe`.

    Exposed options:
        - `--allow-content-probe` / `--no-allow-content-probe`

    Args:
        f: Click command function to decorate.

    Returns:
        Decorated Click command function.
    """
    f = option_with_underscore_traps(
        f"{CliOpt.POLICY_ALLOW_CONTENT_PROBE}/{CliOpt.POLICY_NO_ALLOW_CONTENT_PROBE}",
        ArgKey.POLICY_ALLOW_CONTENT_PROBE,
        is_flag=True,
        default=None,
        help=(
            "Override whether file-type resolution may consult file contents when "
            "needed. Applies to check, strip, and probe."
        ),
    )(f)

    return f

version_format_options

version_format_options(f)

Apply version formatting options.

Adds --align-fields/--no-align-fields, --header-format and --relative-to.

Parameters:

Name	Type	Description	Default
f	Callable[_P, _R]	The Click command function to decorate.	required

Returns:

Type	Description
Callable[_P, _R]	The decorated function.

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

def version_format_options(f: Callable[_P, _R]) -> Callable[_P, _R]:
    """Apply version formatting options.

    Adds ``--align-fields/--no-align-fields``,  ``--header-format`` and ``--relative-to``.

    Args:
        f: The Click command function to decorate.

    Returns:
        The decorated function.
    """
    f = option_with_underscore_traps(
        CliOpt.SEMVER_VERSION,
        ArgKey.SEMVER_VERSION,
        is_flag=True,
        default=False,
        help="Render the version as SemVer instead of PEP 440 (maps rc→-rc.N, dev→-dev.N).",
    )(f)

    return f