classification
Title: PyImport_ImportModule inaccurately described
Type: Stage:
Components: Documentation Versions: Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, memeplex
Priority: normal Keywords: easy

Created on 2015-10-29 12:06 by memeplex, last changed 2020-09-11 22:16 by brett.cannon.

Messages (5)
msg253674 - (view) Author: Memeplex (memeplex) Date: 2015-10-29 12:06
The documentation (for 3.5) states that "[PyImport_ImportModule] is a simplified interface to PyImport_ImportModuleEx()" but the current implementation calls PyImport_Import instead, which is a higher level interface that takes into account import hooks. Older versions of PyImport_ImportModule (say 2.0) did call PyImport_ImportModuleEx, but that's no longer the case.

The PyImport_Import* naming convention got a bit messy with the years and maybe I'm not understanding the intention quite well, but it seems to me that the documentation is outdated and that there is a change in semantics for PyImport_ImportModule.
msg253687 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-10-29 17:51
Semantic change was probably because of the lack of import hook support which is required since Python 3.3. So the docs just need to be fixed rather than the semantics.
msg253818 - (view) Author: Memeplex (memeplex) Date: 2015-11-01 01:58
Brett, I'm not sure about that, notice that the "import hook" as is mentioned in the docs is just the current __import__ in the builtins module (which could have been replaced and in this sense would be a "hook") but not proper import hooks. I think the original distinction between PyImport_ImportModule and PyImport_Import is still sensible today. Originally PyImport_ImportModule directly called the import machinery, while PyImport_Import called it indirectly through builtins.__import__ (which could have been replaced). Now, for some reason, for good or for bad, PyImport_ImportModule also goes through builtins.__import__. The documentation is wrong but what is the fix? Revert PyImport_ImportModule or redocument it?
msg253821 - (view) Author: Memeplex (memeplex) Date: 2015-11-01 03:01
Well it's like that since 2.1 so I guess the doc is wrong indeee.
msg376743 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2020-09-11 22:16
https://github.com/python/cpython/blob/45b34a04a577aa49fa4825421758c3e8eaa1625d/Python/import.c#L1474-L1485 shows that the docs could be simplified to point out that `PyImport_ImportModule()` is a wrapper around `PyImport_Import()` which takes `const char *`.
History
Date User Action Args
2020-09-11 22:16:56brett.cannonsetkeywords: + easy
2020-09-11 22:16:35brett.cannonsetversions: + Python 3.10, - Python 3.5
2020-09-11 22:16:27brett.cannonsetmessages: + msg376743
2015-11-01 03:01:37memeplexsetmessages: + msg253821
2015-11-01 01:58:58memeplexsetmessages: + msg253818
2015-10-29 17:51:55brett.cannonsetmessages: + msg253687
2015-10-29 17:50:38brett.cannonsetnosy: + brett.cannon
2015-10-29 12:06:44memeplexcreate