From a6eeb45a516d6c84c1af6af6b525efb29af607eb Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 2 Sep 2026 15:59:57 +0200 Subject: [PATCH] gh-156414: Document tomllib's limits & "extensions" (GH-156415) (cherry picked from commit 3c7e975001f0a96b63b33346fb1faab75d0035ee) Co-authored-by: Petr Viktorin Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- Doc/library/tomllib.rst | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/Doc/library/tomllib.rst b/Doc/library/tomllib.rst index 55610784362eb84..0a6b9d9d9fad4d0 100644 --- a/Doc/library/tomllib.rst +++ b/Doc/library/tomllib.rst @@ -157,3 +157,48 @@ Conversion Table +------------------+--------------------------------------------------------------------------------------+ | 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 + ` (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 `. + Note that code that calls :mod:`!tomllib` may contribute to the limit.