2017 - Building Bridges: Stopping Python 2 without damages (original) (raw)
Description
Deciding to stop support for Python 2 is a hard choice. As library authors we try to minimize the breakage for users. IPython recently moved from single-source to Python 3 only, and worked with Core Python to make such a transition possible and easy. We'll show you the new features available in pip/setuptools to make that easy for you, and tell you how the transition went for IPython.
Abstract
Up until December 2016 it was hard if not impossible to mark a release of a Python package or library only compatible with some version of Python. Pip would happily download a Python 3 only version on Python 2 system, install it and break users systems.
After much work and patching many upstream project Python packagers can finally make user of the Requires-Python greater than or equal to 3.3 metadata, which will indicate to pip not to upgrade and thus shield most users from getting indecipherable error message from installing (or running) incompatible package versions.
While these changes should now be widely available, not all systems are fully up-to-date, and knowing how things can fails is necessary to packaging your libraries accordingly. We'll show you how to prepare for such a transition.
Finally we've release IPython 6.0 – using the above techniques – and have some numbers and our experience to share, for other to be ready if/when one of the library they know (or develop) is going to stop Python 2 support. Hopefully to do a tiny bit better than us.
Bio
Matthias Bussonnier is a Post Doctoral Scholar at the University of California Berkeley institute for data science and has been a core developer of IPython and Jupyter since 2012.
Transcript
without damages http://localhost:1948/pybay.md?print-pdf#/ 8/72 I'll be describing how we did this, how you can do it. How to do it right, potentially better than us. Things we did wrong – what you can learn from the mistake we did. And we'd like to learn from your experience when you do it. 3 . 3
2. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 21/72 Scratch your own itch We wanted to release IPython 6, to be Python 3 only. We care about Python 2 users, so if a Python 2 user runs it should install the latest version of IPython 5, not IPython 6! $ pip install ipython --upgrade 6 . 1
3. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 26/72 Just $ pip install "ipython<6" on Python 2 Users do not always read documentation before installing. Scripts do not read documentation before installing. Users/scripts do not read error messages. dependencies – all packages need update to have conditional dependencies. 7 . 2
4. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 27/72 Rename ? That's going to be confusing and void most of the documentation on the Internet. Import names different from package name is also a bit tricky to explain sometime. (you meant pip install jinja2 not pip install jinja) 7 . 3
5. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 29/72 Use a metapackage Use a package with virtually no-code that have conditional dependencies, and move the "real" code to a sub package. You kinda need to re-release old code (can't requires old- yourself) pip upgrade metapackage will not pull core unless pinned deps 7 . 5
6. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 37/72 Call to all package maintainers Use tools and services that respect Require-Python pip 9+ setuptools >24.2 Tag your package with requires_python (That's also valid if you do requires_python<3, or requires_python>2.2) 9 . 1
7. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 41/72 1. Update your documentation, CIs, and scripts to use pip. 2. Communicate, Communicate, Communicate: Blog, twitter... 3. Keep setup.py and __init__.py python 2 compatible, but catch errors early. 4. For clear error messages in complicated situations, use multiple lines. 10 . 2
8. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 45/72 E.g.,: in setup.py: if sys.version_info < (3, 3): error = """ IPython 6.0+ does not support Python 2.6, 2.7, 3.0, 3.1, or 3.2. Beginning with IPython 6.0, Python 3.3 and above is required. This may be due to an out of date pip. Make sure you have pip >= 9.0.1. """ sys.exit(error) 10 . 6
9. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 47/72 E.g., in __init__.py: import sys if sys.version_info < (3,3): raise ImportError( """ IPython 6.0+ does not support Python 2.6, 2.7, 3.0, 3.1, or 3.2. Beginning with IPython 6.0, Python 3.3 and above is required. """) 10 . 8
10. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 60/72 Missing Data How many users on Python 2 have a new version of pip and are not upgrading? Fix by releasing a dummy version of the python 2 compatible version with no code change. Thus both Python 2 and 3 user should upgrade. 14 . 8
11. ### 8/11/2017 Building Bridges – Stopping Python 2 support in libraries
without damages http://localhost:1948/pybay.md?print-pdf#/ 70/72 On converting packages to Python3 only use packaging tools that respect Requires_Python encourage everyone, everywhere to use pip 9+ follow defensive packaging practices Read and contribute to python3statement practicalities section 15 . 8
