classification
Title: Inaccurate docs on `import` behaviour
Type: enhancement Stage:
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, eric.smith, sam_b, xtreak
Priority: normal Keywords:

Created on 2018-04-23 09:51 by sam_b, last changed 2019-05-06 14:12 by cheryl.sabella.

Messages (4)
msg315653 - (view) Author: (sam_b) Date: 2018-04-23 09:51
The docs https://docs.python.org/3/tutorial/modules.html#the-module-search-path describe:

> When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations:

> -   The directory containing the input script (or the current directory when no file is specified).
> -   PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH).
> -   The installation-dependent default.


However, it seems like "the directory containing the input script" is checked *before* the standard library:

➜  tmp more logging.py
def foo():
    print('bar')
➜  tmp python
Python 2.7.15rc1 (default, Apr 15 2018, 21:51:34)
[GCC 7.3.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import logging
>>> logging.foo()
bar
>>> logging.WARNING
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'WARNING'
>>> 


Am I misunderstanding the docs?
msg315655 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-04-23 10:08
"built-in modules" has the specific meaning of modules that are compiled in to the python executable. It doesn't mean modules in the standard library.

See https://docs.python.org/3.6/library/sys.html#sys.builtin_module_names

Python 3.6.4 (default, Jan  7 2018, 15:53:53)
[GCC 6.4.0] on cygwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.builtin_module_names
('_ast', '_codecs', '_collections', '_functools', '_imp', '_io', '_locale', '_operator', '_signal', '_sre', '_stat', '_string', '_symtable', '_thread', '_tracemalloc', '_warnings', '_weakref', 'atexit', 'builtins', 'errno', 'faulthandler', 'gc', 'itertools', 'marshal', 'posix', 'pwd', 'sys', 'time', 'xxsubtype', 'zipimport')
msg315657 - (view) Author: (sam_b) Date: 2018-04-23 10:27
Thanks, I thought it might be something like that. Would it be worth clarifying the distinction in the docs? It was certainly surprising to me that `import time` and `import logging` behave differently.
msg315658 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-04-23 10:30
If you have a suggested improvement, please create a pull request. Thanks!
History
Date User Action Args
2019-05-06 14:12:08cheryl.sabellasetnosy: + brett.cannon

type: behavior -> enhancement
versions: + Python 3.8, - Python 3.6
2018-09-23 14:42:49xtreaksetnosy: + xtreak
2018-04-23 10:30:32eric.smithsetmessages: + msg315658
2018-04-23 10:27:58sam_bsetmessages: + msg315657
2018-04-23 10:08:13eric.smithsetnosy: + eric.smith
messages: + msg315655
2018-04-23 09:51:36sam_bcreate