Handle circular references while pretty printing

Fixes #157

Assisted-by: OpenAI GPT-6 (Codex)

Author: Dcastroro

devtools/prettier.py

@@ -67,6 +67,7 @@ def __init__(
         yield_from_generators: bool = True,
     ):
         self._stream = io.StringIO()
+        self._active_ids: set[int] = set()
         self._indent_step = indent_step
         self._c = indent_char
         self._repr_strings = repr_strings
@@ -108,6 +109,18 @@ def _format(self, value: Any, indent_current: int, indent_first: bool) -> None:
         if indent_first:
             self._stream.write(indent_current * self._c)
 
+        value_id = id(value)
+        if value_id in self._active_ids:
+            self._stream.write(f'<Recursion on {type(value).__name__}>')
+            return
+
+        self._active_ids.add(value_id)
+        try:
+            self._format_value(value, indent_current)
+        finally:
+            self._active_ids.remove(value_id)
+
+    def _format_value(self, value: Any, indent_current: int) -> None:
         try:
             pretty_func = value.__pretty__
         except AttributeError:

docs/usage.md

@@ -78,6 +78,10 @@ in `debug()`, but it can also be used directly:
 
 --8<-- "examples/prettier.html"
 
+Circular references encountered while formatting containers, object fields or `__pretty__` values
+are displayed as `<Recursion on TYPE>` rather than repeatedly expanding the same object. Other fields
+are still shown, and a shared object that appears in separate branches is formatted normally each time.
+
 For more details on prettier printing, see
 [`prettier.py`](https://github.com/samuelcolvin/python-devtools/blob/main/devtools/prettier.py).
 

tests/test_recursion.py

@@ -0,0 +1,104 @@
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from devtools import Debug
+from devtools.prettier import PrettyFormat, pformat
+
+
+def test_recursive_dict():
+    value: dict[str, Any] = {'before': 1}
+    value['self'] = value
+    value['after'] = 2
+    expected = "{\n    'before': 1,\n    'self': <Recursion on dict>,\n    'after': 2,\n}"
+    assert pformat(value) == expected
+    assert pformat(value) == expected
+
+
+@pytest.mark.parametrize('cutoff', [0, 10])
+def test_recursive_list(cutoff: int):
+    value: list[Any] = [1, 2]
+    value.append(value)
+    assert PrettyFormat(simple_cutoff=cutoff)(value) == '[\n    1,\n    2,\n    <Recursion on list>,\n]'
+
+
+def test_mutually_recursive_containers():
+    value: dict[str, Any] = {}
+    value['child'] = [value, 1]
+    assert pformat(value) == "{\n    'child': [\n        <Recursion on dict>,\n        1,\n    ],\n}"
+
+
+@pytest.mark.parametrize('slots', [False, True])
+def test_recursive_dataclass(slots: bool):
+    @dataclass(slots=slots)
+    class Node:
+        child: Any = None
+
+    value = Node()
+    value.child = value
+    assert pformat(value) == 'Node(\n    child=<Recursion on Node>,\n)'
+
+
+def test_recursive_pretty():
+    class Pretty:
+        def __pretty__(self, fmt: Callable[[Any], Any], skip_exc: type[Exception]) -> Iterator[Any]:
+            yield 'Pretty('
+            yield fmt(self)
+            yield ')'
+
+    assert pformat(Pretty()) == 'Pretty(<Recursion on Pretty>)'
+
+
+def test_recursive_generator():
+    def generate() -> Iterator[Any]:
+        yield value
+        yield 1
+
+    value = generate()
+    assert pformat(value) == '(\n    <Recursion on generator>,\n    1,\n)'
+
+
+def test_recursive_reentrant_repr():
+    formatter = PrettyFormat()
+
+    class Reentrant:
+        def __repr__(self) -> str:
+            return formatter(self)
+
+    assert formatter(Reentrant()) == '<Recursion on Reentrant>'
+    assert formatter(1) == '1'
+
+
+def test_shared_child_is_not_recursive():
+    child = {'value': 1}
+    assert PrettyFormat(simple_cutoff=0)([child, child]) == (
+        "[\n    {\n        'value': 1,\n    },\n    {\n        'value': 1,\n    },\n]"
+    )
+
+
+def test_formatting_error_does_not_mark_value_as_recursive():
+    formatter = PrettyFormat()
+
+    class Broken:
+        fail = True
+
+        def __repr__(self) -> str:
+            if self.fail:
+                raise ValueError('broken repr')
+            return 'recovered'
+
+    value = Broken()
+    with pytest.raises(ValueError, match='broken repr'):
+        formatter(value)
+    value.fail = False
+    assert formatter(value) == 'recovered'
+
+
+def test_debug_recursive_value():
+    value: dict[str, Any] = {'before': 1}
+    value['self'] = value
+    output = str(Debug(highlight=False).format(value))
+    assert "'before': 1" in output
+    assert "'self': <Recursion on dict>" in output