New submission from alanf: 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__. ---------- assignee: docs@python components: Documentation messages: 245468 nosy: alanf, docs@python priority: normal severity: normal status: open title: extend_path explanation in documentation is ambiguous type: enhancement versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue24466> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
