Skip to content

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

Open
jonashaag wants to merge 1 commit 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 1 commit into
mkdocstrings:mainfrom
jonashaag:fix-stash-crossref-keyspace-exhaustion

Conversation

@jonashaag

@jonashaag jonashaag commented Jul 18, 2026

Copy link
Copy Markdown

For reviewers

  • I did not use AI
  • I used AI and thoroughly reviewed every code/docs change

Description of the change

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.

Relevant resources

@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
@pawamoy

pawamoy commented Jul 20, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution @jonashaag. Can you please send the CI fixes in another PR? And can you also tell your agent to follow our PR template?

@jonashaag jonashaag mentioned this pull request Jul 20, 2026
2 tasks
@jonashaag
jonashaag force-pushed the fix-stash-crossref-keyspace-exhaustion branch from f17308d to ff042bb Compare July 20, 2026 18:21
@jonashaag

Copy link
Copy Markdown
Author

Done, thanks. I split the unrelated CI fixes into #335 and updated this PR description to follow the repository template.

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.

2 participants