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: Porting Python 2 to Python 3 example contradicts its own advice
Type: Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Bruce Richardson, brett.cannon, docs@python, zach.ware
Priority: normal Keywords:

Created on 2018-07-11 10:42 by Bruce Richardson, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (3)
msg321436 - (view) Author: Bruce Richardson (Bruce Richardson) Date: 2018-07-11 10:42
https://docs.python.org/3/howto/pyporting.html#use-feature-detection-instead-of-version-detection

In this section, the (very good) advice is "It would be better to treat Python 2 as the exceptional case instead of Python 3 and assume that future Python versions will be more compatible with Python 3 than Python 2"

However, it then goes on to present the best solution (for dealing with library imports) is this:

try:
    from importlib import abc
except ImportError:
    from importlib2 import abc

This is literally treating Python 3 as the exception, completely contradicting the advice given a few lines earlier.  Practically, it also has the effect that, as Python 3 adoption spreads, import errors and automatic retries will become *more* common and then universal, adding a small amount of delay and noise to the entire Python estate.  And that's not considering the case where both libraries are installed to cope with old code relying on the old library (in which case you surely want new code to default to using the new library)

If the example is simply changed to

try:
    from importlib2 import abc
except ImportError:
    from importlib import abc

then both the contradiction and the practical problems go away
msg321477 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2018-07-11 15:09
I don't agree with your conclusion here: importlib2 is a PyPI package that backports Python 3's importlib to Python 2, thus the ImportError will only be raised on Python 2 with the example as written.
msg321484 - (view) Author: Bruce Richardson (Bruce Richardson) Date: 2018-07-11 16:46
Ah, doh. my bad.

On 11 July 2018 at 16:09, Zachary Ware <report@bugs.python.org> wrote:

>
> Zachary Ware <zachary.ware@gmail.com> added the comment:
>
> I don't agree with your conclusion here: importlib2 is a PyPI package that
> backports Python 3's importlib to Python 2, thus the ImportError will only
> be raised on Python 2 with the example as written.
>
> ----------
> nosy: +zach.ware
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue34094>
> _______________________________________
>
History
Date User Action Args
2022-04-11 14:59:03adminsetgithub: 78275
2018-07-11 18:47:32brett.cannonsetstatus: open -> closed
resolution: not a bug
stage: resolved
2018-07-11 16:46:38Bruce Richardsonsetmessages: + msg321484
2018-07-11 15:09:24zach.waresetnosy: + zach.ware
messages: + msg321477
2018-07-11 10:42:09Bruce Richardsoncreate