[docs] [issue34094] Porting Python 2 to Python 3 example contradicts its own advice

[Bruce Richardson]

New submission from Bruce Richardson <it.is.bruce at gmail.com>:

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

----------
assignee: docs at python
components: Documentation
messages: 321436
nosy: Bruce Richardson, brett.cannon, docs at python
priority: normal
severity: normal
status: open
title: Porting Python 2 to Python 3 example contradicts its own advice

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34094>
_______________________________________