improvements when documenting __all__

[calestyo]

Documentation

1. Forgive me if I'm wrong (still being a Python noob ^^), but testing seems to show that the following is only half the truth:
   

   cpython/Doc/tutorial/modules.rst

   Lines 501 to 504 in da98ed0

   	package. The :keyword:`import` statement uses the following convention: if a package's
   	:file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
   	list of module names that should be imported when ``from package import *`` is
   	encountered. It is up to the package author to keep this list up-to-date when a

This says __all__ would be module names only (well it doesn't explicitly say so, but neither does it mention anything else), but in fact (or at least from some poor man testing I've did), it first seems to take any "items" (functions, vars, etc.) defined inside the package itself (i.e. within __init__.py and only if that doesn't exist (for a name listed in __all__), it seems to try importing a module/subpackage thereof.

Especially when considering:

cpython/Doc/tutorial/modules.rst

Lines 474 to 478 in da98ed0

	Note that when using ``from package import item``, the item can be either a
	submodule (or subpackage) of the package, or some other name defined in the
	package, like a function, class or variable. The ``import`` statement first
	tests whether the item is defined in the package; if not, it assumes it is a
	module and attempts to load it. If it fails to find it, an :exc:`ImportError`

mentioned just above, where it's explicitly told that with from bla import * takes first the in-package items and only then modules/subpackages... it may seem to the reader as if __all__ would be different, and really just take modules (as it says right now).

2. Another thing, which could perhaps be improved is the case, when importing from a package, which contains a module/subpackage of the same name:
   
   Consider e.g.:
   foo/__init__.py:

bar = 0
__all__ = ["foo"]

foo/foo.py:

bar = 1

and then using:

from foo import *

AFAIU, the "local" foo where foo.bar is 0 would be overwritten by foo.foo, thus foo.bar would be 1.

Now one might argue: package author's fault, if he writes stupid package/module names and __all__ but the above, I think, would even happen with e.g. __all__ = ["somethingElse"] when doing:

import foo.foo
from foo import *

as explained here:

cpython/Doc/tutorial/modules.rst

Lines 520 to 531 in da98ed0

	names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
	also includes any submodules of the package that were explicitly loaded by
	previous :keyword:`import` statements. Consider this code::
	import sound.effects.echo
	import sound.effects.surround
	from sound.effects import *
	In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
	current namespace because they are defined in the :mod:`sound.effects` package
	when the ``from...import`` statement is executed. (This also works when
	``__all__`` is defined.)

Thanks,
Chris.

[terryjreedy]

'module names' means names in the module, at the top level, as opposed to names in classes and functions in the module.
In 'from module import submod' will import 'submod' even though 'submod' is not already a module name (name in the module). Unless others think the existing doc unclear, this should be closed.

[calestyo]

I guess one can read it like that... but I'd expect most people will understand "module names" as "the names of modules" and not "names at the top-level within modules". I personally would even understand a phrase like "a module's names" (as if the module itself could have more than one name) like that.

IMO that's especially emphasised as the example given along:

cpython/Doc/tutorial/modules.rst

Line 510 in da98ed0

__all__ = ["echo", "surround", "reverse"]

uses only names that are names of modules.

[calestyo]

Just for the records... I found numerous stackoverflow Q&As, which seem to imply just the wrong understanding of __all__, i.e. that within __init__.py it would only refer to modules (not any names within __init__.py).

Take e.g. this one: https://stackoverflow.com/a/67143260 which even refers to the section of the tutorial I ways also referring to.

There was also another on which even had considerable upvotes... but I cannot find it anymore (had it on the smartphone and st**id Firefox there doesn't have a history).

[terryjreedy]

I agree now that the tutorial section is confusing.

[calestyo]

Maybe a way to improve it (i.e. explaining what happens when from foo import someName generally) is to rather follow the "The from form uses a slightly more complex process:" in:
https://docs.python.org/3/reference/simple_stmts.html#import

That is by itself a bit confusing (at least for noobs ^^), but I'd interpret is as follows:
1st load foo
2nd look for the name someName inside foo
3rd if not found, then "from within" foo, try to import someName
4th repeat 2nd and if still nothing, raise
5th otherwise use whatever was found (first a name defined inside foo, which could again be a module, then the "automatically" imported module

AFAICS, this generally applies, regardless of whether its a module or a package.

Not sure how to best write this in simple words... maybe that from first tries to import an item (module, package, class, func, etc.) actually defined (includes imported) inside foo, and only if that yielded nothing, there's an auto import.