Commitc390756

committed

gh-123241: Document restrictions for tp_traverse implementations

1 parentb3bf212 commitc390756Copy full SHA for c390756

File tree

-0

lines changed

-0

lines changed

Lines changed: 4 additions & 0 deletions

Original file line number	Diff line number	Diff line change
@@ -232,6 +232,10 @@ The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
`232`	`232`	`object argument. If visit returns a non-zero value that value should be`
`233`	`233`	`returned immediately.`
`234`	`234`
	`235`	`+ The traversal function must not have any side effects. Implementations`
	`236`	`+ may not modify the reference counts of any Python objects nor create or`
	`237`	`+ destroy any Python objects.`
	`238`	`+`
`235`	`239`	To simplify writing:c:member:`~PyTypeObject.tp_traverse` handlers, a:c:func:`Py_VISIT` macro is
`236`	`240`	provided. In order to use this macro, the:c:member:`~PyTypeObject.tp_traverse` implementation
`237`	`241`	`must name its arguments exactly visit and arg:`

Lines changed: 5 additions & 0 deletions

Original file line number	Diff line number	Diff line change
@@ -1569,6 +1569,11 @@ and :c:data:`PyType_Type` effectively act as defaults.)
`1569`	`1569`	`but the instance has no strong reference to the elements inside it, as they`
`1570`	`1570`	`are allowed to be removed even if the instance is still alive).`
`1571`	`1571`
	`1572`	`+ ..warning::`
	`1573`	`+ The traversal function must not have any side effects. It must not`
	`1574`	`+ modify the reference counts of any Python objects nor create or destroy`
	`1575`	`+ any Python objects.`
	`1576`	`+`
`1572`	`1577`	Note that:c:func:`Py_VISIT` requires the visit and arg parameters to
`1573`	`1578`	:c:func:`!local_traverse` to have these specific names; don't name them just
`1574`	`1579`	`anything.`

Comments

(0)