New submission from Bruce Richardson <it.is.bruce@gmail.com>: https://docs.python.org/3/howto/pyporting.html#use-feature-detection-instead... 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@python components: Documentation messages: 321436 nosy: Bruce Richardson, brett.cannon, docs@python priority: normal severity: normal status: open title: Porting Python 2 to Python 3 example contradicts its own advice _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34094> _______________________________________