[Dcastroro]

Fixes #157. Formatting a dictionary or other expanded object that points back to itself can exhaust the recursion limit and prevent debug() from showing its contents.

Track object identities only along the active formatting path. Render a repeated ancestor as <Recursion on TYPE>, then continue with the remaining fields. Remove identities in finally, so shared children are formatted normally in each branch and formatting errors do not leave stale state. The same tracking handles reentrant calls from __repr__ without changing the existing stream restoration.

Adds documentation and 12 tests covering self/mutual container cycles, dataclasses with and without slots, __pretty__, a self-yielding generator, reentrant __repr__, repeated shared children, recovery after an exception and debug.format().

Validation on Windows:

• New tests against the unchanged base: 10 failed, 2 passed; with the fix: 12 passed.
• Full suite on Python 3.13.14: 160 passed, 4 skipped, 1 xfailed, 1 xpassed. The original suite had 148 passed with the same remaining statuses.
• Full suite on Python 3.10.20: 160 passed, 4 skipped, 2 xfailed, using the existing frozen lockfile.
• Ruff checks/format, strict basedpyright (with the test virtualenv selected explicitly), documentation examples and strict Zensical build passed. Full diff review and git diff --check passed.

The inherited NO_COLOR environment variable causes the existing test_print_is_tty to fail on both base and patched code. The full-suite results above omit only that variable from the test subprocess environment; repository settings and tests are unchanged. The hosted OS/Python CI matrix remains to be verified.

No new dependencies, credentials, network/API calls in the new tests, or changes to workflows/security checks.

AI disclosure: Codex investigated the issue, implemented the change and tests, reviewed the diff, and ran the validation above.

---

Summary by cubic

Fixes recursive objects causing an infinite recursion error in debug() and PrettyFormat. Repeated ancestors are now rendered as <Recursion on TYPE> and formatting continues with the remaining fields.

• Tracks object identities only on the active formatting path, using finally so shared children format normally in each branch and errors don't leave stale state.
• Handles reentrant calls from __repr__, containers, dataclasses, __pretty__, and generators; values within simple_cutoff keep Python's compact ... recursion notation.
• Adds 12 tests and documentation examples.

^{Written for commit 9b2da78. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic</sub>

[Copilot]

🔵 Needs a closer look

It modifies the central _format recursion path used by every debug()/pformat call and adds shared mutable state on the module-level singleton, so a human should confirm the broad formatting impact despite no defects being found.

No open issues 🎉

What changed in this PR

This PR fixes issue #157, where debug() / PrettyFormat could exhaust the recursion limit when formatting an object that references itself (directly or mutually). The fix tracks the object identities currently on the active formatting path and renders a repeated ancestor as <Recursion on TYPE> instead of re-expanding it, then continues formatting the remaining fields.

The implementation splits the existing _format into a thin guard (_format) plus the original body (_format_value). The guard records id(value) in a per-instance _active_ids set before recursing and removes it in a finally, so shared (non-ancestor) children still format normally in each branch and formatting errors don't leave stale state. Because the id set is shared across the existing reentrant-stream mechanism, recursion triggered from within a __repr__ is also handled.

Changes:

• Add active-path identity tracking in PrettyFormat._format, emitting <Recursion on TYPE> for repeated ancestors and cleaning up via finally.
• Add docs/usage.md note describing the new recursion handling.
• Add tests/test_recursion.py with 12 tests covering self/mutual cycles, dataclasses (with/without slots), __pretty__, generators, reentrant __repr__, shared children, error recovery, and debug.format().

File	Description
devtools/​prettier.py	Introduces _active_ids guard in _format and extracts the formatting body into _format_value to break circular-reference recursion.
tests/​test_recursion.py	New test module validating recursion rendering across containers, dataclasses, __pretty__, generators, reentrancy, shared children, and error recovery.
docs/​usage.md	Documents that circular references render as <Recursion on TYPE> while other fields and shared objects still format normally.

_{Review effort: Balanced}

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic</sub>