topmark.presentation.shared.registry

topmark / presentation / shared / registry

Shared Click-free preparers for human-facing registry output.

This module prepares typed, human-facing report models for registry-related CLI commands. The prepared data is intentionally Click-free and reused by:

• TEXT renderers under topmark.presentation.text (ANSI/console styling), and
• Markdown renderers under topmark.presentation.markdown (documentation-friendly output).

TEXT renderers may use verbosity_level and styled; Markdown renderers treat Markdown as document-oriented output and use show_details as the shared detail-depth control.

Notes

This is a "human output" layer. It is distinct from topmark.registry.machine, which targets JSON/NDJSON machine formats.

See Also: - topmark.registry - topmark.core.machine

FileTypePolicyHumanItem dataclass

FileTypePolicyHumanItem(
    *,
    supports_shebang,
    encoding_line_regex,
    pre_header_blank_after_block,
    ensure_blank_after_header,
    blank_collapse_mode,
    blank_collapse_extra,
)

Stable metadata describing header insertion/stripping policy for a file type.

These attributes are optional; processors read them to adapt behavior without hard-coding language specifics. Defaults are conservative and aim to preserve user-authored whitespace while keeping round-trips stable.

Attributes:

Name	Type	Description
supports_shebang	bool	Whether this file type commonly starts with a POSIX shebang (e.g., #!/usr/bin/env bash). When True, processors may skip a leading shebang during placement.
encoding_line_regex	str | None	Optional regex (string) that matches an encoding declaration line immediately after a shebang (e.g., Python PEP 263). When provided and a shebang was skipped, a matching line is also skipped for placement.
pre_header_blank_after_block	int	Number of blank lines to place between a preamble block (shebang/encoding or similar) and the header. Typically 1.
ensure_blank_after_header	bool	Ensure exactly one blank line follows the header when body content follows. No extra blank is added at EOF.
blank_collapse_mode	str	How to identify and collapse blank lines around the header during insert/strip repairs. See BlankCollapseMode for semantics. Defaults to STRICT.
blank_collapse_extra	str	Additional characters to treat as blank in addition to those covered by blank_collapse_mode. For example, set to \"\\x0c\" to consider form-feed collapsible for a given type.

FileTypeHumanItem dataclass

FileTypeHumanItem(
    *,
    local_key,
    namespace,
    qualified_key,
    description,
    bound,
    extensions,
    filenames,
    patterns,
    skip_processing,
    has_content_matcher,
    has_insert_checker,
    policy,
)

Click-free, human-facing view of one file type.

Attributes:

Name	Type	Description
local_key	str	File type local key.
namespace	str	Namespace that owns the file type.
qualified_key	str	Canonical qualified file type key.
description	str	Human-readable file type description.
bound	bool	Whether the file type currently has an effective processor binding.
extensions	tuple[str, ...]	Registered filename extensions.
filenames	tuple[str, ...]	Exact registered filenames.
patterns	tuple[str, ...]	Registered path or glob patterns.
skip_processing	bool	Whether TopMark recognizes but never mutates this type.
has_content_matcher	bool	Whether a content matcher is configured.
has_insert_checker	bool	Whether a pre-insert checker is configured.
policy	FileTypePolicyHumanItem	Structured header policy metadata for human-facing rendering.

FileTypesHumanReport dataclass

FileTypesHumanReport(
    *, show_details, verbosity_level, styled, items
)

Click-free, human-facing report for topmark registry filetypes.

BindingHumanItem dataclass

BindingHumanItem(
    *,
    file_type_key,
    file_type_local_key,
    file_type_namespace,
    processor_key,
    processor_local_key,
    processor_namespace,
    file_type_description,
    processor_description,
)

Click-free, human-facing view of one effective binding.

Attributes:

Name	Type	Description
file_type_key	str	Canonical file type key.
file_type_local_key	str	File type local key.
file_type_namespace	str	Namespace that owns the file type.
processor_key	str	Canonical processor key.
processor_local_key	str	Processor local key.
processor_namespace	str	Namespace that owns the processor.
file_type_description	str	Human-readable file type description.
processor_description	str	Human-readable processor description.

ProcessorHumanItem dataclass

ProcessorHumanItem(
    *,
    local_key,
    namespace,
    qualified_key,
    description,
    bound,
    line_indent,
    line_prefix,
    line_suffix,
    block_prefix,
    block_suffix,
)

Click-free, human-facing view of one header processor.

Attributes:

Name	Type	Description
local_key	str	Processor local key.
namespace	str	Namespace that owns the processor.
qualified_key	str	Canonical processor key.
description	str	Human-readable processor description.
bound	bool	Whether the processor currently participates in at least one effective binding.
line_indent	str	Line comment indent (if applicable).
line_prefix	str	Line comment prefix (if applicable).
line_suffix	str	Line comment suffix (if applicable).
block_prefix	str	Block comment prefix (if applicable).
block_suffix	str	Block comment suffix (if applicable).

UnboundFileTypeHumanItem dataclass

UnboundFileTypeHumanItem(*, name, description)

Click-free, human-facing view of an unbound file type.

Attributes:

Name	Type	Description
name	str	Qualified file type identifier shown in human-facing output.
description	str	Human-readable file type description.

ProcessorsHumanReport dataclass

ProcessorsHumanReport(
    *, show_details, verbosity_level, processors, styled
)

Click-free, human-facing report for topmark registry processors.

BindingsHumanReport dataclass

BindingsHumanReport(
    *,
    show_details,
    verbosity_level,
    bindings,
    unbound_filetypes,
    unused_processors,
    styled,
)

Click-free, human-facing report for topmark registry bindings.

build_filetypes_human_report

build_filetypes_human_report(
    *, show_details, verbosity_level, styled
)

Build a Click-free report used by TEXT and MARKDOWN.

Parameters:

Name	Type	Description	Default
show_details	bool	Whether consumers intend to display extended details.	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
FileTypesHumanReport	A FileTypesHumanReport with one item per file type.

Source code in src/topmark/presentation/shared/registry.py

def build_filetypes_human_report(
    *,
    show_details: bool,
    verbosity_level: int,
    styled: bool,
) -> FileTypesHumanReport:
    """Build a Click-free report used by TEXT and MARKDOWN.

    Args:
        show_details: Whether consumers intend to display extended details.
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        A `FileTypesHumanReport` with one item per file type.
    """
    raw_items: list[FileTypeInfo] = list_filetypes()

    items: list[FileTypeHumanItem] = [
        FileTypeHumanItem(
            local_key=item["local_key"],
            namespace=item["namespace"],
            qualified_key=item["qualified_key"],
            description=item["description"],
            bound=item["bound"],
            extensions=tuple(item["extensions"]),
            filenames=tuple(item["filenames"]),
            patterns=tuple(item["patterns"]),
            skip_processing=item["skip_processing"],
            has_content_matcher=item["has_content_matcher"],
            has_insert_checker=item["has_insert_checker"],
            policy=_build_filetype_policy_human_item(item["policy"]),
        )
        for item in sorted(raw_items, key=lambda it: str(it["qualified_key"]))
    ]

    return FileTypesHumanReport(
        show_details=show_details,
        verbosity_level=verbosity_level,
        items=tuple(items),
        styled=styled,
    )

build_processors_human_report

build_processors_human_report(
    *, show_details, verbosity_level, styled
)

Build a Click-free report used by TEXT and MARKDOWN for processors.

Parameters:

Name	Type	Description	Default
show_details	bool	Whether consumers intend to display extended details.	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
ProcessorsHumanReport	A ProcessorsHumanReport with one item per registered processor.

Source code in src/topmark/presentation/shared/registry.py

def build_processors_human_report(
    *,
    show_details: bool,
    verbosity_level: int,
    styled: bool,
) -> ProcessorsHumanReport:
    """Build a Click-free report used by TEXT and MARKDOWN for `processors`.

    Args:
        show_details: Whether consumers intend to display extended details.
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        A `ProcessorsHumanReport` with one item per registered processor.
    """
    raw_items: list[ProcessorInfo] = list_processors()

    processors: list[ProcessorHumanItem] = [
        ProcessorHumanItem(
            local_key=item["local_key"],
            namespace=item["namespace"],
            qualified_key=item["qualified_key"],
            description=item["description"],
            bound=item["bound"],
            line_indent=item["line_indent"],
            line_prefix=item["line_prefix"],
            line_suffix=item["line_suffix"],
            block_prefix=item["block_prefix"],
            block_suffix=item["block_suffix"],
        )
        for item in sorted(raw_items, key=lambda it: str(it["qualified_key"]))
    ]

    return ProcessorsHumanReport(
        show_details=show_details,
        verbosity_level=verbosity_level,
        processors=tuple(processors),
        styled=styled,
    )

build_bindings_human_report

build_bindings_human_report(
    *, show_details, verbosity_level, styled
)

Build a Click-free report used by TEXT and MARKDOWN for bindings.

Parameters:

Name	Type	Description	Default
show_details	bool	Whether consumers intend to display extended details.	required
verbosity_level	int	Effective TEXT verbosity; Markdown renderers ignore it.	required
styled	bool	Whether TEXT renderers should apply styling; Markdown renderers ignore it.	required

Returns:

Type	Description
BindingsHumanReport	A BindingsHumanReport with effective bindings, unbound file types, and
BindingsHumanReport	currently unused processors.

Source code in src/topmark/presentation/shared/registry.py

def build_bindings_human_report(
    *,
    show_details: bool,
    verbosity_level: int,
    styled: bool,
) -> BindingsHumanReport:
    """Build a Click-free report used by TEXT and MARKDOWN for `bindings`.

    Args:
        show_details: Whether consumers intend to display extended details.
        verbosity_level: Effective TEXT verbosity; Markdown renderers ignore it.
        styled: Whether TEXT renderers should apply styling; Markdown renderers ignore it.

    Returns:
        A `BindingsHumanReport` with effective bindings, unbound file types, and
        currently unused processors.
    """
    raw_bindings: list[BindingInfo] = list_bindings()
    raw_filetypes: list[FileTypeInfo] = list_filetypes()
    raw_processors: list[ProcessorInfo] = list_processors()

    bindings: list[BindingHumanItem] = [
        BindingHumanItem(
            file_type_key=item["file_type_key"],
            file_type_local_key=item["file_type_local_key"],
            file_type_namespace=item["file_type_namespace"],
            processor_key=item["processor_key"],
            processor_local_key=item["processor_local_key"],
            processor_namespace=item["processor_namespace"],
            file_type_description=item["file_type_description"],
            processor_description=item["processor_description"],
        )
        for item in sorted(raw_bindings, key=lambda it: str(it["file_type_key"]))
    ]

    bound_filetype_keys: set[str] = {item.file_type_key for item in bindings}
    unbound_filetypes: list[UnboundFileTypeHumanItem] = [
        UnboundFileTypeHumanItem(
            name=item["qualified_key"],
            description=item["description"],
        )
        for item in sorted(raw_filetypes, key=lambda it: str(it["qualified_key"]))
        if item["qualified_key"] not in bound_filetype_keys
    ]

    unused_processors: list[ProcessorHumanItem] = [
        ProcessorHumanItem(
            local_key=item["local_key"],
            namespace=item["namespace"],
            qualified_key=item["qualified_key"],
            description=item["description"],
            bound=item["bound"],
            line_indent=item["line_indent"],
            line_prefix=item["line_prefix"],
            line_suffix=item["line_suffix"],
            block_prefix=item["block_prefix"],
            block_suffix=item["block_suffix"],
        )
        for item in sorted(raw_processors, key=lambda it: str(it["qualified_key"]))
        if not item["bound"]
    ]

    return BindingsHumanReport(
        show_details=show_details,
        verbosity_level=verbosity_level,
        bindings=tuple(bindings),
        unbound_filetypes=tuple(unbound_filetypes),
        unused_processors=tuple(unused_processors),
        styled=styled,
    )