This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Document exceptions raised by importlib.import
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: FFY00, docs@python, iritkatriel, j13r, meowmeowmeowcat, ronaldoussoren
Priority: normal Keywords: easy, patch

Created on 2020-06-07 11:08 by j13r, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 27709 open meowmeowmeowcat, 2021-08-10 12:51
Messages (9)
msg370887 - (view) Author: Johannes Buchner (j13r) Date: 2020-06-07 11:08
https://docs.python.org/3/library/functions.html#__import__
and 
https://docs.python.org/3/library/importlib.html#importlib.import_module
do not list which Exceptions are raised in case the module cannot be imported.

The two exceptions are listed here
https://docs.python.org/3/library/exceptions.html#ImportError
ModuleNotFoundError

Could you add a half-sentence "and raises an ModuleNotFoundError if import was unsuccessful." to the function docs?
msg399205 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-08-07 22:48
ModuleNotFoundError is a subclass of ImportError, so it's probably enough to just document the functions as raising ImportError on failure, as in the case of https://docs.python.org/3/library/importlib.html#importlib.abc.Loader.load_module.
msg399319 - (view) Author: meowmeowcat (meowmeowmeowcat) * Date: 2021-08-10 12:52
Thanks! I've opened a PR for this issue.
msg399320 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2021-08-10 12:58
Note that importlib.import_module, and the import statement itself, can raise an arbitrary exception when that exception is raised while executing the module body.

This is easily observed by creating a module that just raises an error in its body:

# t.py
1/0
# EOF

``importlib.import_module("t")`` will raise ZeroDivisionError.
msg399328 - (view) Author: meowmeowcat (meowmeowmeowcat) * Date: 2021-08-10 14:28
Oh, I didn't realize that. Then maybe we don't need to document ImportError in https://docs.python.org/3/library/importlib.html#importlib.import_module?
msg399334 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2021-08-10 15:09
Good question. Hopefully one of the documentation or importlib experts can chime in about that.  I may also have uncovered a new issue in importlib ;-)

Personally I'd say that documenting raising ImportError is still useful because that's the common exception, and an exception that's not mentioned in the rest of the documentation for importlib.  That does require a careful formulation to avoid implying that this the only exception that can be raised.
msg399369 - (view) Author: meowmeowcat (meowmeowmeowcat) * Date: 2021-08-11 04:21
Maybe we can add something like:

```
If the module cannot be imported,:exc:`ImportError` is usually raised.

.. note::
   
   Sometimes other errors are raised if the module cannot be imported successfully. See https://docs.python.org/3/library/exceptions.html for more information.

```
msg399370 - (view) Author: meowmeowcat (meowmeowmeowcat) * Date: 2021-08-11 04:39
> ``importlib.import_module("t")`` will raise ZeroDivisionError.

I've tested ``__import__`` with the same code, and it will raise ZeroDivisionError too.
msg399592 - (view) Author: meowmeowcat (meowmeowmeowcat) * Date: 2021-08-14 14:40
So.. maybe changing ``the module cannot be imported`` to ``the module is not found``?
History
Date User Action Args
2022-04-11 14:59:32adminsetgithub: 85076
2021-10-23 17:05:11FFY00setnosy: + FFY00
2021-08-14 14:40:38meowmeowmeowcatsetmessages: + msg399592
2021-08-14 06:09:37meowmeowmeowcatsettype: enhancement
2021-08-11 04:39:12meowmeowmeowcatsetmessages: + msg399370
2021-08-11 04:21:12meowmeowmeowcatsetmessages: + msg399369
2021-08-10 15:09:12ronaldoussorensetmessages: + msg399334
2021-08-10 14:28:29meowmeowmeowcatsetmessages: + msg399328
2021-08-10 12:58:43ronaldoussorensetnosy: + ronaldoussoren
messages: + msg399320
2021-08-10 12:52:40meowmeowmeowcatsetmessages: + msg399319
2021-08-10 12:51:26meowmeowmeowcatsetkeywords: + patch
nosy: + meowmeowmeowcat

pull_requests: + pull_request26194
stage: patch review
2021-08-07 22:48:42iritkatrielsetversions: + Python 3.11, - Python 3.5, Python 3.6, Python 3.7, Python 3.8
nosy: + iritkatriel

messages: + msg399205

keywords: + easy
2020-06-07 11:12:25serhiy.storchakasettitle: Ddcument exceptions raised by importlib.import -> Document exceptions raised by importlib.import
2020-06-07 11:08:14j13rcreate