From e14d18b6a3deb31028329273d070972b064abcd1 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 26 Aug 2026 14:12:24 +0200 Subject: [PATCH 1/2] Document tomllib's limits & extensions --- Doc/library/tomllib.rst | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/Doc/library/tomllib.rst b/Doc/library/tomllib.rst index 55610784362eb84..91bac216e800ccb 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, consider only using features that are +guaranteed or recommended by the standard. + +The implementation details listed here may change in future versions of Python. + +Tables/dicts + Key/value pairs in TOML documents and tables are not guaranteed 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. From 00640b0e6e053e9057a40fa4890e0e675dcd69da Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 2 Sep 2026 15:42:00 +0200 Subject: [PATCH 2/2] Apply batched suggestions from code review 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 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/tomllib.rst b/Doc/library/tomllib.rst index 91bac216e800ccb..0a6b9d9d9fad4d0 100644 --- a/Doc/library/tomllib.rst +++ b/Doc/library/tomllib.rst @@ -163,14 +163,14 @@ 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, consider only using features that are +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 - Key/value pairs in TOML documents and tables are not guaranteed to be - in any specific order. + 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