tomllib — Parse TOML files

Source code: Lib/tomllib

---

This module provides an interface for parsing TOML 1.1.0 (Tom’s Obvious Minimal Language, https://toml.io). This module does not support writing TOML.

Added in version 3.11: The module was added with support for TOML 1.0.0.

Changed in version 3.15: Added TOML 1.1.0 support. See the What’s New for details.

See also

The Tomli-W package is a TOML writer that can be used in conjunction with this module, providing a write API familiar to users of the standard library marshal and pickle modules.

See also

The TOML Kit package is a style-preserving TOML library with both read and write capability. It is a recommended replacement for this module for editing already existing TOML files.

This module defines the following functions:

tomllib.load(fp, /, *, parse_float=float)

tomllib.load(

fp: _typeshed.SupportsRead[bytes],

/,

*,

parse_float: Callable[[str], Any] = ...,

) → dict[str, Any]

(typeshed)

Read a TOML file. The first argument should be a readable and binary file object. Return a dict. Convert TOML types to Python using this conversion table.

parse_float will be called with the string of every TOML float to be decoded. By default, this is equivalent to float(num_str). This can be used to use another datatype or parser for TOML floats (e.g. decimal.Decimal). The callable must not return a dict or a list, else a ValueError is raised.

A TOMLDecodeError will be raised on an invalid TOML document.

tomllib.loads(s, /, *, parse_float=float)

tomllib.loads(

s: str,

/,

*,

parse_float: Callable[[str], Any] = ...,

) → dict[str, Any]

(typeshed)

Load TOML from a str object. Return a dict. Convert TOML types to Python using this conversion table. The parse_float argument has the same meaning as in load().

A TOMLDecodeError will be raised on an invalid TOML document.

The following exceptions are available:

exception tomllib.TOMLDecodeError(msg, doc, pos)

exception tomllib.TOMLDecodeError(msg: str, doc: str, pos: int) → TOMLDecodeError

exception tomllib.TOMLDecodeError(

msg: str | type[Any] = ...,

doc: str | type[Any] = ...,

pos: int | type[Any] = ...,

*args: Any,

) → TOMLDecodeError

(typeshed)

Subclass of ValueError with the following additional attributes:

msg: str

(typeshed)

The unformatted error message.

doc: str

(typeshed)

The TOML document being parsed.

pos: int

(typeshed)

The index of doc where parsing failed.

lineno: int

(typeshed)

The line corresponding to pos.

colno: int

(typeshed)

The column corresponding to pos.

Changed in version 3.14: Added the msg, doc and pos parameters. Added the msg, doc, pos, lineno and colno attributes.

Deprecated since version 3.14: Passing free-form positional arguments is deprecated.

Examples

Parsing a TOML file:

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

Parsing a TOML string:

import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)

Conversion Table

TOML	Python
TOML document	dict
string	str
integer	int
float	float (configurable with parse_float)
boolean	bool
offset date-time	datetime.datetime (tzinfo attribute set to an instance of datetime.timezone)
local date-time	datetime.datetime (tzinfo attribute set to None)
local date	datetime.date
local time	datetime.time
array	list
table	dict
inline table	dict
array of tables	list of dicts