[issue12645] test.support. import_fresh_module - incorrect doc
New submission from Eli Bendersky <eliben@gmail.com>:
From Ezio Melotti's email to python-dev:
diff --git a/Doc/library/test.rst b/Doc/library/test.rst --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -447,7 +447,7 @@ Module and package deprecation messages are suppressed during this import if *deprecated* is ``True``. - This function will raise :exc:`unittest.SkipTest` is the named module + This function will raise :exc:`unittest.SkipTest` if the named module Actually I think this is no longer true. import_fresh_module raises an ImportError if *name* can't be imported, or returns None if the fresh module is not found. Its use case is to enable or block accelerations for modules that optionally provide one. All the modules that currently use import_fresh_module are (afaik) always available (json, warnings, heapq), so raising SkipTest when the module is missing is not useful now. It returns None in the case an acceleration is missing, so e.g. in "cjson = import_fresh_module('json', fresh=['_json'])" cjson will be None and it will be possible to do things like @skipUnless(cjson, 'requires _json'). Here raising an ImportError will defeat (part of) the purpose of the function, i.e. avoiding: try: import _json except ImportError: _json = None and raising a SkipTest when the accelerations are missing is not an option if there are other tests (e.g. the tests for the Python implementation). These changes come from http://hg.python.org/cpython/rev/c1a12a308c5b . Before the change import_fresh_module was still returning the module (e.g. json) even when the acceleration (fresh=['_json']) was missing, and the C tests were run twice using the same pure-python module used for the Py ones. The typo and the wrong doc is also on 2.7. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141255 nosy: docs@python, eli.bendersky, ezio.melotti priority: normal severity: normal status: open title: test.support. import_fresh_module - incorrect doc versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ncoghlan stage: -> needs patch type: -> enhancement versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Adam Collard added the comment: The typo is no longer present, but the docs were still wrong. ---------- nosy: +adam-collard Added file: http://bugs.python.org/file30803/issue-12645-test-docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment: I'm reading the existing `test.support.import_fresh_module` docstring, and have re-formatted it for PEP 257 compliance and for reading clarity. ---------- keywords: +patch nosy: +bignose Added file: http://bugs.python.org/file30857/issue12645.reformat_docstring.9d22bc60bd4f.... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment:
import_fresh_module raises an ImportError if *name* can't be imported, or returns None if the fresh module is not found.
The implementation doesn't seem to raise ImportError when a module import fails. Instead, from what I can tell, it captures any ImportError and returns None. So should the documentation (user docs and docstring) reflect this? Or have I mis-read the implementation? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: _save_and_remove module can also raise ImportError ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: A single patch for both the ReST doc and docstring would be helpful. Except formatting, their contents can be the same. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: Ben, would you like to provide an updated patch? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment: On 01-Aug-2013, Eli Bendersky wrote:
Ben, would you like to provide an updated patch?
Unfortunately, contributions are not accepted under the Apache Software Foundation License (as I had thought), but also require assigning extra privileges to the Python Software Foundation under a special agreement. I'm not able to do this in good conscience, so it seems the Python Software Foundation will reject my contribution. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Roundup Robot added the comment: New changeset edaf44136d32 by Eli Bendersky in branch '3.3': Issue #12645: Clarify and reformat the documentation of import_fresh_module http://hg.python.org/cpython/rev/edaf44136d32 New changeset d8000009ef0e by Eli Bendersky in branch 'default': Close #12645: Clarify and reformat the documentation of import_fresh_module http://hg.python.org/cpython/rev/d8000009ef0e ---------- nosy: +python-dev resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ncoghlan stage: -> needs patch type: -> enhancement versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Adam Collard added the comment: The typo is no longer present, but the docs were still wrong. ---------- nosy: +adam-collard Added file: http://bugs.python.org/file30803/issue-12645-test-docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment: I'm reading the existing `test.support.import_fresh_module` docstring, and have re-formatted it for PEP 257 compliance and for reading clarity. ---------- keywords: +patch nosy: +bignose Added file: http://bugs.python.org/file30857/issue12645.reformat_docstring.9d22bc60bd4f.... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment:
import_fresh_module raises an ImportError if *name* can't be imported, or returns None if the fresh module is not found.
The implementation doesn't seem to raise ImportError when a module import fails. Instead, from what I can tell, it captures any ImportError and returns None. So should the documentation (user docs and docstring) reflect this? Or have I mis-read the implementation? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: _save_and_remove module can also raise ImportError ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: A single patch for both the ReST doc and docstring would be helpful. Except formatting, their contents can be the same. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Eli Bendersky added the comment: Ben, would you like to provide an updated patch? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Ben Finney added the comment: On 01-Aug-2013, Eli Bendersky wrote:
Ben, would you like to provide an updated patch?
Unfortunately, contributions are not accepted under the Apache Software Foundation License (as I had thought), but also require assigning extra privileges to the Python Software Foundation under a special agreement. I'm not able to do this in good conscience, so it seems the Python Software Foundation will reject my contribution. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
Roundup Robot added the comment: New changeset edaf44136d32 by Eli Bendersky in branch '3.3': Issue #12645: Clarify and reformat the documentation of import_fresh_module http://hg.python.org/cpython/rev/edaf44136d32 New changeset d8000009ef0e by Eli Bendersky in branch 'default': Close #12645: Clarify and reformat the documentation of import_fresh_module http://hg.python.org/cpython/rev/d8000009ef0e ---------- nosy: +python-dev resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________
participants (5)
-
Adam Collard -
Ben Finney
-
Eli Bendersky
-
Ezio Melotti
-
Roundup Robot