From 54f9fc5c60976abb34e3dae6a9eae902fcf61dfc Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Mon, 8 Jul 2019 23:30:31 -0700 Subject: DOC: Add a numpy-doc docstring to add_newdoc --- numpy/core/function_base.py | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) (limited to 'numpy/core/function_base.py') diff --git a/numpy/core/function_base.py b/numpy/core/function_base.py index a7700bb73..aee78d734 100644 --- a/numpy/core/function_base.py +++ b/numpy/core/function_base.py @@ -437,18 +437,29 @@ def _add_docstring(obj, doc): def add_newdoc(place, obj, doc): """ - Adds documentation to obj which is in module place. + Add documentation to an existing object, typically one defined in C - If doc is a string add it to obj as a docstring + The purpose is to allow easier editing of the docstrings without requiring + a re-compile. This exists primarily for internal use within numpy itself. - If doc is a tuple, then the first element is interpreted as - an attribute of obj and the second as the docstring - (method, docstring) + Parameters + ---------- + place : str + The absolute name of the module to import from + obj : str + The name of the object to add documentation to, typically a class or + function name + doc : {str, Tuple[str, str], List[Tuple[str, str]]} + If a string, the documentation to apply to `obj` + + If a tuple, then the first element is interpreted as an attribute of + `obj` and the second as the docstring to apply - ``(method, docstring)`` - If doc is a list, then each element of the list should be a - sequence of length two --> [(method1, docstring1), - (method2, docstring2), ...] + If a list, then each element of the list should be a tuple of length + two - ``[(method1, docstring1), (method2, docstring2), ...]`` + Notes + ----- This routine never raises an error if the docstring can't be written, but will raise an error if the object being documented does not exist. -- cgit v1.2.1 From f730ea85c441e2af73a3f1d19f86412240bc106d Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Mon, 8 Jul 2019 23:31:26 -0700 Subject: MAINT: Enforce that `add_newdocs` is called with sequences of the right size Previously this would silently ignore extra items --- numpy/core/function_base.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'numpy/core/function_base.py') diff --git a/numpy/core/function_base.py b/numpy/core/function_base.py index aee78d734..661b744b1 100644 --- a/numpy/core/function_base.py +++ b/numpy/core/function_base.py @@ -472,7 +472,8 @@ def add_newdoc(place, obj, doc): if isinstance(doc, str): _add_docstring(new, doc.strip()) elif isinstance(doc, tuple): - _add_docstring(getattr(new, doc[0]), doc[1].strip()) + attr, docstring = doc + _add_docstring(getattr(new, attr), docstring.strip()) elif isinstance(doc, list): - for val in doc: - _add_docstring(getattr(new, val[0]), val[1].strip()) + for attr, docstring in doc: + _add_docstring(getattr(new, attr), docstring.strip()) -- cgit v1.2.1 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