bpo-40838 document getdoc, getmodule, getsourcefile in inspect returns None
#30575
Conversation
…` returns `None`
sobolevn
added
needs backport to 3.9
Doc/library/inspect.rst
Outdated
| @@ -503,6 +503,7 @@ Retrieving source code | |||
| If the documentation string for an object is not provided and the object is | |||
| a class, a method, a property or a descriptor, retrieve the documentation | |||
| string from the inheritance hierarchy. | |||
| Might return ``None`` for invalid docstrings. | |||
There was a problem hiding this comment.
This method returns None if the object doesn't have a docstring. I don't think a docstring even could be invalid.
I'd actually prefer this method returning an empty string if the object doesn't have a docstring. Needing to use doc = getdoc(x) or '' everytime is annoying but I can understand changing this would be a backwards incompatible change.
There was a problem hiding this comment.
I've updated this to be: Might return None for missing or invalid docstrings
I mean this case by invalid:
if not isinstance(doc, str):
return None
There was a problem hiding this comment.
This piece of documentation very consistently uses the imperative mood ("return None" is an order directed to the function, telling the function what to do, while "might return None" is a description to the reader of what the function might do). I think it would be nice to maintain consistency with the rest of this piece of documentation 🙂
Additionally, the description for getdocstring doesn't use the word "docstring" at all currently, so it would be nice to stick to "documentation string" when describing that function 🙂
Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
|
|
||
|
|
||
| .. function:: getsourcefile(object) | ||
|
|
||
| Return the name of the Python source file in which an object was defined. This | ||
| Return the name of the Python source file in which an object was defined | ||
| or ``None`` if no way can be identified to get the source. This |
There was a problem hiding this comment.
| or ``None`` if no way can be identified to get the source. This | |
| or ``None`` if it cannot be identified. This |
There was a problem hiding this comment.
Thanks! But, I've copied this exact piece from inspect.py, I think it is better to keep it in sync (at least try to do that) 🙂
Co-authored-by: Jelle Zijlstra <[email protected]>
|
Thanks @sobolevn for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
|
GH-92909 is a backport of this pull request to the 3.11 branch. |
…t` returns `None` (pythonGH-30575) Co-authored-by: Alex Waygood <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit b86d783) Co-authored-by: Nikita Sobolev <[email protected]>
…t` returns `None` (pythonGH-30575) Co-authored-by: Alex Waygood <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit b86d783) Co-authored-by: Nikita Sobolev <[email protected]>
…t` returns `None` (GH-30575) Co-authored-by: Alex Waygood <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit b86d783) Co-authored-by: Nikita Sobolev <[email protected]>
|
GH-92910 is a backport of this pull request to the 3.10 branch. |
…t` returns `None` (GH-30575) Co-authored-by: Alex Waygood <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit b86d783) Co-authored-by: Nikita Sobolev <[email protected]>
CC @corona10 as my mentor.
I think that this can be backported to 3.9 and 3.10.
https://bugs.python.org/issue40838