This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author alanf
Recipients alanf, docs@python
Date 2015-06-18.14:33:15
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1434637996.53.0.698059319376.issue24466@psf.upfronthosting.co.za>
In-reply-to
Content
The description of pkgutil.extend_path in the doc (e.g., https://docs.python.org/2/library/pkgutil.html , https://docs.python.org/3/library/pkgutil.html ) is so ambiguous that I had to run a test to understand its behavior.

The doc says:

This will add to the package’s __path__ all subdirectories of directories on sys.path named after the package.

It wasn't clear to me how this should be parsed. Using parentheses to group the clauses, there's this possibility :

(1) This will add to the package’s __path__ all (subdirectories of directories on sys.path) named after the package.

That is, given all subdirectories of directories on sys.path, find the ones that are named after the package, and add them to the package's __path__.

or:

(2) This will add to the package’s __path__ all subdirectories of (directories on sys.path named after the package).

That is, given all directories on sys.path that are named after the package, add all their subdirectories to the package's __path__.

or: 

(3) This will add to the package’s __path__ all subdirectories of ((directories on sys.path) named after the package).

That is, given all directories on sys.path that are named after the package, add all their subdirectories to the package's __path__.

or:

(4) This will add to the package’s __path__ all (subdirectories of (directories on sys.path)) named after the package.

That is, given all directories on sys.path, add any of their subdirectories that are named after the package to the package's __path__.

It was also unclear to me whether the subdirectories were meant to be traversed recursively.

My testing indicates that (4) is the correct parse, and that the subdirectories are not meant to be traversed recursively.

I suggest this wording: For each directory on sys.path that has a subdirectory that matches the package name, add the subdirectory to the package's __path__.
History
Date User Action Args
2015-06-18 14:33:16alanfsetrecipients: + alanf, docs@python
2015-06-18 14:33:16alanfsetmessageid: <1434637996.53.0.698059319376.issue24466@psf.upfronthosting.co.za>
2015-06-18 14:33:16alanflinkissue24466 messages
2015-06-18 14:33:15alanfcreate