inspect.getsourcefile documentation doesn't mention it can return None

[pekkaklarck]

BPO	40838
Nosy	@DimitrisJim, @sobolevn
PRs	bpo-40838 document getdoc, getmodule, getsourcefile in inspect returns None #30575

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-06-01.11:41:44.257>
labels = ['type-bug', 'docs']
title = "inspect.getsourcefile documentation doesn't mention it can return None"
updated_at = <Date 2022-01-13.13:05:58.746>
user = 'https://bugs.python.org/pekkaklarck'

bugs.python.org fields:

activity = <Date 2022-01-13.13:05:58.746>
actor = 'sobolevn'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-06-01.11:41:44.257>
creator = 'pekka.klarck'
dependencies = []
files = []
hgrepos = []
issue_num = 40838
keywords = ['patch']
message_count = 2.0
messages = ['370547', '370548']
nosy_count = 4.0
nosy_names = ['docs@python', 'pekka.klarck', 'Jim Fasarakis-Hilliard', 'sobolevn']
pr_nums = ['30575']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue40838'
versions = []

[pekkaklarck]

The docs of inspect.getsourcefile [1] mention the function can raise TypeError, but there's nothing about the function possibly returning None. This caused a bug in our project [2].

If I understand the code [3] correctly, None is returned if getsourcefile cannot determine the original source file of the file returned by getfile. That's understandable but should definitely be documented. Raising TypeError that getfile itself may raise might be even better, but such a backwards incompatible API change is probably not worth the effort.

While looking at the code, I also noticed there's getabsfile [4] that uses getfile if getsourcefile returns None. That looks handy but since the function isn't included in the inspect module documentation [5] using it feels pretty risky.

[1] https://docs.python.org/3/library/inspect.html#inspect.getsourcefile
[2] robotframework/robotframework#3587
[3] https://github.com/python/cpython/blob/3.8/Lib/inspect.py#L692
[4] https://github.com/python/cpython/blob/3.8/Lib/inspect.py#L714
[5] https://bugs.python.org/issue12317

[DimitrisJim]

For a more comprehensive list, we currently have for get* functions in inspect:

inspect.getdoc: Returns None if the documentation string isn't present, either directly on the object or through it mro. This isn't documented.

inspect.getfile: Explicitly seems to handle None cases. After peeking a bit in the PyCode_* interface, it doesn't seem to be possible to assign None to the co_filename so the returning the object.co_filename in the function appears to not be able to return None.

inspect.getmodule: Returns None in a number of cases. This isn't documented.

inspect.getsourcefile: Returns None if the filename indicates an extension module or when none of the ifs are matched. This isn't documented.

Some (getmodulename, getcomments) do document this. Agreed that the rest of the cases where Nones might be returned should be documented.