[docs] [issue22571] Remove import * recommendations and examples in doc?

[Terry J. Reedy]

New submission from Terry J. Reedy:

PEP 8 recommends against 'from mod import *' because it makes reading harder and is bad for code analysis.  My experience with retrofitting tests to idlelib modules with tkinter * imports is that it also makes testing harder since the testing strategy depends on the specific tkinter objects actually used.  So either an explicit list ('from tkinter import x, y, z') or a searchable prefix ('tk.') makes testing easier.  

Some time ago, 'from tkinter import *' was changed to 'import tkinter as tk' in the tkinter doc examples, though *not* the text.  ##10031 changed the import section of the FAQ to "remove the advice to use "from ... import *" with some modules" (from the commit message).  Should we finish the job?  Or leave the issue to individual chapter authors?

Here is the edited result of grepping 'import *' in ...\py34\Doc\*.rst with Idle.

F:\Python\dev\4\py34\Doc\distutils\apiref.rst: 1289: This module is safe to use in ``from ... import *`` mode; it only exports
F:\Python\dev\4\py34\Doc\library\cmd.rst: 234:     from turtle import *
F:\Python\dev\4\py34\Doc\library\collections.abc.rst: 14:    from collections import *
F:\Python\dev\4\py34\Doc\library\collections.rst: 11:     from collections import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 54:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 86:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 320:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 562:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 671:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 695:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 714:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 914:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 1074:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\ctypes.rst: 1122:    >>> from ctypes import *
F:\Python\dev\4\py34\Doc\library\decimal.rst: 20:    from decimal import *
F:\Python\dev\4\py34\Doc\library\decimal.rst: 56:      >>> from decimal import *
F:\Python\dev\4\py34\Doc\library\decimal.rst: 125:    >>> from decimal import *
F:\Python\dev\4\py34\Doc\library\difflib.rst: 13:    from difflib import *
F:\Python\dev\4\py34\Doc\library\itertools.rst: 12:    from itertools import *
F:\Python\dev\4\py34\Doc\library\stat.rst: 104:    from stat import *
F:\Python\dev\4\py34\Doc\library\statistics.rst: 13:    from statistics import *
F:\Python\dev\4\py34\Doc\library\struct.rst: 313:    >>> from struct import *
F:\Python\dev\4\py34\Doc\library\tkinter.rst: 63:    from tkinter import *
F:\Python\dev\4\py34\Doc\library\tkinter.rst: 580:    from tkinter import *
F:\Python\dev\4\py34\Doc\library\tkinter.tix.rst: 60:       from tkinter.constants import *
F:\Python\dev\4\py34\Doc\library\tkinter.ttk.rst: 38:    from tkinter import *
F:\Python\dev\4\py34\Doc\library\tkinter.ttk.rst: 39:    from tkinter.ttk import *
F:\Python\dev\4\py34\Doc\library\turtle.rst: 11:    from turtle import *

F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 102:    >>> from fibo import *
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 461: Now what happens when the user writes ``from sound.effects import *``?  Ideally,
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 470: list of module names that should be imported when ``from package import *`` is
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 479: This would mean that ``from sound.effects import *`` would import the three
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 482: If ``__all__`` is not defined, the statement ``from sound.effects import *``
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 493:    from sound.effects import *
F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 501: patterns when you use ``import *``, it is still considered bad practise in
F:\Python\dev\4\py34\Doc\tutorial\stdlib2.rst: 372:    >>> from decimal import *

I removed the reference hits that simply explain.  I have not looked at whether the tutorial goes beyond explanation, but should this even be mentioned in so many places?

----------
assignee: docs at python
components: Documentation
messages: 228734
nosy: docs at python, georg.brandl, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Remove import * recommendations and examples in doc?
versions: Python 2.7, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22571>
_______________________________________