[docs] Python 3.5.2 tutorial, section 6.4.1

[Robert Donovan]

This really needs some work.  It's much lower quality than the rest of 
the tutorial so far.  Different author?
Details follow...



1. Quote  "If |__all__| is not defined, the statement |from 
sound.effects import *| does /not/ import all submodules from the 
package |sound.effects| into the current namespace; it only ensures that 
the package |sound.effects| has been imported (possibly running any 
initialization code in |__init__.py|) and then imports whatever names 
are defined in the package. This includes any names defined (and 
submodules explicitly loaded) by |__init__.py|. "

This needs to be reworded.  What does it mean to import a package if not 
to import its modules?   If you are telling us, then /tell us/:

;it only ensures that the package |sound.effects| has been imported, 
WHICH MEANS running any initialization code in |__init__.py| ...

/and/...

and then imports whatever names are defined in the package (DEFINED 
WHERE?  IN THE __init__.py FILE? IF SO HOW IS THIS DIFFERENT FROM JUST 
RUNNING THAT FILE?  CAN NAMES BE DEFINED ANYWHERE ELSE?   WHAT ABOUT THE 
MODULE NAMES?  ARE THEY DEFINED?  WHAT DO YOU MEAN BY DEFINED?  THEY ARE 
ON THE DISK, IS THAT DEFINED?  WHAT DO YOU MEAN BY "the package"?)  This 
includes any names defined (and submodules explicitly loaded) by 
|__init__.py|.  ("this includes" IMPLIES THERE ARE OTHERS.  LIKE WHAT?)


2. Quote " It also includes any submodules of the package that were 
explicitly loaded by previous |import| 
<https://docs.python.org/3/reference/simple_stmts.html#import> 
statements. Consider this code:

import  sound.effects.echo
import  sound.effects.surround
from  sound.effects  import  *

In this example, the |echo| and |surround| modules are imported in the 
current namespace because they are defined in the |sound.effects| 
package when the |from...import| statement is executed. (This also works 
when |__all__| is defined.)"

I can't figure out what this means at all.
They are "defined in the |sound.effects| package when the 
|from...import| statement is executed"?
Surely they are defined all the time, sitting there on disk.
Surely they were imported when we asked them to be with the initial 
import statements.
Why would we ask them to be imported again with the * form?

3. Quote "Although certain modules are designed to export only names 
that follow certain patterns when you use |import *|, it is still 
considered bad practise in production code."

What!?



4. Quote "Now what happens when the user writes |from sound.effects 
import *|? Ideally, one would hope that this somehow goes out to the 
filesystem, finds which submodules are present in the package, and 
imports them all. This could take a long time and importing sub-modules 
might have unwanted side-effects that should only happen when the 
sub-module is explicitly imported.

The only solution is...
"

This one is nit-picking, but a "However, this could take a long time..." 
would aid comprehension and make it a little less self-contradictory.



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20161030/316ca228/attachment-0001.html>