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

[Graham Wideman]

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

Hi Nick: Thanks for your additional points. Comments inline:

> __all__ only affects import *, and may also affect documentation tools (e.g. pydoc will respect __all__ when deciding what to display). It has no effect on attribute retrieval from modules.

That's indeed my understanding. So the doc (6. Simple statements) which says that __all__ determines the list of "public names" is a bit of a red herring.  Attributes are accessible (ie: public) regardless of whether on the __all__ list.  Instead the __all__ list establishes the list of names imported by *, and makes those names reference-able without a module prefix. (Plus gives hints about intent to doc tools.)

> pkgutil.extend_path() is used to modify pkg.__path__ attributes, *not* sys.path. 

Understood, and perhaps my point was obtuse.  I was pointing out that the doc for extend_path discusses .pkg entries which point to package dirs, and that this, it says, is like .pth files. I claim that an entry in a .pth files should NOT point to a package dir, but rather to one level up: to a dir that *contains* package dirs. (Pointing a .pth entry directly at a package dir will break package behavior by exposing the constituent modules to sys.path.)  Hence the doc for extend_path is misleadingly suggesting a wrong idea about .pth files.

----------

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