| :mod:`!tomllib` --- Parse TOML files |
| ==================================== |
| |
| .. module:: tomllib |
| :synopsis: Parse TOML files. |
| |
| **Source code:** :source:`Lib/tomllib` |
| |
| -------------- |
| |
| This module provides an interface for parsing TOML 1.1.0 (Tom's Obvious Minimal |
| Language, `https://toml.io <https://toml.io/en/>`_). This module does not |
| support writing TOML. |
| |
| .. versionadded:: 3.11 |
| The module was added with support for TOML 1.0.0. |
| |
| .. versionchanged:: 3.15 |
| Added TOML 1.1.0 support. |
| See the :ref:`What's New <whatsnew315-tomllib-1-1-0>` for details. |
| |
| .. warning:: |
| |
| 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. |
| |
| .. seealso:: |
| |
| The :pypi:`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 |
| :mod:`marshal` and :mod:`pickle` modules. |
| |
| .. seealso:: |
| |
| The :pypi:`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: |
| |
| .. function:: load(fp, /, *, parse_float=float) |
| |
| Read a TOML file. The first argument should be a readable and binary file object. |
| Return a :class:`dict`. Convert TOML types to Python using this |
| :ref:`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. :class:`decimal.Decimal`). The callable must not return a |
| :class:`dict` or a :class:`list`, else a :exc:`ValueError` is raised. |
| |
| A :exc:`TOMLDecodeError` will be raised on an invalid TOML document. |
| |
| |
| .. function:: loads(s, /, *, parse_float=float) |
| |
| Load TOML from a :class:`str` object. Return a :class:`dict`. Convert TOML |
| types to Python using this :ref:`conversion table <toml-to-py-table>`. The |
| *parse_float* argument has the same meaning as in :func:`load`. |
| |
| A :exc:`TOMLDecodeError` will be raised on an invalid TOML document. |
| |
| |
| The following exceptions are available: |
| |
| .. exception:: TOMLDecodeError(msg, doc, pos) |
| |
| Subclass of :exc:`ValueError` with the following additional attributes: |
| |
| .. attribute:: msg |
| |
| The unformatted error message. |
| |
| .. attribute:: doc |
| |
| The TOML document being parsed. |
| |
| .. attribute:: pos |
| |
| The index of *doc* where parsing failed. |
| |
| .. attribute:: lineno |
| |
| The line corresponding to *pos*. |
| |
| .. attribute:: colno |
| |
| The column corresponding to *pos*. |
| |
| .. versionchanged:: 3.14 |
| Added the *msg*, *doc* and *pos* parameters. |
| Added the :attr:`msg`, :attr:`doc`, :attr:`pos`, :attr:`lineno` and :attr:`colno` attributes. |
| |
| .. deprecated:: 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-to-py-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 | |
| +------------------+--------------------------------------------------------------------------------------+ |
| |
| Limits and interoperability considerations |
| ------------------------------------------ |
| |
| :mod:`!tomllib` places some limits on the documents it can handle, |
| and it preserves details that other TOML parsers are allowed to ignore. |
| When writing portable TOML files, only use features that are |
| guaranteed or recommended by the standard. |
| |
| The implementation details listed here may change in future versions of Python. |
| |
| Tables/dicts |
| The TOML spec does not guarantee key/value pairs in TOML documents and |
| tables to be in any specific order. |
| |
| .. impl-detail:: |
| :mod:`!tomllib` loads dictionary entries in the order they appear in |
| the source. |
| |
| Integers |
| TOML recommends supporting integers in ``range(−2**63, 2**63)``. |
| |
| .. impl-detail:: |
| :mod:`!tomllib` uses :ref:`Python's limit on integer string conversion |
| <int_max_str_digits>` (4300 digits by default). |
| |
| Floats |
| TOML recommends supporting at least IEEE 754 binary64 values, |
| which means that numbers with more than 15 significant decimal digits |
| are likely to be rounded. |
| |
| .. impl-detail:: |
| :mod:`!tomllib` uses Python :class:`float` by default; |
| on many common platforms this is the recommended binary64. |
| See :data:`sys.float_info` for details. |
| |
| Nesting limit |
| TOML 1.1.0 does not recommend a limit on how deeply arrays and tables |
| may be nested inside one another. |
| (A limit of 100 has been proposed for a future version of TOML.) |
| |
| .. impl-detail:: |
| In :mod:`!tomllib`, the nesting level is mainly limited by Python's |
| :func:`recursion limit <sys.getrecursionlimit>`. |
| Note that code that calls :mod:`!tomllib` may contribute to the limit. |
