GH-119668: expose importlib.machinery.NamespacePath #119669

FFY00 · 2024-05-28T16:12:43Z

Issue: Expose _NamespacePath #119668

Signed-off-by: Filipe Laíns <[email protected]>

Misc/NEWS.d/next/Library/2024-05-28-17-14-30.gh-issue-119668.RrIGpn.rst

Doc/library/importlib.rst

brettcannon

See the comments that @picnixz left.

bedevere-app · 2024-07-10T23:29:14Z

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

Co-authored-by: Bénédikt Tran <[email protected]>

picnixz · 2024-07-22T13:59:18Z

The docs failure is related to the fact that you did not yet merge main into your branch. Since I don't like updating branches of people, I'll let you do it yourself.

Lib/importlib/machinery.py

Signed-off-by: Filipe Laíns <[email protected]>

picnixz

Thanks for addressing the previous review but I think the docs should explain the public API more in details and possibly have an example. I'm reviewing on my phone so sorry for the typos (and the lack of explicit suggestions)

picnixz · 2024-11-17T14:29:38Z

Doc/library/importlib.rst

+
+   For top-level modules, the parent module's path is :data:`sys.path`.
+
+


Can we use .. versionadded:: next + what's new entry? While this only exposes a private class, I think users should be notified more than just with a blurb.

Maybe versionchanged? You can say something like, prior to 3.15, this class was exposed as the module private _NamespacePath class. With 3.15 and beyond, the class has been publicly exposed as NamespacePath.

The attribute is set on importlib._bootstrap_external, which is a private module, so I lean towards versionadded.

picnixz · 2024-11-17T14:31:22Z

Lib/importlib/_bootstrap_external.py

        self._path.append(item)


+_NamespacePath = NamespacePath  # for backwards compatibility


Should we make it a deprecated alias? (and emit a warning if we were to access the private name? that could help transition from the private to the public name).

Who's the backwards-compatibility for? People poking at private attributes in private modules?

I don't think it hurts, but I also don't think it's necessary.

