Inaccurate docs on `import` behaviour

[samb]

BPO	33340
Nosy	@brettcannon, @ericvsmith, @tirkarthi

^{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 2018-04-23.09:51:36.081>
labels = ['type-feature', '3.8', 'docs']
title = 'Inaccurate docs on `import` behaviour'
updated_at = <Date 2019-05-06.14:12:08.875>
user = 'https://bugs.python.org/samb'

bugs.python.org fields:

activity = <Date 2019-05-06.14:12:08.875>
actor = 'cheryl.sabella'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-04-23.09:51:36.081>
creator = 'sam_b'
dependencies = []
files = []
hgrepos = []
issue_num = 33340
keywords = []
message_count = 4.0
messages = ['315653', '315655', '315657', '315658']
nosy_count = 5.0
nosy_names = ['brett.cannon', 'eric.smith', 'docs@python', 'sam_b', 'xtreak']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue33340'
versions = ['Python 3.8']

[samb]

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?

[ericvsmith]

"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')

[samb]

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.

[ericvsmith]

If you have a suggested improvement, please create a pull request. Thanks!