From 7cb3051dc304a0cf8da73a647b259a4dc215ea39 Mon Sep 17 00:00:00 2001 From: Daniel Stutzbach Date: Fri, 17 Dec 2010 16:31:32 +0000 Subject: [PATCH] Issue 8753: Added documentation for Py_ReprEntr and Py_ReprLeave. --- Doc/c-api/exceptions.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 894652eb9b27..db46902e9c37 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -533,6 +533,35 @@ recursion depth automatically). Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each *successful* invocation of :c:func:`Py_EnterRecursiveCall`. +Properly implementing :attr:`tp_repr` for container types requires +special recursion handling. In addition to protecting the stack, +:attr:`tp_repr` also needs to track objects to prevent cycles. The +following two functions facilitate this functionality. Effectively, +these are the C equivalent to :func:`reprlib.recursive_repr`. + +.. c:function:: int Py_ReprEntr(PyObject *object) + + Called at the beginning of the :attr:`tp_repr` implementation to + detect cycles. + + If the object has already been processed, the function returns a + positive integer. In that case the :attr:`tp_repr` implementation + should return a string object indicating a cycle. As examples, + :class:`dict` objects return ``{...}`` and :class:`list` objects + return ``[...]``. + + The function will return a negative integer if the recursion limit + is reached. In that case the :attr:`tp_repr` implementation should + typically return ``NULL``. + + Otherwise, the function returns zero and the :attr:`tp_repr` + implementation can continue normally. + +.. c:function:: void Py_ReprLeave(PyObject *object) + + Ends a :c:func:`Py_ReprEntr`. Must be called once for each + invocation of :c:func:`Py_ReprEntr` that returns zero. + .. _standardexceptions: -- 2.47.3