:mod:`!tomllib` --- Parse TOML files
Python 3.14 Docs · نسخهٔ 3.14.10 · PSF License
:mod:!tomllib --- Parse TOML files
:synopsis: Parse TOML files.
Source code: Lib/tomllib
--------------
This module provides an interface for parsing TOML 1.0.0 (Tom's Obvious Minimal Language, https://toml.io <https://toml.io/en/>_). This module does not support writing TOML.
Be cautious when parsing data from untrusted sources. A malicious TOML string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended.
The Tomli-W package <tomli-w> 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.
The TOML Kit package <tomlkit> 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:
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 <toml-to-py-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.
Load TOML from a str object. Return a dict. Convert TOML types to Python using this conversion table <toml-to-py-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:
Subclass of ValueError with the following additional attributes:
The unformatted error message.
The TOML document being parsed.
The index of *doc* where parsing failed.
The line corresponding to *pos*.
The column corresponding to *pos*.
Added the *msg*, *doc* and *pos* parameters. Added the msg, doc, pos, lineno and colno attributes.
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 |
+------------------+--------------------------------------------------------------------------------------+