Skip to content

gh-85076: Document exceptions that can be raised by importlib.import_module #94662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+4 −0
Open

gh-85076: Document exceptions that can be raised by importlib.import_module #94662

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
047548c
Document ImportError from importlib
kj7rrv Jul 7, 2022
19e53c4
Update Doc/library/importlib.rst
kj7rrv Jul 23, 2023
7623c39
Merge branch 'main' into importlib-doc-importerror
kj7rrv Jul 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions Doc/library/importlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,11 @@ Functions
need to call :func:`invalidate_caches` in order for the new module to be
noticed by the import system.

If the module cannot be imported, :func:`import_module` will raise an
:exc:`ImportError`. If the module is found and loaded, but the code in the
module raises an exception, :func:`import_module` will pass that exception
to the module that called it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the module cannot be imported, :func:`import_module` will raise an
:exc:`ImportError`. If the module is found and loaded, but the code in the
module raises an exception, :func:`import_module` will pass that exception
to the module that called it.
If the module cannot be found or loaded, :func:`import_module` will raise an
:exc:`ImportError`.

"cannot be imported" is very generic and could conceivably apply to explicitly raised exceptions, like in the second half of this paragraph, so makes sense to be more specific.

I think we could just omit the second half of the paragraph. Talking about "passing exceptions" makes it sound more complicated than it is. The behaviour here is intuitive and already documented by the sentence "This means all semantics of the function are derived from :func:importlib.__import__."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't "cannot be found or loaded" imply that that's the behavior if the module cannot be loaded because code in the module raised an exception? Maybe "If the module cannot be found or its files cannot be accessed..." instead? That makes it clear that ImportError is raised in cases like the module not being found or being inaccessible due to file permissions, not cases where it is found but not successfully loaded.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest to look further down, where I tried to consolidate things. (sorry for the spam, I hope it's helpful for readers 😅)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trying to incorporate everything discussed at the same time.

@brettcannon's suggestion:

  • is more specific on the type of exception that can be expected.
  • does not incorporate the remark from @hauntsaninja, that criticises the fact that "cannot be imported" is very generic.

In the first thread @kj7rrv suggested a nice way of explaining how a found module can't be imported. Not sure if it's now too specific, but let's continue the discussion:

Suggested change
If the module cannot be imported, :func:`import_module` will raise an
:exc:`ImportError`. If the module is found and loaded, but the code in the
module raises an exception, :func:`import_module` will pass that exception
to the module that called it.
If the module cannot be found or its files cannot be accessed,
:func:`import_module` will raise :exc:`ImportError` or an appropriate
subclass like :exc:`ModuleNotFoundError`.


.. versionchanged:: 3.3
Parent packages are automatically imported.

Expand Down