From 45c4a8dc09ecaff6352a2e17cb242f7ae5ca11a9 Mon Sep 17 00:00:00 2001 From: mattip Date: Tue, 9 Jul 2019 15:26:08 -0500 Subject: DOC: point out the shortcomings of add_newdocs --- numpy/core/function_base.py | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'numpy/core/function_base.py') diff --git a/numpy/core/function_base.py b/numpy/core/function_base.py index 661b744b1..a316e072f 100644 --- a/numpy/core/function_base.py +++ b/numpy/core/function_base.py @@ -467,6 +467,16 @@ def add_newdoc(place, obj, doc): in new-style classes or built-in functions. Because this routine never raises an error the caller must check manually that the docstrings were changed. + + Since this function grabs the ``char *`` from a c-level str object and puts + it into the ``tp_doc`` slot of the type of `obj`, it violates a number of + C-API best-practices, by: + + - modifying a `PyTypeObject` after calling `PyType_Ready` + - calling `Py_INCREF` on the str and losing the reference, so the str + will never be released + + If possible it should be avoided. """ new = getattr(__import__(place, globals(), {}, [obj]), obj) if isinstance(doc, str): -- cgit v1.2.1