classification
Title: __import__ docstring should recommend importlib.import_module()
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: belopolsky, brett.cannon, docs@python, eric.araujo, python-dev
Priority: normal Keywords: patch

Created on 2010-07-13 21:49 by belopolsky, last changed 2012-07-18 23:44 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
__import__-mention-importlib.diff eric.araujo, 2011-07-12 13:35 review
__import__-mention-importlib-2.7.diff eric.araujo, 2011-07-29 15:55
Messages (7)
msg110234 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-13 21:49
On Tue, Jul 13, 2010 at 4:52 PM, Brett Cannon wrote [1]:
..
> I say this every time I give an import talk and it has been brought up here
> before but obviously not everyone catches it (which is understandable as I
> think when it came up on python-dev it was at the tail end of a discussion),
> so I am just going to repeat myself:
>   Do not put junk in fromlist if you call __import__ directly! Use
> importlib.import_module! Or if you have a *really* good reason to not use
> it, then use ``__import__(name); module = sys.modules[name]``.

I think one of the reasons the message does not sink in (at least this is the reason in my case) is that a user who discovers that __import__('foo.bar') returns foo instead of bar, looks up help(__import__) to find that

"""
When importing a module from a package, note that __import__('A.B', ...) returns package A when fromlist is empty, but its submodule B when fromlist is not empty.
"""

Passing fromlist=["dummy"] seems like a natural solution after reading this.

The ReST documentation [2] is slightly better as it contain a recommendation that says: "If you simply want to import a module (potentially within a package) by name, you can call __import__() and then look it up in sys.modules." However this still fails to mention the (better IMO) alternative of using importlib.import_module().

I believe the __import__ docstring should start with a recommendation not to use it directly and use importlib.import_module() instead, while the ReST documentation should grow a warning not to use dummy fromlist and the recommendation to use __import__() followed by sys.modules lookup should be changed to a recommendation to use mportlib.import_module().

[1] "Peculiar import code in pickle.py" <http://mail.python.org/pipermail/python-dev/2010-July/101906.html>.
[2] http://docs.python.org/dev/library/functions.html?#__import__
msg110241 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-07-13 23:24
More rationale for not using a dummy fromlist, from Brett Cannon:

“Pulling from sys.modules is the correct way to do this. There are subtle
issues when using a bunk fromlist argument (empty modules, double
initialization, etc.). If one does not use importlib.import_module --
written *specifically* to prevent people from doing the nasty hack with the fromlist -- then you should use the sys.modules approach, period”
msg140183 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-12 13:35
The docstring of __import__ was updated to mention importlib in 3d490c3a019e, for #7397.  Attached patch edits the docs.
msg140207 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2011-07-12 19:20
Patch looks good to me.
msg141391 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-29 15:54
Patch committed in 3.2.

Attached patch ports the docstring change to 2.7 and edits the reST docs, please approve.
msg141392 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-29 16:11
New changeset 7bfc0a45542c by Éric Araujo in branch '3.2':
Let the doc of __import__ link to importlib (#9254).
http://hg.python.org/cpython/rev/7bfc0a45542c

New changeset 4a6cb2d9e906 by Éric Araujo in branch 'default':
Merge from 3.2 (#9254, #8982, #9788)
http://hg.python.org/cpython/rev/4a6cb2d9e906
msg165820 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-07-18 23:44
New changeset 751f28564a45 by R David Murray in branch '2.7':
Closes #9254: backport __import__ docstring/doc mentions of importlib.
http://hg.python.org/cpython/rev/751f28564a45
History
Date User Action Args
2012-07-18 23:44:27python-devsetstatus: open -> closed
resolution: fixed
messages: + msg165820

stage: commit review -> resolved
2011-07-29 16:11:13python-devsetnosy: + python-dev
messages: + msg141392
2011-07-29 15:55:43eric.araujosetfiles: + __import__-mention-importlib-2.7.diff
2011-07-29 15:54:44eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg141391
2011-07-12 19:20:44brett.cannonsetmessages: + msg140207
stage: needs patch -> commit review
2011-07-12 13:35:29eric.araujosetfiles: + __import__-mention-importlib.diff
keywords: + patch
messages: + msg140183

versions: - Python 3.1
2011-03-09 02:57:09terry.reedysetnosy: brett.cannon, belopolsky, eric.araujo, docs@python
versions: + Python 3.3
2010-08-24 23:27:09eric.araujosetversions: + Python 3.1, Python 2.7, Python 3.2
2010-07-13 23:24:15eric.araujosetnosy: + eric.araujo
messages: + msg110241
2010-07-13 21:49:59belopolskysetnosy: + docs@python
assignee: docs@python
components: + Documentation
type: enhancement
stage: needs patch
2010-07-13 21:49:27belopolskycreate