>>> Exactly what variants of arguments are possible, and what are their
>>> effects?
>> Does http://docs.python.org/dev/library/functions#__import__ help?
>> Does http://docs.python.org/dev/library/importlib ?
> Well somewhat overkill -- because the matter of interest was args for
> from... and import, while the docs you mention are for more
> complicated underlying functions. (Interesting nonetheless.)

importlib.import_module should not be overkill, as it was designed specifically to be more easy and correct to use than __import__.

>>> -- the __all__ variable: Does it act generally to limit visibility
>>> of a module or package's attributes, or does pertain only to the
>>> 'from...import *' statement?
>> Both. 
> I'm pretty sure that's not correct -- pretty sure that __all__ only
> specifies what's included in from...import *, and does not prevent
> access via from...import specific_attrib.  But I may have tested
> incorrectly.

Sorry, I should have clarified.  I meant that __all__ limits what “from x import *” can see (for somemodule.__all__), and what pydoc and other tools display (for someobject.__all__).  Direct reference “x._lalala” or explicit import “from x import explicit_name” don’t look at __all__.
                                                     
>>> In addsitepackages(), the library directory for Windows (the else
>>> clause) is shown as lower-case 'lib' instead of 'Lib'.

Please report that as a new bug.

>>> sys
>>> Could helpfully point to a discussion of the typical items to
>>> be found in sys.path under normal circumstances
>> Hm, this would be very platform-specific.  What use cases would that
>> help?
> It would demystify how python already knows how to find various
> things under vanilla circumstances.

I’m all for demystification, so OK.  We already have platform-specific examples in site and/or sysconfig docs, so once more wouldn’t harm.

>>> 'Installing Python Modules' document
>>> "Windows has no concept of a user’s home directory, " and so on.
>> The author probably meant that there was no $HOME environment
>> variable, ~ shortcut and all that.
> Fair enough, but in actuality there *is* a user-specific location (on
> Windows) examined by site.py, which is in %APPDATA%\Python\.

That does not map to the home concept at all.  Anyway, it does not really add value to say that one OS doesn’t have something that another OS has, let’s just say that X uses something and that Y uses soemthing else.

>> Don’t confuse the prefix and the install dir.  The directory for
>> Python modules is computed as prefix + Lib/site-packages.
> Currently, under "Alternate installation: Windows (the prefix
> scheme)", it says:
>    python setup.py install --prefix="\Temp\Python" [...]
> Does this really mean "install modules to \Temp\Python\Lib\site-packages"?

I don’t know, try it in a shell!

> (And as a side point, surely installing under the Temp directory is a
> strange location to pick for an example?)

Well, the docs gotta pick something.  A tempdir is not worse than something else to demonstrate how to use a tool.

We need to have one discussion thread for each issue, to make this huge doc bug manageable.  I will go over your first message again and open one report for each point, this week if I have time.