classification
Title: [doc] language reference describes the role of module.__file__ inaccurately
Type: Stage: needs patch
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, brett.cannon, docs@python, eric.snow, iritkatriel, ncoghlan
Priority: normal Keywords: easy

Created on 2014-06-14 20:33 by eric.snow, last changed 2021-12-07 00:49 by eric.snow.

Messages (4)
msg220578 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2014-06-14 20:33
The language reference [1] says:

  Ultimately, the loader is what makes use of __file__ and/or __cached__

This implies that loaders should use __file__ and __cached__ when loading a module.  Instead loaders are meant to implement exec_module() and use the spec that's passed in.

The entire section should have a clear note that loaders are not meant to rely a module's import-related attributes.

[1] https://docs.python.org/3/reference/import.html#__file__
[2] https://docs.python.org/3/reference/import.html#import-related-module-attributes
msg407721 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-12-05 17:43
Would it suffice to change

"Ultimately, the loader is what makes use of __file__ and/or __cached__"

to 

"Ultimately, the loader set the values of __file__ and/or __cached__"

?
msg407866 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2021-12-06 21:37
> "Ultimately, the loader set the values of __file__ and/or __cached__"

Change it to "sets" and +1 from me!
msg407885 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2021-12-07 00:49
The key point is that loaders should be using the spec, not any of the module attrs (like `__file__` and `__cached__`), nor setting them.

For the specific paragraph I referenced, it would look more like:

  It is also appropriate to set __cached__ when __file__ is not set.
  However, that scenario is quite atypical.  Ultimately, __file__ and
  __cached__ are set by the import system from the module spec provided
  by the finder.  The spec instructs the loader.  If a loader can load
  from a cached module but otherwise does not load from a file, that
  atypical scenario may be appropriate.
History
Date User Action Args
2021-12-07 00:49:59eric.snowsetmessages: + msg407885
2021-12-06 22:01:31iritkatrielsetkeywords: + easy
2021-12-06 21:37:42brett.cannonsetmessages: + msg407866
2021-12-05 17:43:07iritkatrielsetnosy: + iritkatriel
title: language reference describes the role of module.__file__ inaccurately -> [doc] language reference describes the role of module.__file__ inaccurately
messages: + msg407721

versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.4, Python 3.5
2014-06-14 20:35:11eric.snowsetassignee: docs@python

nosy: + docs@python
components: + Documentation
stage: needs patch
2014-06-14 20:33:24eric.snowcreate