[issue11553] Docs for: import, packages, site.py, .pth files

[Graham Wideman]

Graham Wideman <initcontact at grahamwideman.com> added the comment:

Hi Eric,  Thanks for starting to review this, and your responses are encouraging. Some comments inline below.

FWIW, along the way I accumulated my own notes on this topic, on some pages here:

grahamwideman.wikispaces.com
(Left navigation panel...)
Software development > Python > Organization for common modules

Might be of interest as feedback on the digging process I needed in order to get some clarity on these issues, and also shows my references.

>> 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.)

>> Current docs are unclear on points such as:
>> -- is __init__.py needed on subpackage directories?
>Yes, it always has.  I think there was some discussion about removing them in py3k, but this was rejected.
I came to same conclusion.. but have seen it described otherwise (in at least one book), so good to state this explicitly.

>> -- 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.
                                                                                               
>> Seriously misleading discussion of .pth files.  [snip]
>Agreed. 

Cool -- I think it's well worth fixing this area for sure!

>> In addsitepackages(), the library directory for Windows (the else clause)
>> is shown as lower-case 'lib' instead of 'Lib'.
>I don’t see any else clause in the 2.7 or 3.3 code.  Otherwise you’re right.

Sorry, the lowecase 'lib' issue is in 
  getsitepackages()... 
  if sys.platform in(...) ... 
  else:...
    sitepackages.append(os.path.join(prefix, "lib", "site-packages"))

>> 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.

>> '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\.

>> For Windows suggests 'prefix' (default: C:\Python) as an installation directory.
>> This is indeed one of the possible 'site-package' directories, but surely it is
>> deprecated in favor of C:\Python\Lib\site-packages, which this section does not mention.
>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"
    to install modules to the \Temp\Python directory on the current drive.
Does this really mean "install modules to \Temp\Python\Lib\site-packages"?
(And as a side point, surely installing under the Temp directory is a strange location to pick for an example?)

>That was my initial feeback; I think I’ve covered all of your points. 
Looking forward!

----------

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