summaryrefslogtreecommitdiffstats
path: root/Doc/howto/pyporting.rst
diff options
context:
space:
mode:
authorBrett Cannon <brett@python.org>2016-03-18 20:23:58 (GMT)
committerBrett Cannon <brett@python.org>2016-03-18 20:23:58 (GMT)
commitadcb6545194abdbefa47e5377367041634f1577c (patch)
tree766178932aa5ffd28146dad5addf5c8481ac0ffa /Doc/howto/pyporting.rst
parent62564dbb4b4a882d4702111ba43bb5b204945a62 (diff)
downloadcpython-adcb6545194abdbefa47e5377367041634f1577c.zip
cpython-adcb6545194abdbefa47e5377367041634f1577c.tar.gz
cpython-adcb6545194abdbefa47e5377367041634f1577c.tar.bz2
Suggest people use feature detection in porting guide
Diffstat (limited to 'Doc/howto/pyporting.rst')
-rw-r--r--Doc/howto/pyporting.rst46
1 files changed, 46 insertions, 0 deletions
diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst
index 87b68d4..621d901 100644
--- a/Doc/howto/pyporting.rst
+++ b/Doc/howto/pyporting.rst
@@ -282,6 +282,50 @@ To summarize:
appropriate
#. Be careful when indexing binary data
+
+Use feature detection instead of version detection
+++++++++++++++++++++++++++++++++++++++++++++++++++
+Inevitably you will have code that has to choose what to do based on what
+version of Python is running. The best way to do this is with feature detection
+of whether the version of Python you're running under supports what you need.
+If for some reason that doesn't work then you should make the version check is
+against Python 2 and not Python 3. To help explain this, let's look at an
+example.
+
+Let's pretend that you need access to a feature of importlib_ that
+is available in Python's standard library since Python 3.3 and available for
+Python 2 through importlib2_ on PyPI. You might be tempted to write code to
+access e.g. the ``importlib.abc`` module by doing the following::
+
+ import sys
+
+ if sys.version[0] == 3:
+ from importlib import abc
+ else:
+ from importlib2 import abc
+
+The problem with this code is what happens when Python 4 comes out? 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::
+
+ import sys
+
+ if sys.version[0] > 2:
+ from importlib import abc
+ else:
+ from importlib2 import abc
+
+The best solution, though, is to do no version detection at all and instead rely
+on feature detection. That avoids any potential issues of getting the version
+detection wrong and helps keep you future-compatible::
+
+ try:
+ from importlib import abc
+ except ImportError:
+ from importlib2 import abc
+
+
Prevent compatibility regressions
---------------------------------
@@ -381,6 +425,8 @@ supported by Python 2. You should also update the classifiers in your
.. _cheat sheet: http://python-future.org/compatible_idioms.html
.. _coverage.py: https://pypi.python.org/pypi/coverage
.. _Futurize: http://python-future.org/automatic_conversion.html
+.. _importlib: https://docs.python.org/3/library/importlib.html#module-importlib
+.. _importlib2: https://pypi.python.org/pypi/importlib2
.. _Modernize: http://python-modernize.readthedocs.org/en/latest/
.. _Porting to Python 3: http://python3porting.com/
.. _Pylint: https://pypi.python.org/pypi/pylint