toml

The toml library parses TOML strings into Scriptling objects and serializes Scriptling objects back to TOML strings. Commonly used for configuration files such as pyproject.toml or Cargo.toml.

Available Functions

Functions

loads(toml_string)

Parses a TOML string and returns the corresponding Scriptling object.

Parameters:

• toml_string (str): TOML-formatted string to parse.

Returns: dict, list, str, int, float, bool, or None: depending on the parsed TOML value. Datetimes are returned as ISO-formatted strings.

Raises: Error: if toml_string is not valid TOML, or if it nests more than 100 levels deep. The depth cap is a safeguard: the underlying decoder’s memory grows sharply with nesting, far faster than the input, so a small but deeply nested document could otherwise exhaust the host before any memory limit applies. Real configuration files nest only a few levels. The same cap applies to the TOML the host reads: network policy and secret config files, script metadata, package manifests, and MCP tool, resource and prompt metadata.

import toml

data = toml.loads("""
[database]
host = "localhost"
port = 5432
enabled = true

[servers]
alpha = "10.0.0.1"
beta = "10.0.0.2"
""")

print(data["database"]["host"])  # localhost
print(data["database"]["port"])  # 5432
print(data["servers"]["alpha"])  # 10.0.0.1

dumps(obj)

Converts a Scriptling object to a TOML-formatted string.

Parameters:

• obj (dict, list, str, int, float, bool, or None): Value to serialize.

Returns: str: the TOML-formatted output.

Raises: RecursionError: if obj nests more than 10,000 levels deep. The value would otherwise be cut short and the output silently corrupt.

import toml

data = {
    "title": "My App",
    "database": {
        "host": "localhost",
        "port": 5432
    },
    "features": ["auth", "logging", "api"]
}

toml_str = toml.dumps(data)
print(toml_str)
# title = "My App"
# features = ["auth", "logging", "api"]
#
# [database]
# host = "localhost"
# port = 5432

Complete Example

import toml

config_toml = """
[server]
host = "0.0.0.0"
port = 8080
workers = 4

[database]
url = "postgres://localhost/mydb"
pool_size = 10
timeout = 30.5

[[servers]]
name = "web1"
ip = "10.0.0.1"

[[servers]]
name = "web2"
ip = "10.0.0.2"
"""

config = toml.loads(config_toml)

print("Server host:", config["server"]["host"])
print("Database URL:", config["database"]["url"])

for server in config["servers"]:
    print(f"Server {server['name']}: {server['ip']}")

config["server"]["workers"] = 8
updated_toml = toml.dumps(config)
print(updated_toml)

Supported Types

Python Compatibility

Compared to Python’s tomllib/tomli-w:

• No load() / dump() for file I/O: only string input/output.
• dumps() is provided for writing TOML; Python’s tomllib is read-only (the tomli-w package adds dumps() separately, which this follows the convention of).
• No TOMLDecodeError exception class: parse errors raise a generic Scriptling error.
• Datetime values are returned as ISO-formatted strings rather than datetime objects.

See Also

• json: parse and generate JSON data.
• yaml: parse and generate YAML data.
• scriptling.csv: parse and generate CSV data.
• scriptling.xml: parse and generate XML data.