Well... considering it has been designed to support backwards compatibility, I thought it was worth the deprecation warning so that we can eventually remove it. But that could make the code a bit more complex (as we would need some logic in the module's __getattr__), so I'm also fine with leaving it as is.

picnixz · 2024-11-17T14:38:11Z

Doc/library/importlib.rst

+
+   It uses the module *name* to find its parent module, and from there it looks
+   up the parent's :attr:`module.__path__`.  When this changes, the module's own
+   path is recomputed, using *path_finder*. The initial value is set to *path*.


Can we perhaps mention the type of the path finder? (namely using some class Sphinx directive).

Btw, when you say that the initial value is set to path it seems that you are talking about the initial value of the path finder.

In addition, maybe mention that invalidating the caches forces the path to be recomputed (it might not necessarily be the case that the module parent's path has changed).

Finally, could you document the public methods of this new class? For instance there is no insert() method nor remove() as for lists.

I think an example of how to use it could be useful though I don't know whether we want to burden the docs even more.

Can we perhaps mention the type of the path finder? (namely using some class Sphinx directive).

Btw, when you say that the initial value is set to path it seems that you are talking about the initial value of the path finder.

In addition, maybe mention that invalidating the caches forces the path to be recomputed (it might not necessarily be the case that the module parent's path has changed).

I've rewritten the docs to include this.

Finally, could you document the public methods of this new class? For instance there is no insert() method nor remove() as for lists.

Using NamespacePath's mutability at runtime is something that requires folks to be familiar with the source, so I don't think we really need to document that.

The main improvement I want to get from the PR is the ability to isinstance(path, NamespacePath) safely.

I think an example of how to use it could be useful though I don't know whether we want to burden the docs even more.

Similarly, I don't really think that is necessary given the advanced nature of the topic.

brettcannon

Really just a very minor doc change is needed to add a note as to when the class was publicly exposed.

brettcannon · 2025-09-05T22:31:27Z

Lib/importlib/_bootstrap_external.py

        self._path.append(item)


+_NamespacePath = NamespacePath  # for backwards compatibility


Who's the backwards-compatibility for? People poking at private attributes in private modules?

brettcannon · 2025-09-05T22:31:40Z

Doc/library/importlib.rst

+
+   For top-level modules, the parent module's path is :data:`sys.path`.
+
+


brettcannon · 2025-09-05T22:32:02Z

Lib/importlib/_bootstrap_external.py

        self._path.append(item)


+_NamespacePath = NamespacePath  # for backwards compatibility


I don't think it hurts, but I also don't think it's necessary.

Lib/importlib/_bootstrap_external.py

Co-authored-by: Brett Cannon <[email protected]>

Signed-off-by: Filipe Laíns <[email protected]>

warsaw

Approved, with some suggestions and comments. Thanks for finally fixing this wart!

Doc/library/importlib.rst

warsaw · 2025-10-10T00:06:23Z

Doc/library/importlib.rst

+   The *path* argument is the initial path value.
+
+   The *path_finder* argument is the callable used to recompute the path value.
+   It has the same signature as :meth:`MetaPathFinder.find_spec`.


It's a little hard to tell from context, but which "it" is "It" referring to? I'm not sure if this is part of the path_finder paragraph or a separate paragraph.

It refers to path_finder, I'll rewrite it as "The callable has the same signature as (...)"

warsaw · 2025-10-10T00:07:57Z

Doc/library/importlib.rst

+
+   For top-level modules, the parent module's path is :data:`sys.path`.
+
+


Maybe versionchanged? You can say something like, prior to 3.15, this class was exposed as the module private _NamespacePath class. With 3.15 and beyond, the class has been publicly exposed as NamespacePath.

Lib/importlib/_bootstrap_external.py

Misc/NEWS.d/next/Library/2024-05-28-17-14-30.gh-issue-119668.RrIGpn.rst

Doc/library/importlib.rst

Co-authored-by: Barry Warsaw <[email protected]>

Signed-off-by: Filipe Laíns <[email protected]>

pythonGH-119668: expose importlib.NamespacePath

3c5af73

Signed-off-by: Filipe Laíns <[email protected]>

FFY00 requested review from brettcannon, ericsnowcurrently, ncoghlan and warsaw as code owners May 28, 2024 16:12

bedevere-app bot added the awaiting core review label May 28, 2024

bedevere-app bot mentioned this pull request May 28, 2024

Expose _NamespacePath #119668

Open

FFY00 and others added 3 commits May 28, 2024 17:14

add news

668b8ff

Signed-off-by: Filipe Laíns <[email protected]>

add to docs

02ceeb5

Signed-off-by: Filipe Laíns <[email protected]>

Merge branch 'main' into expose-namsespacepath

67cfa22

picnixz reviewed Jul 6, 2024

View reviewed changes

brettcannon requested changes Jul 10, 2024

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting core review labels Jul 10, 2024

Apply suggestions from code review

29df08f

Co-authored-by: Bénédikt Tran <[email protected]>

warsaw reviewed Sep 27, 2024

View reviewed changes

Lib/importlib/machinery.py Show resolved Hide resolved

FFY00 changed the title ~~GH-119668: expose importlib.NamespacePath~~ GH-119668: expose importlib.machinery.NamespacePath Nov 17, 2024

FFY00 added 6 commits November 17, 2024 03:34

Merge branch 'main' into expose-namsespacepath

fb73b9f

Fix news (importlib.NamespacePath > importlib.machinery.NamespacePath)

0dd0520

Signed-off-by: Filipe Laíns <[email protected]>

Link to module.__path__ in NamespacePath docs

06b8906

Signed-off-by: Filipe Laíns <[email protected]>

Mention the path argument in the documentation

cd506a4

Signed-off-by: Filipe Laíns <[email protected]>

Simplify docs text

6f441c4

Signed-off-by: Filipe Laíns <[email protected]>

Highlight argument names in docs text

137652a

Signed-off-by: Filipe Laíns <[email protected]>

FFY00 requested a review from brettcannon November 17, 2024 04:01

picnixz reviewed Nov 17, 2024

View reviewed changes

Merge branch 'main' into expose-namsespacepath

ab0930f

brettcannon requested changes Sep 5, 2025

View reviewed changes

brettcannon self-assigned this Sep 5, 2025

FFY00 and others added 5 commits October 9, 2025 17:04

Merge branch 'main' into expose-namsespacepath

d779a7f

Update Lib/importlib/_bootstrap_external.py

be415ab

Co-authored-by: Brett Cannon <[email protected]>

Rewrite NamespacePath's doc

bb16ae1

Signed-off-by: Filipe Laíns <[email protected]>

Specify path_finder's type in the NamespacePath docstring

9f52661

Signed-off-by: Filipe Laíns <[email protected]>

Fix doc tests

0494d7b

Signed-off-by: Filipe Laíns <[email protected]>

FFY00 requested a review from brettcannon October 9, 2025 22:22

warsaw approved these changes Oct 10, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting changes labels Oct 10, 2025

FFY00 commented Oct 10, 2025

View reviewed changes

Doc/library/importlib.rst Outdated Show resolved Hide resolved

FFY00 and others added 2 commits October 10, 2025 06:39

Apply suggestions from code review

8ccb7ba

Co-authored-by: Barry Warsaw <[email protected]>

Fix doc lint

8bc2d6c

Signed-off-by: Filipe Laíns <[email protected]>


		For top-level modules, the parent module's path is :data:`sys.path`.

		self._path.append(item)


		_NamespacePath = NamespacePath # for backwards compatibility

Uh oh!

GH-119668: expose importlib.machinery.NamespacePath #119669

Are you sure you want to change the base?

GH-119668: expose importlib.machinery.NamespacePath #119669

Uh oh!

Conversation

FFY00 commented May 28, 2024 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brettcannon left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Jul 10, 2024

Uh oh!

picnixz commented Jul 22, 2024

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brettcannon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

warsaw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

FFY00 commented May 28, 2024 •

edited by bedevere-app bot

Loading