Improve/clarify importlib recipe for loading code from a source file path

[brettcannon]

          > https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly 

Ahh -- thanks -- I hadn't found that.

That looks to me like it's the non-deprecated way to do:

module = SourceFileLoader(name, path).load_module()

Is that correct -- will it do the same thing?

In which case, I propose that that recipe be added to importlib as a utility function along the lines of:

def load_module_from_path(name, path):
    """
    load a module from a file on disk

    :param name: name of the module
    :type name: str

    :param path: path to the file
    :type path: PathLike

    :returns: instantiated module object

    Note: The module is also added to sys.modules, and will behave the same as though
              the file were on sys.path and imported the usual way.
    """
    import os  # import here, so that it only gets imported if needed.
    path = os.fspath(path)

    spec = importlib.util.spec_from_file_location(name, path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)

    return module

I understand that it was a deliberate decision to put the recipe in the docs, rather than a utility function, though unless it's really something that is "not recommended" (in which case perhaps it should say so in the docs) -- then this is just complex enough that a utility function is called for -- particularly since SourceFileLoader(name, path).load_module() (now deprecated?) is advice readily found on the internet.

Does this need another issue or PR?

Meanwhile, for the original issue:

I suggest that checking for __fspath__ be added to the: FileLoader.__init__() and perhaps a couple other places where file paths are initialized -- that is the "outer" parts of the importlib API.

Though for my use-case the proposed utility function would solve the problem at hand.

Originally posted by @ChrisBarker-NOAA in #87005 (comment)

Linked PRs

• gh-121607: Edited source file import recipe to make it more clear #121519
• [3.13] gh-121607: Edited source file import recipe to make it more clear (GH-121519) #124080
• [3.12] gh-121607: Edited source file import recipe to make it more clear (GH-121519) #124081

[ZeroIntensity]

If we go the route of adding a new function to importlib.util, it might be worthwhile to assume the module name based on the path.

Any time I've seen someone use this snippet (or something similar) for source file importing, they've always used the trailing file name, minus the .py suffix, as the module name. Would eliminate some of the redundancy to do this automatically. IIRC, I've done this in the past with pathlib: module_name = Path("/path/to/module.py").stem

[brettcannon]

If we go the route of adding a new function to importlib.util

We're not for various reasons. If people want a function I think it should come from PyPI.

[brettcannon]

All backports are merged, so I'm closing this. Thanks, everyone!