@@ -8,48 +8,48 @@ id: bar
88
99We do not discourage authors to release software on Python 2. While this guide
1010is mostly written with the assumption that software are going to stop Python 2
11- support, it does perfectly apply to a package thatwish to not support Python 3,
11+ support, it does perfectly apply to a package thatwishes to not support Python 3,
1212or is stopping support for any minor version.
1313
1414
15- This pagegather information and links to resources allowingto release a
16- library that stop supporting an older version of Python without causing too
15+ This pagegathers information and links to resources allowinga library
16+ to stop supporting an older version of Python without causing too
1717much disruption for users who haven't upgraded to this new version.
1818
19- Whether you are a user, or a developer, being aware of the issue listed here, at
20- least the main points should ease lots of the pain.
19+ Whether you are a user or a developer, being aware of the issue listed here -- at
20+ least the main points-- should ease lots of the pain.
2121
2222#Too long, did not read:
2323
2424- Help and encourage users to install** pip 9.0+**
2525- Help and encourage users to install** setuptools 24.3+**
26- - As maintainer use` setup(..., python_requires='>=3.4') ` new option.
27- - do use ` pip install [-e] . ` and do** not** invoke` setup.py ` directly.
28- - ** Fail** early at** install time** if on Python 2.
29- - We are giving a talk at PyCon 2017 (likely recorded), add linkhere .
26+ - As maintainer, usethe new ` setup(..., python_requires='>=3.4') ` option.
27+ - Use ` pip install [-e] . ` and do** not** invoke` setup.py ` directly.
28+ - ** Fail** early at** install time** ifuser is on Python 2.
29+ - We are giving a talk at PyCon 2017 (likely recorded; linkto follow) .
3030
3131##The problem
3232
33- Up until December 2016 it was hard to publish a new major version of library
34- that changed requirements in Python version and mark it as such so that user
33+ Up until December 2016 it was hard to publish a new major version ofa library
34+ that changed requirements in Python version and mark it as such so thata user's
3535system will not try to upgrade said library.
3636
3737With the recent changes in Python packaging this is now possible.
3838
39- As an example let's look atthe example of the ` fictitious ` library.
39+ As an example let's look ata non-existent ` fictitious ` library.
4040
4141- ` fictitious ` 1.1, 1.2, 1.3, 1.4 are compatible Python 2.7 and 3.3+
4242- ` fictitious ` 2.0 has been released and is python 3.4+ only.
4343
4444As a Python 2.7 user, if I don't pay attention, or if the library is not
45- correctly tagged,if I issue thefollowing :
45+ correctly tagged,there can be issues when you try to update thelibrary :
4646
4747$ python -c 'import fictitious; print(fictitious.__version__)'
48481.3.2
4949$ pip install fictitious --upgrade
5050
51- Either my system will install 2.0, which will not work, on the worst case
52- scenario, or fail to install, in which case I will not get the critical 1.4
51+ Either my system will install 2.0, which will not work -- the worst case
52+ scenario -- or fail to install, in which case I will not get the critical 1.4
5353upgrade.
5454
5555##As a user
@@ -60,17 +60,17 @@ If you are already a Python 3 user, you should not encounter a lot of
6060disruption. Please still check that the libraries you use follow best practices
6161not to break for Python 2 users. Python is a community regardless of which
6262python version you have to (or decided to) run, making sure that everything
63- worksmake the community strong.
63+ worksmakes the community strong.
6464
6565Make sure you have Pip ≥ 9.0, this is especially important if you have Python
66- 2 installations. Having pip 9.0+ is not aguaranty to flawless upgrade. But pip
67- 9.0+ does have a number of safety check not availableon previous versions.
66+ 2 installations. Having pip 9.0+ is not aguarantee of a flawless upgrade. But pip
67+ 9.0+ does have a number of safety check not availablein previous versions.
6868
6969Having a version of pip < 9.0 can lead your system to try to upgrade to
7070non-compatible versions of Python packages even if these are marked as
7171non-compatible.
7272
73- Help as many other_ users_ as possible to install pip ≥ 9.0, for the
73+ Help as many other_ users_ as possible to install pip ≥ 9.0. For the
7474transition, it is the slowest part of the ecosystem to update, and is the only
7575piece that requires action of all Python users.
7676
@@ -92,16 +92,16 @@ All good.
9292
9393##Setuptools
9494
95- If you are on a system
95+ If you are on a system for which no wheel is available, pip will try to
9696install a source distribution (aka` sdist ` ).
9797
98- Installing an` sdist ` will require setuptools make sure you have setuptools
99- ≥ 24.2.0 or building Python 3is likely to fail. In particular
98+ Installing an` sdist ` will require setuptools, so make sure you have setuptools
99+ ≥ 24.2.0 or building Python 3- only librarieswill likely fail. In particular
100100if library authors have taken time to mark their library as Python 3 only, the
101101` python_requires ` argument to` setup() ` may not be recognized and installation
102102will fail.
103103
104- Use the following to check setuptools version :
104+ Use the following to checkyour setuptools version :
105105
106106$ python -c 'import setuptools; print(setuptools.__version__)'
10710724.2.0
@@ -114,9 +114,9 @@ date system:
114114##Local package index
115115
116116If you are using a custom local package index, for example if you are working
117- at a company with private packages, make sure itimplement correctly
118- [ pep-503] ( https://www.python.org/dev/peps/pep-0503/ ) and let pipknows about
119- the` python_requires ` field. This_ mostly_ mean that thehtml you are exposing
117+ at a company with private packages, make sure it correctly implements
118+ [ pep-503] ( https://www.python.org/dev/peps/pep-0503/ ) to let pipknow about
119+ the` python_requires ` field. This_ mostly_ mean that theHTML you are exposing
120120should get a` data-python-requires ` data attribute with the (html escaped)
121121version specifier.
122122
@@ -129,20 +129,20 @@ insure they support this new functionality.
129129#Preparing your library
130130
131131
132- As a library author one of the most importantfactor in a smooth transition is
132+ As a library author one of the most importantfactors in a smooth transition is
133133planning and communication, letting your user base know in advance that the
134134transition is happening and what step to take is critical for a transition.
135135
136136For your library code here the steps you need to take to ensure that
137- installation will fail in the least number ofcase :
137+ installation will fail in the least number ofcases :
138138
139- You need to release yournew packages version with
139+ You need to release yourpackage's new version with
140140[ setuptools] ( https://pypi.python.org/pypi/setuptools ) version 24.2.0 or above.
141- You can also use one of the alternate packagemanager that can set the
141+ You can also use one of the alternate packagemanagers that can set the
142142[ Requires-Python] ( https://www.python.org/dev/peps/pep-0345/#requires-python )
143- metadata field. Without this, pip 9.0** will try** to install non-compatible
143+ metadata field. Without this, pip 9.0** will try** to installa non-compatible
144144version of your software on Python 2. This version of setuptools is recent
145- (July 20, 2016) and this possiblethank to the[ work of Xavier
145+ (July 20, 2016) and thisis all possiblethanks to the[ work of Xavier
146146Fernandez] ( https://github.com/pypa/setuptools/pull/631 )
147147
148148Add the following to your` setup.py `
@@ -172,19 +172,20 @@ they will get the right version of your library.
172172It is recommended** not** to invoke` setup.py ` directly either with` install ` or
173173` develop ` subcommands. These may not correctly resolve dependencies, and can
174174install incompatible versions of dependencies. Please recommend and use `pip
175- install .` and ` pip install -e .` for regular and developerinstall .
175+ install .` and ` pip install -e .` for regular and developerinstalls, respectively .
176176
177- Check in scripts, and documentation that the correct installation command is
177+ Check in scripts and documentation that the correct installation command is
178178used.
179179
180180#Recommended Mitigations
181181
182182These are not mandatory but should make the transition seamless by warning your
183- user early enough_ and_ providing useful error messages.
183+ users early enough_ and_ providing useful error messages.
184184
185185##Runtime warning on master
186186
187- Add a warning at_ runtime_ early on master (before switching to Python 3 only)
187+ Add a warning at_ runtime_ that triggers early on master
188+ (before switching to Python 3 only)
188189
189190```
190191import warnings
@@ -196,19 +197,20 @@ if sys.version_info < (3,):
196197 UserWarning)
197198```
198199
199- Your Python 2user have a chance to upgrade, or get off master, (for example on
200- the LTS branch).
200+ Your Python 2users will have a chance to upgrade, or get off master,
201+ (for example on the LTS branch).
201202
202203##Fail early at import time
203204
204- Add an error early at import at runtime with a clear error message, leave the
205- early import compatible Python 2 for users to not be welcomed with a useless
206- ` SyntaxError ` . Don't hesitate to use multi-line strings in error messages.
205+ Add an error early through import at runtime with a clear error message, leave the
206+ early import compatible Python 2 as users will not feel welcomed with a useless
207+ ` SyntaxError ` due to their Python 2 usage. Don't hesitate to use multi-line strings
208+ in error messages.
207209
208- Error at import time_ will_ happen onsystem with old version of pip and
210+ Error at import time_ will_ happen onsystems with old version of pip and
209211setuptools. Keep in mind that saying the package is Python 3 only is not a lot
210- more helpful than aSyntax error . The most reasonable reason would be out of
211- data pip and setuptools:
212+ more helpful than a` SyntaxError ` . The most reasonable reason would be
213+ out-of-date pip and setuptools:
212214
213215
214216```
@@ -220,7 +222,7 @@ if sys.version_info < (3,):
220222
221223Unfortunately Frobulator 6.0 and above are not compatible with Python 2
222224anymore, and you still ended up with this version installed on your system.
223- That's a bummer. Sorry about that. It should not have happened. Make sure you
225+ That's a bummer; sorry about that. It should not have happened. Make sure you
224226have pip ≥ 9.0 to avoid this kind of issues, as well as setuptools ≥ 24.2:
225227
226228 $ pip install pip setuptools --upgrade
@@ -247,14 +249,15 @@ https://i.am.an/url
247249##Watch out for beta releases
248250
249251
250- Make sure your version number match pep 440 or you will get surprises during
251- beta in particular as the` sdist ` and` wheel ` will appear as being different
252- versions, in particular sdist (during beta/rc/post) can appear with a greater
253- version number than wheels. Pip thus try to install the sdist instead of the
254- wheel, which have more chance of failing, in particular with pre 24.2 versions
255- of setuptools.
252+ Make sure your version number matches
253+ [ PEP 440] ( https://www.python.org/dev/peps/pep-0440/ ) or you will get surprises
254+ during beta, in particular as the` sdist ` and` wheel ` will appear as being
255+ different versions (the sdist (during beta/rc/post) can appear with
256+ a greater version number than wheels). Pip thus will try to install the sdist
257+ instead of the wheel, which has more chance of failing, in particular with
258+ pre-24.2 versions of setuptools.
256259
257- The regular expression to check for validity of pep440 can befind below:
260+ The regular expression to check for validity of pep440 can befound below:
258261
259262^
260263([1-9]\\d*!)?
@@ -268,11 +271,11 @@ The regular expression to check for validity of pep440 can be find below:
268271##fail early in setup.py
269272
270273Leave` setup.py ` python 2 compatible and fail early. If you detect Python 2
271- raise a clear error message and ask user to make sure they have pip > 9.0 (or
274+ raise a clear error message and askthe user to make sure they have pip > 9.0 (or
272275migrate to Python 3). You can (try to) conditionally import pip and check for
273276its version but this might not be the same pip. Failing early is important to
274277make sure the Python installation does not install an incompatible version.
275- Otherwise user code can fail at runtimearbitrary later in the future, which can
278+ Otherwise user code can fail at runtimearbitrarily later in the future, which can
276279be a difficult to debug and fix. Get inspiration from the message of failure at
277280runtime, and adapt for installation time.
278281
@@ -281,7 +284,7 @@ runtime, and adapt for installation time.
281284If you control dependant packages, Make sure to include conditional dependencies
282285depending on the version of Python.
283286
284- #Non
287+ #Non- recommended mitigations
285288
286289This is a collection of "mitigation" or "solutions" you will find on the web
287290and that you will hear about. This is an attempt to acknowledge them, and
@@ -290,65 +293,66 @@ implement them.
290293
291294###Use a meta-package.
292295
293- It is possible to release a meta-package that has_ virtually_ no code andrely
294- on conditional dependency to install its actual core code on the user system.
296+ It is possible to release a meta-package that has_ virtually_ no code andrelies
297+ ona conditional dependency to install its actual core code on the user system.
295298For example, Frob-6.0 could be a meta-package which depends on
296299Frob-real-py2 on Python < 3.0, and Frob-real-py3 on Python ≥ 3.4. While
297300this approach is_ doable_ this can make imports confusing.
298301
299302##Depend on setuptools
300303
301- You can mark your library as dependent on setuptools greater than 24.3 this
304+ You can mark your library as dependent on setuptools greater than 24.3as this
302305will insure that during the next upgrade (when the packages drop python 2
303306support) will have the right version of setuptools.
304307
305308Of course regardless of all the care you will take for your library to no break
306- and to install only on python 2, you will likely have cases where itstill end
307- up being installed on incompatible versions of Python. Simply because users
308- upgrades rarely and only an old version of pip or setuptools is enough to make
309- theall update process broken.
309+ and to install only on python 2, you will likely have cases where itwill still
310+ end up being installed on incompatible versions of Python. Simply because users
311+ upgrade rarely and only an old version of pip or setuptools is enough to make
312+ the update process broken.
310313
311314Plus setuptools is rarely an actual dependency of your project but a
312315requirement to build wheels.
313316
314317
315- ###MultipleSdist.
318+ ###Multiplesdist files
316319
317320Pip (used to) support a "feature" where a sdist ending in` -pyX.Y.tar.gz ` would
318321only be seen as compatible on Python X.Y, thus it used to be possible to
319322publish multiple sdist of a package targeting various python version.
320323
321- Though it is not possible anymore to upload multiple sdist on PyPI. This
322- solution isthus not possible .
324+ It is not possible anymore to upload multiple sdistfiles on PyPI, so this
325+ solution isno longer tenable .
323326
324327###Wheel only ?
325328
326- Releasing a package only usingwheel for a given python version is doable, but
329+ Releasing a package only usingwheels for a given python version is doable, but
327330this will break downstream packages that may require the original source to
328- reproducethe build.
331+ reproducetheir build.
329332
330- #Why allthat ?
333+ #Why all* this * ?! ?
331334
332- You might wonder why all this, it's 2016 already, so how comeall these
333- issues ? Python 3 has been out for 8+ years now !
335+ You might wonder why all this, it's 2016 already, so how comethis is now an
336+ issue ? Python 3 has been out for 8+ years now !
334337
335- Well there are many reasonsto this, first of all, this issue mostlyaffect
338+ Well there are many reasonsfor this. First of all, this issue mostlyaffects
336339libraries that are currently python 2 and Python 3 compatible at the same time.
337340Many libraries have transitioned from Python 2-only to Python 2 + 3. And the
338341issue of transitioning to Python 3 only is relatively recent. Technically it
339- can also apply to libraries that are only stopping support for 2.6, oreven are
340- already Python 3 only, but are starting to stopsupport for earlier versions of
341- Python. For example a library releasing a Python 3.4+ only version.
342+ can also apply to libraries that are only stopping support for 2.6, or are even
343+ already Python 3 only, but are starting to stopsupporting earlier versions of
344+ Python (for example a library releasing a Python 3.4+ only version) .
342345
343- Python 3.3 wasrelease at the end of 2012, and was the first version to
346+ Python 3.3 wasreleased at the end of 2012, and was the first version to
344347support (again)` u ` as a prefix for Unicode string. It was one of the first
345- minorversion of Python 3 that saw a majority of single-sourceproject working
346- both on Python 2 and Python 3. These are theProject that will likely be
348+ minorversions of Python 3 that saw a majority of single-sourceprojects working
349+ both on Python 2 and Python 3. These are theprojects that will likely be
347350affected by this issue.
348351
349- The introduction of Python 3 was chaotic, there are still strong argument both
350- in Python 2 and Python 3 camps. In the one suffering the most from this are
351- users. Starting with the fact that inevitably some libraries will stop support
352- for Python 2 and release Python 3 only library. And that inevitably some system
353- will will not be upgraded to Python 3 how can we_ ensure_ that users get the
354- _ least_ breakage as possible ? And what are the best practices to follow.
352+ The introduction of Python 3 was chaotic; there are still strong arguments in both
353+ the Python 2 and Python 3 camps. Regardless of what side you take, the ones suffering
354+ the most from this are users (starting with the fact that inevitably some libraries
355+ will stop supporting for Python 2 and release Python 3 only library). Inevitably, some
356+ systems and people will will not be upgraded to Python 3, so this document hopefully
357+ helps to_ ensure_ that users get the_ least_ breakage as possible and what are the best
358+ practices are to follow.