topmark.core.merge¶

Merge and extraction helpers for TopMark configuration.

This module centralizes small, typed utilities used across TopMark for:

1) Overlay merges of optional values (e.g., "use override if provided, else keep current").

2) Extracting typed optional values from config mappings (e.g., TOML tables), returning None when the key is absent.

These helpers intentionally avoid importing TopMark configuration models to prevent type-check-time import cycles. They are safe to use in topmark.config, topmark.pipeline, CLI code, and plugins.

Design principles: - Absent keys should generally map to None (inherit), not to a default. - Extraction helpers are conservative: invalid values return None so the caller can decide whether to warn, error, or keep defaults.

overlay ¶

overlay(*, current, override)

Return override when set, otherwise return current.

This is the core "last-wins overlay" primitive used throughout config merging.

Parameters:

Name	Type	Description	Default
`current`	`T \| None`	The current value (possibly inherited).	required
`override`	`T \| None`	The overriding value (highest precedence). `None` means "unset".	required

Returns:

Type	Description
`T \| None`	The override value if it is not `None`, otherwise the current value.

Source code in src/topmark/core/merge.py

def overlay(*, current: T | None, override: T | None) -> T | None:
    """Return `override` when set, otherwise return `current`.

    This is the core "last-wins overlay" primitive used throughout config merging.

    Args:
        current: The current value (possibly inherited).
        override: The overriding value (highest precedence). `None` means "unset".

    Returns:
        The override value if it is not `None`, otherwise the current value.
    """
    return override if override is not None else current

opt_bool ¶

opt_bool(tbl, *, key)

Return an optional bool value from a mapping.

Parameters:

Name	Type	Description	Default
`tbl`	`Mapping[str, object] \| None`	Mapping (e.g., a parsed TOML table). If `None`, returns `None`.	required
`key`	`str`	Key to read.	required

Returns:

Type	Description
`bool \| None`	`None` if `tbl` is falsy or `key` is absent.
`bool \| None`	`bool(tbl[key])` otherwise.

Notes

This mirrors TOML parsing behavior in TopMark today: values are coerced via bool(...). If you later want stricter typing (only accept actual booleans), introduce a strict_opt_bool() variant.

Source code in src/topmark/core/merge.py

def opt_bool(tbl: Mapping[str, object] | None, *, key: str) -> bool | None:
    """Return an optional bool value from a mapping.

    Args:
        tbl: Mapping (e.g., a parsed TOML table). If `None`, returns `None`.
        key: Key to read.

    Returns:
        - `None` if `tbl` is falsy or `key` is absent.
        - `bool(tbl[key])` otherwise.

    Notes:
        This mirrors TOML parsing behavior in TopMark today: values are coerced
        via `bool(...)`. If you later want stricter typing (only accept actual
        booleans), introduce a `strict_opt_bool()` variant.
    """
    if not tbl or key not in tbl:
        return None
    return bool(tbl[key])

opt_enum ¶

opt_enum(tbl, *, key, enum_cls)

Return an optional Enum member from a mapping.

Parameters:

Name	Type	Description	Default
`tbl`	`Mapping[str, object] \| None`	Mapping (e.g., a parsed TOML table). If `None`, returns `None`.	required
`key`	`str`	Key to read.	required
`enum_cls`	`type[E]`	Enum class used to interpret the value.	required

Returns:

Type	Description
`E \| None`	`None` if `tbl` is falsy or `key` is absent.
`E \| None`	An enum member when `tbl[key]` can be converted via `enum_cls(value)`.
`E \| None`	`None` when conversion fails (invalid/unknown value).

Examples:

mode = opt_enum(tbl, key="empty_insert_mode", enum_cls=EmptyInsertMode)

Source code in src/topmark/core/merge.py

def opt_enum(tbl: Mapping[str, object] | None, *, key: str, enum_cls: type[E]) -> E | None:
    """Return an optional Enum member from a mapping.

    Args:
        tbl: Mapping (e.g., a parsed TOML table). If `None`, returns `None`.
        key: Key to read.
        enum_cls: Enum class used to interpret the value.

    Returns:
        - `None` if `tbl` is falsy or `key` is absent.
        - An enum member when `tbl[key]` can be converted via `enum_cls(value)`.
        - `None` when conversion fails (invalid/unknown value).

    Examples:
        ```py
        mode = opt_enum(tbl, key="empty_insert_mode", enum_cls=EmptyInsertMode)
        ```
    """
    if not tbl or key not in tbl:
        return None

    val = tbl[key]
    try:
        # Accept member values ("logical_empty") and already-typed members.
        return enum_cls(val)
    except (ValueError, TypeError):
        return None