classification
Title: extend_path explanation in documentation is ambiguous
Type: enhancement Stage:
Components: Documentation Versions: Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: alanf, docs@python
Priority: normal Keywords:

Created on 2015-06-18 14:33 by alanf, last changed 2015-06-18 14:33 by alanf.

Messages (1)
msg245468 - (view) Author: alanf (alanf) Date: 2015-06-18 14:33
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:16alanfcreate