Skip to content

gh-156414: Document tomllib's limits & "extensions" #156415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
encukou wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −0
Open

gh-156414: Document tomllib's limits & "extensions" #156415

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions Doc/library/tomllib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +166 to +167

@hauntsaninja hauntsaninja Aug 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When writing portable TOML files, consider only using features that are
guaranteed or recommended by the standard.
When writing portable TOML files, only use features that are
guaranteed or recommended by the standard.

we shouldn't hedge, this is the only way to be portable


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.
Comment on lines +172 to +173

@timhoffm timhoffm Aug 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be something like

Suggested change
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.

As is I found it a bit unclear whether the unconditional mention of "Key/value pairs in TOML documents and tables" refers to the spec or the concrete impolementation.


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