[faresrafat3]

Fixes #309.

This is the documentation update that #309 ends up calling for. The maintainer of Tomli
agreed in that issue that invalid TOML should stay distinguishable from an error caused
by an implementation limit, and that the RecursionError case needed documenting too:

I think it's good that invalid TOML can be distinguished from an error resulting from
implementation limitations of Tomli. Perhaps this and the RecursionError (caused by
deeply nested inline table or array) need documenting though?

@encukou suggested the wording, and this implements it:

I think it would be enough to say something like "Note that Tomli may raise a different
exception if an implementation-defined limit is exceeded, such as RecursionError for
deeply nested tables or ValueError for extremely large integers."

The note is added to the "Handle invalid TOML" section of the README, right after the
example: TOMLDecodeError covers invalid TOML only, while errors caused by Tomli's own
implementation limits propagate unchanged, because the document may be valid TOML that
this implementation cannot represent.

One wording adjustment against the suggestion above: the note says "deeply nested inline
tables or arrays" rather than "deeply nested tables". The maintainer's comment above
spoke of a "deeply nested inline table or array", so the note names both.

Verification

Checked against master (2.5.0) by running the library from this branch under
CPython 3.12:

>>> import tomli
>>> tomli.loads("a = " + "1" * 4301)
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 4301 digits; use sys.set_int_max_str_digits() to increase the limit
>>> tomli.loads("a = " + "[" * 402 + "]" * 402)
RecursionError: TOML inline arrays/tables are nested more than the allowed 400 levels
>>> tomli.loads("a = " + "{x=" * 402 + "1" + "}" * 402)
RecursionError: maximum recursion depth exceeded
>>> tomli.loads("]] this is invalid TOML [[")
tomli._parser.TOMLDecodeError: Invalid statement (at line 1, column 1)

The two errors named in the note are distinct: an oversized integer raises a plain
ValueError, and deep nesting raises RecursionError. Both are limits of the
implementation rather than of TOML, which is why the note calls them
"implementation-defined".

mdformat --check README.md passes locally with the versions pinned in
.pre-commit-config.yaml, and the full CI matrix is green.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (43a86ad) to head (47968f4).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #310   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         4           
  Lines          535       535           
  Branches       100       100           
=========================================
  Hits           535       535           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[faresrafat3]

Hi @hukkin — checking in on this PR. It documents the implementation-limit errors that tomli can raise. CI is green and all tests pass. Let me know if there's anything you'd like me to adjust.

[faresrafat3]

Thanks for the review @hukkin! I've updated the PR to document the implementation-limit errors that tomli can raise. CI is green and all tests pass. Let me know if there's anything else you'd like me to adjust.

[encukou]

I think it would be enough to say something like “Note that Tomli may raise a different exception if an implementation-defined limit is exceeded, such as RecursionError for deeply nested tables or ValueError for extremely large integers.”

[faresrafat3]

Done — replaced the expanded explanation with exactly that wording. The worked examples and the ValueError subclassing note are gone; it is now the single note you suggested. Thanks for the steer.

[faresrafat3]

Hi @encukou — the PR now carries exactly the wording you suggested, replacing the expanded explanation:

Note that Tomli may raise a different exception if an implementation-defined limit is exceeded, such as RecursionError for deeply nested tables or ValueError for extremely large integers.

The worked examples and the ValueError subclassing note are gone. It is the single note, nothing else. CI is green and all tests pass.

Ready for review whenever you get to it — happy to adjust further if it still needs trimming.

[faresrafat3]

Rebased this onto current master and squashed it into a single commit, so the diff is
now just the one note.

The wording is the one @encukou suggested, with one adjustment: it says "deeply nested
inline tables or arrays" rather than "deeply nested tables", to match the phrase used in
#309.

The commit is now signed with my verified GitHub address, so it is attributed to my
account rather than showing up as an unattributed commit.

The verification section in the description lists the actual output on master, which
includes a limit I had stated wrong before: nested inline arrays raise RecursionError
at 400 levels (MAX_INLINE_NESTING), while nested inline tables hit Python's own
recursion limit. The note itself does not state a number, since both limits are
implementation details that can change.