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 ---------- place : str The absolute n
(place, obj, doc, warn_on_python=True)
| 488 | |
| 489 | |
| 490 | def add_newdoc(place, obj, doc, warn_on_python=True): |
| 491 | """ |
| 492 | Add documentation to an existing object, typically one defined in C |
| 493 | |
| 494 | The purpose is to allow easier editing of the docstrings without requiring |
| 495 | a re-compile. This exists primarily for internal use within numpy itself. |
| 496 | |
| 497 | Parameters |
| 498 | ---------- |
| 499 | place : str |
| 500 | The absolute name of the module to import from |
| 501 | obj : str | None |
| 502 | The name of the object to add documentation to, typically a class or |
| 503 | function name. |
| 504 | doc : str | tuple[str, str] | list[tuple[str, str]] |
| 505 | If a string, the documentation to apply to `obj` |
| 506 | |
| 507 | If a tuple, then the first element is interpreted as an attribute |
| 508 | of `obj` and the second as the docstring to apply - |
| 509 | ``(method, docstring)`` |
| 510 | |
| 511 | If a list, then each element of the list should be a tuple of length |
| 512 | two - ``[(method1, docstring1), (method2, docstring2), ...]`` |
| 513 | warn_on_python : bool |
| 514 | If True, the default, emit `UserWarning` if this is used to attach |
| 515 | documentation to a pure-python object. |
| 516 | |
| 517 | Notes |
| 518 | ----- |
| 519 | This routine never raises an error if the docstring can't be written, but |
| 520 | will raise an error if the object being documented does not exist. |
| 521 | |
| 522 | This routine cannot modify read-only docstrings, as appear |
| 523 | in new-style classes or built-in functions. Because this |
| 524 | routine never raises an error the caller must check manually |
| 525 | that the docstrings were changed. |
| 526 | |
| 527 | Since this function grabs the ``char *`` from a c-level str object and puts |
| 528 | it into the ``tp_doc`` slot of the type of `obj`, it violates a number of |
| 529 | C-API best-practices, by: |
| 530 | |
| 531 | - modifying a `PyTypeObject` after calling `PyType_Ready` |
| 532 | - calling `Py_INCREF` on the str and losing the reference, so the str |
| 533 | will never be released |
| 534 | |
| 535 | If possible it should be avoided. |
| 536 | """ |
| 537 | new = getattr(__import__(place, globals(), {}, [obj]), obj) |
| 538 | if isinstance(doc, str): |
| 539 | if "${ARRAY_FUNCTION_LIKE}" in doc: |
| 540 | doc = overrides.get_array_function_like_doc(new, doc) |
| 541 | _add_docstring(new, doc, warn_on_python) |
| 542 | elif isinstance(doc, tuple): |
| 543 | attr, docstring = doc |
| 544 | _add_docstring(getattr(new, attr), docstring, warn_on_python) |
| 545 | elif isinstance(doc, list): |
| 546 | for attr, docstring in doc: |
| 547 | _add_docstring(getattr(new, attr), docstring, warn_on_python) |
searching dependent graphs…