rtoml

Install rtoml using pip. Requires python>=3.10. Binaries are available for Linux, macOS, and Windows. If no binary is available for your system, you must have rust stable installed to build it from source.

pip install rtoml

When using rtoml to parse TOML files, datetime objects are automatically converted into their corresponding Python types based on the TOML structure:

• Datetime with time: Converted to a datetime.datetime object. If an offset is present in the TOML, it is converted to a timezone-aware object using a TzInfo object.
• Date only: Converted to a datetime.date object.
• Time only: Converted to a datetime.time object.

Offsets are handled via a TzInfo class which represents the UTC offset in hours and minutes.

# Example of how TOML datetimes map to Python
# TOML:
# date = 2023-10-27
# datetime = 2023-10-27T12:00:00Z
# time = 12:00:00

# Python results:
# date -> datetime.date(2023, 10, 27)
# datetime -> datetime.datetime(2023, 10, 27, 12, 0, tzinfo=...) 
# time -> datetime.time(12, 0, 0)

Use dumps() to serialize a Python object to a TOML string, or dump() to write it directly to a file or Path.

Parameters:

• obj: The Python object to serialize.
• pretty: If True, the output uses a more readable format.
• none_value: Controls how None values are handled.
  • If None (default), None values are ignored/omitted from the output.
  • If a string is provided (e.g., '@None'), None values are serialized as that specific string literal.

import rtoml

obj = {'a': 1, 'b': None}

# Serialize to string (None is ignored)
toam_str = rtoml.dumps(obj, none_value=None)

# Serialize to string (None becomes '@None')
toam_str_with_none = rtoml.dumps(obj, none_value='@None')

Use load() to parse a TOML file or file-like object, or loads() to parse a TOML string. Both return a Python dictionary.

Parameters:

• toml: For load(), a str, Path, or file object from open(). For loads(), a str containing TOML.
• none_value: (Optional) A string that specifies which value in the TOML should be loaded as None in Python. By default, it is None, meaning no values are loaded as None.

import rtoml

# From a string
data = rtoml.loads('key = "value"')

# From a file
with open('config.toml', 'r') as f:
    data = rtoml.load(f)

If a Python object cannot be converted to a valid TOML type (e.g., a custom class that doesn't map to a primitive, list, dict, or datetime), the serializer will return a serde::ser::Error.

The error message follows the format: [object_repr] ([type_name]) is not serializable to TOML.

Use the deserialize function to convert a TOML-formatted string into a Python object. You can optionally provide a none_value string to specify which TOML value should be interpreted as Python's None.

import rtoml

toml_str = 'key = "value"'
# Basic deserialization
data = rtoml.deserialize(toml_str)

# Deserialization with a custom None value
toml_with_none = 'key = "@None"'
data = rtoml.deserialize(toml_with_none, none_value='@None')

The current version of the rtoml package is available via the __version__ or VERSION attributes in the module.

import rtoml
print(rtoml.__version__)

Use serialize to convert a Python object into a TOML-formatted string. Use serialize_pretty if you want a human-readable, formatted TOML string. Both functions accept an optional none_value parameter to define how Python None values should be represented in the resulting TOML string.

import rtoml

data = {"key": "value", "other": None}

# Standard serialization
toml_str = rtoml.serialize(data, none_value='@None')

# Pretty-printed serialization
pretty_toml = rtoml.serialize_pretty(data, none_value='@None')

When converting Python objects to TOML, you can control how Python None values are represented in the resulting TOML string.

By default, if none_value is not provided, None values in dictionaries or lists may be skipped or converted to the string `

// Note: This is an internal Rust implementation detail of the serialization logic.
// The behavior is exposed via the `none_value` parameter in `SerializePyObject::new`.
// If `none_value` is set to `Some("@None")`, Python `None` will be serialized as the string "@None" in TOML.
// If `none_value` is `None`, Python `None` values in dictionaries are skipped by default.

When working with rtoml, errors during the conversion process will raise specific Python exceptions:

• TomlParsingError: Raised when the input TOML string is malformed or cannot be parsed.
• TomlSerializationError: Raised when a Python object cannot be converted into a valid TOML representation.

import rtoml

try:
    data = rtoml.deserialize("invalid = [unclosed bracket")
except rtoml.TomlParsingError as e:
    print(f"Parsing failed: {e}")

try:
    # Attempting to serialize something incompatible with TOML
    rtoml.serialize({"set": {1, 2, 3}})
except rtoml.TomlSerializationError as e:
    print(f"Serialization failed: {e}")

The TzInfo class is used internally and exposed via the rtoml._rtoml module to represent UTC offsets for timezone-aware datetime objects. It implements standard Python datetime interface methods.

Methods:

• seconds(): Returns the total offset in seconds.
• utcoffset(dt): Returns a datetime.timedelta representing the offset.
• tzname(dt): Returns the timezone name as a string (e.g., "UTC" or "UTC+05:30").
• dst(dt): Returns None (Daylight Saving Time is not supported/calculated).
• __str__(): Returns the string representation of the offset (e.g., "UTC+01:00").

# Note: TzInfo is part of the rtoml._rtoml module
# It is primarily used as the tzinfo for datetime objects parsed from TOML.