Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Add information for lib3to6 to practicalities
Also update some prose for 2020; and for people like me who only skim headings, re-wrote the not-recommended mitigations in negative voice.
  • Loading branch information
mscuthbert authored Aug 26, 2020
commit 31d4340783bfb742494c86b5d447379c182e63bd
34 changes: 21 additions & 13 deletions _practicalities/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ is mostly written with the assumption that software are going to stop Python 2
support, it does perfectly apply to a package that wishes to not support Python 3,
or is stopping support for any minor version.


This page gathers information and links to resources allowing a library
to stop supporting an older version of Python without causing too
much disruption for users who haven't upgraded to this new version.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

~~~~

Expand Down Expand Up @@ -313,7 +312,17 @@ You can look at the [full
check](https://github.com/ipython/ipython/blob/6a3e2db0c299dc05e636653c4a43d0aa756fb1c8/setup.py#L23-L58)
that attempt to detect which version of pip is in used.

## Upload with Twine.
## If your users absolutely need Py2.7 but you want to move on

If you have users that still depend on Python 2.7 and you cannot drop support yet,
it may nonetheless be possible to start using Python 3 in your codebase. T
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
it may nonetheless be possible to start using Python 3 in your codebase. T
it may nonetheless be possible to start using Python 3 in your codebase.

hrough automatic conversion using [lib3to6](https://pypi.org/project/lib3to6/)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
hrough automatic conversion using [lib3to6](https://pypi.org/project/lib3to6/)
Through automatic conversion using [lib3to6](https://pypi.org/project/lib3to6/)

(similar to BabelJS for JavaScript)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it's named simply Babel: https://babeljs.io/

Suggested change
(similar to BabelJS for JavaScript)
(similar to Babel for JavaScript)

you can generate distribution files that will work on both Python2 and Python3.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
you can generate distribution files that will work on both Python2 and Python3.
you can generate distribution files that will work on both Python 2 and Python 3.

Lib3to6 is also useful if your project needs to support older versions of Python3
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Lib3to6 is also useful if your project needs to support older versions of Python3
Lib3to6 is also useful if your project needs to support older versions of Python 3

such as 3.5 but you want to use the latest Python syntax.

## Upload with Twine

You _must_ upload your package with ``twine`` and NOT with ``setup.py upload``.
If you have an old version of setuptools or ``distutils``, even if
Expand All @@ -332,21 +341,21 @@ and that you will hear about. This is an attempt to acknowledge them, and
explain why they can't work and what are their drawbacks before you attempt to
implement them.

### Use a meta-package
### Don't use a meta-package

It is possible to release a meta-package that has _virtually_ no code and relies
on a conditional dependency to install its actual core code on the user system.
For example, Frob-6.0 could be a meta-package which depends on
Frob-real-py2 on Python < 3.0, and Frob-real-py3 on Python ≥ 3.4. While
this approach is _doable_ this can make imports confusing.

## Depend on setuptools
## Don't depend on setuptools
Copy link
Member

@Carreau Carreau Aug 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this one is

Suggested change
## Don't depend on setuptools
## Don't depend on setuptools unless version >=24.3

Maybe ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about Don't depend on setuptools unless version >=24.3

So that it's all a list of not to dos?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good updated suggestion.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

buildscript {
repositories {
// Gradle 4.1 and higher include support for Google's Maven repo using
// the google() method. And you need to include this repo to download
//


You can mark your library as dependent on setuptools greater than 24.3 as this
will ensure that during the next upgrade (when the packages drop python 2
support) will have the right version of setuptools.

Of course regardless of all the care you will take for your library to no break
Of course regardless of all the care you will take for your library to not break
and to install only on python 2, you will likely have cases where it will still
end up being installed on incompatible versions of Python. Simply because users
upgrade rarely and only an old version of pip or setuptools is enough to make
Expand All @@ -355,8 +364,7 @@ the update process broken.
Plus setuptools is rarely an actual dependency of your project but a
requirement to build wheels.


### Multiple sdist files
### Don't write multiple sdist files

Pip (used to) support a "feature" where a sdist ending in `-pyX.Y.tar.gz` would
only be seen as compatible on Python X.Y, thus it used to be possible to
Expand All @@ -365,16 +373,16 @@ publish multiple sdist of a package targeting various python version.
It is not possible anymore to upload multiple sdist files on PyPI, so this
solution is no longer tenable.

### Wheel only?
### Don't release wheel only

Releasing a package only using wheels for a given python version is doable, but
this will break downstream packages that may require the original source to
reproduce their build.

# Why all *this*?!?

You might wonder why all this, it's 2018 already, so how come this is still an
issue? Python 3 has been out for 9+ years now!
You might wonder why all this, it's 2020 already, so how come this is still an
issue? Python 3 has been out for 11+ years now!

Well there are many reasons for this. First of all, this issue mostly affects
libraries that are currently python 2 and Python 3 compatible at the same time.
Expand All @@ -390,10 +398,10 @@ minor versions of Python 3 that saw a majority of single-source projects working
both on Python 2 and Python 3. These are the projects that will likely be
affected by this issue.

The introduction of Python 3 was chaotic; there are still strong arguments in both
The introduction of Python 3 was chaotic; there were strong arguments in both
the Python 2 and Python 3 camps. Regardless of what side you take, the ones suffering
the most from this are users (starting with the fact that inevitably some libraries
will stop supporting for Python 2 and release Python 3 only library). Inevitably, some
the most from this are users (starting with the fact that some libraries
have stopped supporting for Python 2 and released Python 3 only versions). Inevitably, some
systems and people will not be upgraded to Python 3, so this document hopefully
helps to _ensure_ that users get the _least_ breakage as possible and what are the best
practices are to follow.