TOML¶

The toml-tstring package provides render_data, render_text, and render_result for TOML templates.

Application config example¶

This example builds a TOML configuration with interpolated table headers, keys, datetime values, and multiline strings:

"""Tutorial example: build a TOML application config from a PEP 750 template."""

from __future__ import annotations

from datetime import UTC, date, datetime, time

from _display import print_walkthrough
from toml_tstring import render_result


def main() -> None:
    service_name = "billing"
    owner = "platform-team"
    region = "us-east-1"
    environment = "production"
    launch_at = datetime(2026, 3, 14, 9, 30, tzinfo=UTC)
    business_day = date(2026, 3, 14)
    office_hours = time(9, 30)
    retries = [1, 2, 5]

    template = t'''\
[services.{service_name}]
owner = {owner}
launch_at = {launch_at}
business_day = {business_day}
office_hours = {office_hours}
welcome = """Welcome {owner}
Running in {environment}
Region {region}"""
release_label = {service_name}-{environment}

[services.{service_name}.labels]
{region} = {environment}

[services.{service_name}.retry]
schedule = {retries}
'''

    result = render_result(template)

    print_walkthrough(
        title="TOML",
        template=template,
        result=result,
        notes=[
            "The service name is interpolated into table headers.",
            "The region is interpolated into a TOML key position.",
            "The multiline welcome message starts life as a readable TOML string.",
            "datetime, date, and time values render as TOML-native literals.",
            (
                "Bare scalar assembly such as {service_name}-{environment} "
                "becomes a string."
            ),
        ],
    )


if __name__ == "__main__":
    main()

What to notice¶

The service name is interpolated into table headers: [services.{service_name}]
The region is interpolated into a TOML key position: {region} = {environment}
The multiline welcome message starts life as a readable TOML string
datetime, date, and time values render as TOML-native literals
Bare scalar assembly like {service_name}-{environment} becomes a string

Interpolation contexts¶

Context	Example	Description
Whole value	`key = {val}`	Any TOML-representable Python value
Table header	`[{name}]`	Must be `str`
Key	`{key} = value`	Must be `str`
String fragment	`"hello {name}"`	Inserted inside a TOML string

Supported types¶

str, int, float, bool
list (rendered as TOML arrays)
dict (rendered as inline tables or nested tables)
datetime, date, time (rendered as TOML-native datetime literals)

Warning

TOML has no null value — None is rejected. Offset-aware time values are also rejected.

Profiles¶

Profile	Description	Default
`1.1`	TOML 1.1 (inline table newlines, trailing commas, `\e`/`\xHH` escapes, times without seconds)	Yes
`1.0`	TOML 1.0	No

from toml_tstring import render_data

# Use TOML 1.1 features (default)
data = render_data(template)

# Restrict to TOML 1.0 behavior
data = render_data(template, profile="1.0")