extend_path explanation in documentation is ambiguous

[alanf]

BPO	24466

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2015-06-18.14:33:16.496>
labels = ['3.11', 'type-feature', '3.9', '3.10', 'docs']
title = 'extend_path explanation in documentation is ambiguous'
updated_at = <Date 2021-06-22.20:44:15.320>
user = 'https://bugs.python.org/alanf'

bugs.python.org fields:

activity = <Date 2021-06-22.20:44:15.320>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-06-18.14:33:16.496>
creator = 'alanf'
dependencies = []
files = []
hgrepos = []
issue_num = 24466
keywords = []
message_count = 1.0
messages = ['245468']
nosy_count = 2.0
nosy_names = ['docs@python', 'alanf']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue24466'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-68654: Clarify subdirectories used by pkgutil.extend_path #103701
• [3.11] gh-68654: Clarify subdirectories used by pkgutil.extend_path (GH-103701) #103702

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

[iritkatriel]

CC @birkenfeld