Title: import_fresh_module - incorrect doc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: adam-collard, bignose, docs@python, eli.bendersky, ezio.melotti, ncoghlan, python-dev
Priority: normal Keywords: easy, patch

Created on 2011-07-27 18:03 by eli.bendersky, last changed 2013-08-11 22:44 by python-dev. This issue is now closed.

File name Uploaded Description Edit
issue-12645-test-docs adam-collard, 2013-07-06 11:49 patch for test docs. review
issue12645.reformat_docstring.9d22bc60bd4f.patch bignose, 2013-07-08 06:39 Patch to re-format docstring for clarity and PEP 257 review
Messages (9)
msg141255 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-27 18:03
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:
 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 .  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.
msg192418 - (view) Author: Adam Collard (adam-collard) * Date: 2013-07-06 11:49
The typo is no longer present, but the docs were still wrong.
msg192620 - (view) Author: Ben Finney (bignose) Date: 2013-07-08 06:39
I'm reading the existing `` docstring, and have re-formatted it for PEP 257 compliance and for reading clarity.
msg192621 - (view) Author: Ben Finney (bignose) Date: 2013-07-08 06:42
> 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?
msg192748 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-07-09 13:21
_save_and_remove module can also raise ImportError
msg192749 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-07-09 13:24
A single patch for both the ReST doc and docstring would be helpful. Except formatting, their contents can be the same.
msg194058 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-08-01 12:42
Ben, would you like to provide an updated patch?
msg194435 - (view) Author: Ben Finney (bignose) Date: 2013-08-04 23:01
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.
msg194914 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-08-11 22:44
New changeset edaf44136d32 by Eli Bendersky in branch '3.3':
Issue #12645: Clarify and reformat the documentation of import_fresh_module

New changeset d8000009ef0e by Eli Bendersky in branch 'default':
Close #12645: Clarify and reformat the documentation of import_fresh_module
Date User Action Args
2013-08-11 22:44:11python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg194914

resolution: fixed
stage: needs patch -> resolved
2013-08-04 23:01:47bignosesetmessages: + msg194435
2013-08-01 12:42:34eli.benderskysetmessages: + msg194058
2013-07-09 13:24:23eli.benderskysetmessages: + msg192749
2013-07-09 13:21:46eli.benderskysetmessages: + msg192748
2013-07-08 06:42:54bignosesetmessages: + msg192621
2013-07-08 06:39:54bignosesetfiles: + issue12645.reformat_docstring.9d22bc60bd4f.patch

nosy: + bignose
messages: + msg192620

keywords: + patch
2013-07-06 11:49:48adam-collardsetfiles: + issue-12645-test-docs
nosy: + adam-collard
messages: + msg192418

2012-11-08 08:48:02ezio.melottisetnosy: + ncoghlan
stage: needs patch
type: enhancement

versions: + Python 3.4
2011-07-27 18:03:35eli.benderskycreate