Skip to content

fix: Avoid infinite loop when cross-reference keyspace is exhausted#334

Open
jonashaag wants to merge 3 commits into
mkdocstrings:mainfrom
jonashaag:fix-stash-crossref-keyspace-exhaustion
Open

fix: Avoid infinite loop when cross-reference keyspace is exhausted#334
jonashaag wants to merge 3 commits into
mkdocstrings:mainfrom
jonashaag:fix-stash-crossref-keyspace-exhaustion

Conversation

@jonashaag

@jonashaag jonashaag commented Jul 18, 2026

Copy link
Copy Markdown

Full disclosure: Written by GPT 5.6 Sol.

This fixes a problem with our docs build.


Cross-reference stash keys start with _ and preserve the rendered identifier length. One-character and two-character identifiers therefore share a keyspace of only 62 keys. Once all keys are present, _gen_stash_key retries random choices forever.

This became reproducible for attribute values after 2.0.5 started rendering their source-level names: a large value containing more than 62 references through the same one-character module alias hangs the documentation build.

Detect an exhausted key length and expand subsequent keys by one character. Non-exhausted keyspaces retain the existing same-length behavior.

Validation:

  • Focused rendering tests: 42 passed
  • Full test suite: passed
  • Downstream strict MkDocs build with 75 one-character alias references: passed

@jonashaag
jonashaag marked this pull request as draft July 18, 2026 18:08
@jonashaag

Copy link
Copy Markdown
Author

CI follow-up: the unrelated matrix failures are fixed in separate commits. Snapshot fixtures are checked out with LF on Windows; the docs inventory is only consumed by highest-resolution jobs; the global PyO3 ABI3 override was removed so current Pydantic builds on Python 3.15; and lowest-direct is limited to Python 3.10–3.13 because the minimum Pydantic stack cannot build on 3.14/3.15. The latest run is 31/31 green: https://github.com/mkdocstrings/python/actions/runs/29655904249

@jonashaag
jonashaag marked this pull request as ready for review July 18, 2026 18:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant