topmark.toml.loaders

topmark / toml / loaders

Load and split-parse TopMark TOML documents.

This module provides low-level file I/O helpers for reading TOML documents from the filesystem, normalizing them to plain-Python TOML tables, and turning one TopMark TOML source into a per-source split parse result.

Responsibilities

• read raw TOML documents from disk
• normalize tomlkit output into TomlTable
• extract [tool.topmark] from pyproject.toml sources when needed
• delegate per-source split parsing to parse_topmark_toml_table

This module does not deserialize layered config into MutableConfig and does not resolve precedence across multiple sources.

load_topmark_toml_table

load_topmark_toml_table(
    data, *, source_path=None, from_pyproject=False
)

Validate and split-parse an in-memory TopMark TOML source table.

Validates whether data complies with the expected TopMark TOML document schema, and split-parses data subsequently.

Parameters:

Name	Type	Description	Default
data	TomlTable	In-memory TOML table representing either a full TopMark TOML document or a parsed pyproject.toml document.	required
source_path	Path | None	Optional source path used only for diagnostics/logging.	None
from_pyproject	bool	If True, first extract [tool.topmark] from the TOML document before split parsing.	False

Returns:

Type	Description
ParsedTopmarkToml | None	The per-source split parse result, or None when from_pyproject=True
ParsedTopmarkToml | None	and no valid [tool.topmark] table is present.

Source code in src/topmark/toml/loaders.py

def load_topmark_toml_table(
    data: TomlTable,
    *,
    source_path: Path | None = None,
    from_pyproject: bool = False,
) -> ParsedTopmarkToml | None:
    """Validate and split-parse an in-memory TopMark TOML source table.

    Validates whether `data` complies with the expected TopMark TOML document schema,
    and split-parses `data` subsequently.

    Args:
        data: In-memory TOML table representing either a full TopMark TOML
            document or a parsed `pyproject.toml` document.
        source_path: Optional source path used only for diagnostics/logging.
        from_pyproject: If `True`, first extract `[tool.topmark]` from the TOML
            document before split parsing.

    Returns:
        The per-source split parse result, or `None` when `from_pyproject=True`
        and no valid `[tool.topmark]` table is present.
    """
    # `pyproject.toml` embeds TopMark settings under `[tool.topmark]`; plain
    # `topmark.toml` already exposes the relevant source table directly.
    source_label: str = str(source_path) if source_path is not None else "<in-memory TOML>"

    if from_pyproject:
        topmark_tbl: TomlTable | None = extract_pyproject_topmark_table(data)
        if topmark_tbl is None:
            logger.debug("No [tool.topmark] table found in %s", source_label)
            return None
    else:
        topmark_tbl = data
        if not topmark_tbl:
            logger.debug("Empty TopMark TOML data found in %s", source_label)

    # Validate the TOML schema
    issues: tuple[TomlValidationIssue, ...] = TOPMARK_TOML_SCHEMA.validate(
        topmark_tbl,
        mode=TomlValidationMode.INPUT,
    )

    # Delegate semantic splitting of the TOML source to the pure parser layer.
    return parse_topmark_toml_table(
        topmark_tbl,
        validation_issues=issues,
    )

load_topmark_toml_source

load_topmark_toml_source(path)

Load and split-parse one TopMark TOML source file.

Parameters:

Name	Type	Description	Default
path	Path	Path to a TopMark TOML source file.	required

Returns:

Type	Description
ParsedTopmarkToml | None	The per-source split parse result, or None when the file cannot be
ParsedTopmarkToml | None	loaded or does not contain a valid TopMark TOML source table.

Source code in src/topmark/toml/loaders.py

def load_topmark_toml_source(path: Path) -> ParsedTopmarkToml | None:
    """Load and split-parse one TopMark TOML source file.

    Args:
        path: Path to a TopMark TOML source file.

    Returns:
        The per-source split parse result, or `None` when the file cannot be
        loaded or does not contain a valid TopMark TOML source table.
    """
    data: TomlTable | None = _load_toml_table(path)
    if data is None:
        return None

    return load_topmark_toml_table(
        data,
        source_path=path,
        from_pyproject=path.name == "pyproject.toml",
    )