numpy.lib.add_newdoc#

lib.add_newdoc(place, obj, doc, warn_on_python=True)[source]#

Add documentation to an existing object, typically one defined in C

The purpose is to allow easier editing of the docstrings without requiring a re-compile. This exists primarily for internal use within numpy itself.

Parameters:
placestr

The absolute name of the module to import from

objstr or None

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 a list, then each element of the list should be a tuple of length two - [(method1, docstring1), (method2, docstring2), ...]

warn_on_pythonbool

If True, the default, emit UserWarning if this is used to attach documentation to a pure-python object.

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.

This routine cannot modify read-only docstrings, as appear 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.

On this page