Meta issue for cleaning up import system cruft

[warsaw]

This is a meta issue tracking all the things that need to be cleaned up in the import system. From removing long deprecated APIs to migrating internal access to __spec__, we'll have several task lists for each related set of clean ups.

@brettcannon @ericsnowcurrently for visibility.

Removing deprecated APIs

Over in What's New for Python 3.11 there's a long list of things that have been deprecated long enough that they can be removed in Python 3.12. Here's that task list for tracking purposes. Watch for linked PRs (maybe one big one or many small ones -- we'll see!).

@brettcannon @ericsnowcurrently for visibility.

• importlib.find_loader()
• importlib.util.module_for_loader()
• importlib.util.set_loader_wrapper()
• importlib.util.set_package_wrapper()
• importlib.abc.Loader.module_repr() (3.12: gh-97850: Remove all known instances of module_repr() #97876)
• importlib.abc.MetaPathFinder.find_module()
• importlib.abc.MetaPathFinder.find_module()
• importlib.abc.PathEntryFinder.find_loader()
• importlib.abc.PathEntryFinder.find_module()
• importlib.machinery.BuiltinImporter.find_module()
• importlib.machinery.BuiltinLoader.module_repr() (3.12: gh-97850: Remove all known instances of module_repr() #97876)
• importlib.machinery.FileFinder.find_loader()
• importlib.machinery.FileFinder.find_module()
• importlib.machinery.FrozenImporter.find_module()
• importlib.machinery.FrozenLoader.module_repr() (3.12: gh-97850: Remove all known instances of module_repr() #97876)
• importlib.machinery.PathFinder.find_module()
• importlib.machinery.WindowsRegistryFinder.find_module()
• Remove pkgutil.ImpImporter (3.12: already deprecated)
• Remove pkgutil.ImpLoader
• Remove the imp module (3.12: Remove more deprecated importlib APIs from Python 3.12 #98040)
• importlib.abc.Finder

Update docs

• Make sure examples and details from PEP 302 are covered in the importlib docs (/cc @Yhg1s )
• Remove https://docs.python.org/3/reference/import.html#open-issues (PR)
• It would be really nice to have a diagram.
• (import_machinery.rst) how about a section devoted just to the attributes of modules and packages, perhaps expanding upon or supplanting the related entries in the data model reference page?
• runpy, pkgutil, et al in the library manual should all get “See Also” links at the top pointing to the new import system section.
• Add more explanation regarding the different ways in which __main__ is initialized?
• Add more info on __main__ quirks/pitfalls (i.e. copy from PEP 395).

Missing deprecations

Here's a list of related APIs that have not yet been deprecated, but should be. We'll deprecate them in 3.12 and remove them in 3.14.

• pkgutil.find_loader()
• pkgutil.get_loader() (or it needs to be reimplemented to not use find_loader())

Other:

• Do we need to define importlib.abc.PathEntryFinder.find_spec() #103999

• PR: gh-97850: Deprecate find_loader and get_loader in pkgutil #98520

• PR: GH-97850: Suppress cross-references to the removed module_repr method #104133

• PR: GH-97850: Suppress cross-references to removed importlib.util functions #104134

• PR: gh-97850: Note in py312 whatsnew that importlib.util.set_loader and importlib.util.module_for_loader have been removed #108719

• PR: [3.12] gh-97850: Note in py312 whatsnew that importlib.util.set_loader and importlib.util.module_for_loader have been removed (GH-108719) #108723

• PR: gh-97850: remove find_loader and get_loader from pkgutil #119656

• PR: gh-97850: Suggest TraversableResources as the alternative for ResourceLoader. #128601

• PR: gh-97850: Remove the mention of removal from ResourceReader docs #128602

• PR: [3.13] gh-97850: Remove the mention of removal from ResourceReader docs (GH-128602) #128654

• PR: [3.12] gh-97850: Remove the mention of removal from ResourceReader docs (GH-128602) #128655

• PR: [3.13] gh-97850: Suggest TraversableResources as the alternative for ResourceLoader (GH-128601) #128895

• PR: [3.12] gh-97850: Suggest TraversableResources as the alternative for ResourceLoader (GH-128601) #128896

• PR: gh-97850: Update the deprecation warning of importlib.abc.Loader.load_module #129855

• PR: [3.13] gh-97850: Update the deprecation warning of importlib.abc.Loader.load_module (GH-129855) #130013

• PR: [3.12] gh-97850: Update the deprecation warning of importlib.abc.Loader.load_module (GH-129855) #130017

[sobolevn]

I've removed importlib.utils.set_loader, importlib.utils.set_package, and
importlib.utils.module_for_loader from importlib.utils in #97898 🎉

[tomasr8]

Ok I can remove the scheduled removal from the docs of ResourceReader 👍

@encukou since you mentioned not bothering people with warnings, what's your opinion on this issue (and the linked PR): #121604 Should all the mentioned items also raise deprecation warnings?

[jaraco]

@jaraco If I understand correctly, you lean more towards keeping ResourceReader deprecated? If that is the case, should we add a DeprecationWarning as well? Currently, the deprecation is only mentioned in the docs. As Brett says, we can also extend the deprecation timeline in the docs to 3.14 + 5.

I do, but I'm not confident there's a clear path to deprecate, because although the interface is deprecated, it's an interface that's used both by providers and consumers of that interface. Even its replacement subclasses that interface, so it's not even obvious to me that a deprecation warning is possible. Sounds like it's best to just leave it documented. Thanks.

[encukou]

what's your opinion on this issue (and the linked PR): #121604

My first impression: The deprecation code seems like a bigger maintenance burden than the deprecated API itself; better to just leave it alone. Let's deprecate things that are dangerous or misleading, not just old and limited.
But, I don't think my personal opinion should carry much weight here.

[warsaw]

Let's deprecate things that are dangerous or misleading
... or unmaintainable.

If it doesn't match any of those criteria then agreed there's no urgency to remove them and break code.

[tomasr8]

Thanks everyone for your comments! :)

I created #128601 and #128602 to update the deprecations in the docs.