Doc/library/tomllib.rst

: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.