Skip to content

topmark.toml.utils

topmark / toml / utils

Small helpers for building and normalizing TopMark TOML values and tables.

These helpers keep TOML construction and rendering code concise while preserving the strict invariant enforced by TomlValue: absent values must be omitted from TopMark TOML tables rather than represented explicitly as None.

This module also contains small, side-effect-free builders for TOML-compatible list values whose static types remain compatible with TomlValue under Pyright strict mode.

insert_if_present 

insert_if_present(table, key, value)

Insert a TOML key only when a value is present.

Parameters:

Name Type Description Default
table TomlTable

TOML table being constructed.

 required
key str

TOML key to insert.

 required
value TomlValue | None

TOML value to store. When None, the key is omitted.

 required
Source code in src/topmark/toml/utils.py 
41
42
43
44
45
46
47
48
49
50
def insert_if_present(table: TomlTable, key: str, value: TomlValue | None) -> None:
    """Insert a TOML key only when a value is present.

    Args:
        table: TOML table being constructed.
        key: TOML key to insert.
        value: TOML value to store. When `None`, the key is omitted.
    """
    if value is not None:
        table[key] = value

strip_none_for_toml 

strip_none_for_toml(value)

Remove TOML-incompatible None values from nested TOML-shaped data.

TOML has no null. During rendering, keys with None values are omitted and None items are dropped from lists.

Notes
  • The input is typed as object (not Any) so Pyright does not treat mapping/list iterators as Unknown.
  • Mapping keys are defensively normalized to strings, since TOML tables are string-keyed.
Source code in src/topmark/toml/utils.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def strip_none_for_toml(value: object) -> object:
    """Remove TOML-incompatible `None` values from nested TOML-shaped data.

    TOML has no `null`. During rendering, keys with `None` values are omitted
    and `None` items are dropped from lists.

    Notes:
        - The input is typed as `object` (not `Any`) so Pyright does not treat
        mapping/list iterators as `Unknown`.
        - Mapping keys are defensively normalized to strings, since TOML tables
        are string-keyed.
    """
    # Recursively normalize mappings/lists into TOML-compatible plain-Python
    # shapes while dropping `None` entries.
    if isinstance(value, Mapping):
        out: dict[str, object] = {}
        m: Mapping[object, object] = cast("Mapping[object, object]", value)
        for k_any, v_any in m.items():
            if v_any is None:
                logger.debug("Ignoring `None` entry in Mapping for key %s", k_any)
                continue
            k: str = k_any if isinstance(k_any, str) else str(k_any)
            out[k] = strip_none_for_toml(v_any)
        return out

    if isinstance(value, list):
        out_list: list[object] = []
        seq: list[object] = cast("list[object]", value)
        for v_any in seq:
            if v_any is None:
                logger.debug("Ignoring `None` entry in list")
                continue
            out_list.append(strip_none_for_toml(v_any))
        return out_list

    return value

as_toml_string_list 

as_toml_string_list(values)

Return a TOML-compatible list of strings.

Pyright treats list[str] as incompatible with the recursive TomlValue alias because list is invariant. Building the list through the wider element type keeps TOML serializer code strict-typing friendly without casts.

Parameters:

Name Type Description Default
values Iterable[str]

String values to expose as a TOML-compatible list.

 required

Returns:

Type Description
list[TomlValue]

A list whose static type is compatible with TomlValue.
Source code in src/topmark/toml/utils.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def as_toml_string_list(values: Iterable[str]) -> list[TomlValue]:
    """Return a TOML-compatible list of strings.

    Pyright treats `list[str]` as incompatible with the recursive `TomlValue`
    alias because `list` is invariant. Building the list through the wider
    element type keeps TOML serializer code strict-typing friendly without
    casts.

    Args:
        values: String values to expose as a TOML-compatible list.

    Returns:
        A list whose static type is compatible with `TomlValue`.
    """
    result: list[TomlValue] = list(values)
    return result

as_toml_table_list 

as_toml_table_list(values)

Return a TOML-compatible list of TOML tables.

This helper mirrors as_toml_string_list, but for iterables of TOML tables that need to be stored in a list position accepted by TomlValue.

Parameters:

Name Type Description Default
values Iterable[TomlTable]

TOML tables to expose as a TOML-compatible list.

 required

Returns:

Type Description
list[TomlValue]

A list whose static type is compatible with TomlValue.
Source code in src/topmark/toml/utils.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def as_toml_table_list(values: Iterable[TomlTable]) -> list[TomlValue]:
    """Return a TOML-compatible list of TOML tables.

    This helper mirrors `as_toml_string_list`, but for iterables of TOML
    tables that need to be stored in a list position accepted by `TomlValue`.

    Args:
        values: TOML tables to expose as a TOML-compatible list.

    Returns:
        A list whose static type is compatible with `TomlValue`.
    """
    result: list[TomlValue] = list(values)
    return result