[DicksonWu654]

Summary

Two costs in Container grow with the size of the table rather than with the key being accessed:

• Container.__setitem__ on an existing key ran next(filter(lambda k: k == key, self._map)) to recover the stored Key object, comparing the query against every key in the table. Updating every key of a table therefore takes quadratic time. _map already points to the key's body slot, and that slot holds the stored key, so take it from there.
• item() and __contains__ turned every str query into a SingleKey (which runs key-type detection and builds the quoted form) just to probe _map. SingleKey hashes and compares like its string, so a plain str can probe _map directly. On a miss, NonExistentKey is still built from a SingleKey, so error messages are unchanged.

A container stores only SingleKeys, since dotted keys are split into SingleKeys before they are stored. User-defined Key implementations are not given special handling.

There is no new state, and no change to the public API or pickle format.

Benchmarks

Master is 55d0768. Each pair is two fresh processes pinned to one core with taskset, with the master-first / branch-first order alternating. Each process warms up first (plus 2 s on PyPy) and reports its fastest call. The table shows the median of those times and the median of the per-pair ratios, with their range. The machine is a shared, busy 11-vCPU Linux box (WSL2), so the ranges are wide.

Workload	Python	master	branch	speedup (range)	pairs
2,000 shuffled edits to one table	3.12	1793 ms	277 ms	7.41x (3.43–19.6)	7
parse + those edits + dump	3.12	1844 ms	278 ms	6.62x (3.57–11.1)	7
2,000 shuffled edits to one table	3.14	668 ms	78.6 ms	8.50x (6.05–10.7)	5
2,000 shuffled edits to one table	PyPy 3.11	239 ms	35.7 ms	6.99x (6.03–9.15)	5
read name/version of every package, uv.lock	3.12	0.639 ms	0.189 ms	3.28x (2.82–4.86)	5
read name/version of every package, poetry.lock	3.12	1.19 ms	0.342 ms	3.74x (2.29–6.73)	7
read name/version of every package, uv.lock	3.14	0.639 ms	0.130 ms	4.49x (4.01–6.29)	5
parse uv.lock	3.12	385 ms	354 ms	1.11x (0.80–1.37)	11
parse poetry.lock	3.12	142 ms	170 ms	0.95x (0.62–1.39)	11
parse uv.lock	3.14	343 ms	367 ms	0.97x (0.54–1.11)	9
parse + set every package version + dump, uv.lock	3.12	355 ms	365 ms	0.97x (0.94–1.17)	5

The two 3.12 rows for 2,000 edits, and the poetry.lock lookup row, average each process over at least 0.4 s instead of taking its fastest call.

• 2,000 shuffled edits: a [tool.poetry.dependencies] table with 2,000 entries, with a new version string assigned to every key in random order.
• Lock-file reads: real uv.lock / poetry.lock files.

Parse times, and edits to lock files whose tables have only a few keys, show no measurable change (the bottom rows).

Behaviour checks

• The full suite, including the toml-test submodule, passes on CPython 3.9, 3.12 and 3.14, and on PyPy 3.11. ruff check, ruff format --check and pyupgrade --py39-plus are clean. mypy reports the same errors as on master.
• New tests in tests/test_container_updates.py cover:
  • the stored key's quoting and trivia surviving repeated updates through str, str subclasses and Key queries,
  • updates after deletions and on out-of-order tables,
  • missing-key error messages,
  • no comparisons against unrelated keys.
• A differential check against master compared rendered text, item types and trivia, unwrap() results, edit-then-dump output, and exact exception messages. It covered every TOML file in tests/toml-test and tests/examples plus real lock files. Earlier, roughly 17,000 generated documents and edit sequences on CPython 3.12 and 3.14 were also compared. No differences were found.

Duplicate Check

• I searched the open PRs and found none that already fixes this issue.
• Related open PRs (if any, and why this PR is still needed): Speed up repeated scalar insertion with boundary bisection #576 (for key insertion is linear in size of document #540) speeds up inserting new keys (_get_last_index_before_table / _insert_at). This PR only changes lookups and replacement of existing keys, so the two do not overlap.

Agent Drafting Metadata

• Agent: OpenAI Codex (implementation, tests, benchmarks); Claude Code (independent re-check and PR preparation)
• Model: GPT-6; Claude Opus 5.5
• Notes: Before submission, the change was re-checked independently against master. That re-check reran the full test suite on four interpreters, ran a separate differential check, and repeated the paired benchmarks above.

🤖 Generated with Claude Code

[human-attestation]

🛡️ Human Attestation required. A human needs to confirm this PR once before it can merge.

Attest this PR — sign in with GitHub, pass the challenge, and confirm one of the statements.

[frostming]

unless user code passes in another Key implementation

If we are to ignore this case, can it be further simplified, like using str as the key of self._map? @DicksonWu654

[DicksonWu654]

unless user code passes in another Key implementation

@frostming Yes. I've dropped that case in 05a8246, which removes the _has_custom_keys flag along with the comparison scan it guarded. Now a plain str always probes _map directly, and replacing a key always takes the stored key from its body slot. That's -82/+12 lines against the previous version, and the tests still pass.

I kept _map keyed by Key rather than str. A SingleKey already hashes and compares like its string, so a str lookup hits it without building anything, and switching the key type would change the pickled state and touch most of Container for no extra speed. Happy to do it anyway if you'd prefer it that way.