Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Various grammar tweaks#72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
Carreau merged 1 commit intopython3statement:masterfrombrettcannon:patch-7
Apr 28, 2017
Merged
Changes fromall commits
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
170 changes: 87 additions & 83 deletions_practicalities/intro.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -8,48 +8,48 @@ id: bar

We do not discourage authors to release software on Python 2. While this guide
is mostly written with the assumption that software are going to stop Python 2
support, it does perfectly apply to a package thatwish to not support Python 3,
support, it does perfectly apply to a package thatwishes to not support Python 3,
or is stopping support for any minor version.


This pagegather information and links to resources allowingto release a
library that stop supporting an older version of Python without causing too
This pagegathers information and links to resources allowinga library
to stop supporting an older version of Python without causing too
much disruption for users who haven't upgraded to this new version.

Whether you are a user, or a developer, being aware of the issue listed here, at
least the main points should ease lots of the pain.
Whether you are a user or a developer, being aware of the issue listed here -- at
least the main points--should ease lots of the pain.

# Too long, did not read:

- Help and encourage users to install **pip 9.0+**
- Help and encourage users to install **setuptools 24.3+**
- As maintainer use `setup(..., python_requires='>=3.4')` new option.
-do use `pip install [-e] .` and do **not** invoke `setup.py` directly.
- **Fail** early at **install time** if on Python 2.
- We are giving a talk at PyCon 2017 (likely recorded), addlinkhere.
- As maintainer, usethe new`setup(..., python_requires='>=3.4')` option.
-Use `pip install [-e] .` and do **not** invoke `setup.py` directly.
- **Fail** early at **install time** ifuser ison Python 2.
- We are giving a talk at PyCon 2017 (likely recorded;linkto follow).

## The problem

Up until December 2016 it was hard to publish a new major version of library
that changed requirements in Python version and mark it as such so that user
Up until December 2016 it was hard to publish a new major version ofalibrary
that changed requirements in Python version and mark it as such so thatauser's
system will not try to upgrade said library.

With the recent changes in Python packaging this is now possible.

As an example let's look atthe example of the `fictitious` library.
As an example let's look ata non-existent `fictitious` library.

- `fictitious` 1.1, 1.2, 1.3, 1.4 are compatible Python 2.7 and 3.3+
- `fictitious` 2.0 has been released and is python 3.4+ only.

As a Python 2.7 user, if I don't pay attention, or if the library is not
correctly tagged,if I issuethefollowing:
correctly tagged,there can be issues when you try to updatethelibrary:

$ python -c 'import fictitious; print(fictitious.__version__)'
1.3.2
$ pip install fictitious --upgrade

Either my system will install 2.0, which will not work, on the worst case
scenario, or fail to install, in which case I will not get the critical 1.4
Either my system will install 2.0, which will not work -- the worst case
scenario -- or fail to install, in which case I will not get the critical 1.4
upgrade.

## As a user
Expand All@@ -60,17 +60,17 @@ If you are already a Python 3 user, you should not encounter a lot of
disruption. Please still check that the libraries you use follow best practices
not to break for Python 2 users. Python is a community regardless of which
python version you have to (or decided to) run, making sure that everything
worksmake the community strong.
worksmakes the community strong.

Make sure you have Pip ≥ 9.0, this is especially important if you have Python
2 installations. Having pip 9.0+ is not aguaranty to flawless upgrade. But pip
9.0+ does have a number of safety check not availableon previous versions.
2 installations. Having pip 9.0+ is not aguarantee of a flawless upgrade. But pip
9.0+ does have a number of safety check not availablein previous versions.

Having a version of pip < 9.0 can lead your system to try to upgrade to
non-compatible versions of Python packages even if these are marked as
non-compatible.

Help as many other _users_ as possible to install pip ≥ 9.0, for the
Help as many other _users_ as possible to install pip ≥ 9.0. For the
transition, it is the slowest part of the ecosystem to update, and is the only
piece that requires action of all Python users.

Expand All@@ -92,16 +92,16 @@ All good.

## Setuptools

If you are on a systemfor which no wheel is available, pip will try to
If you are on a system for which no wheel is available, pip will try to
install a source distribution (aka `sdist`).

Installing an `sdist` will require setuptools make sure you have setuptools
≥ 24.2.0 or building Python 3only librariesis likely to fail. In particular
Installing an `sdist` will require setuptools, so make sure you have setuptools
≥ 24.2.0 or building Python 3-only librarieswill likely fail. In particular
if library authors have taken time to mark their library as Python 3 only, the
`python_requires` argument to `setup()` may not be recognized and installation
will fail.

Use the following to check setuptools version :
Use the following to checkyoursetuptools version :

$ python -c 'import setuptools; print(setuptools.__version__)'
24.2.0
Expand All@@ -114,9 +114,9 @@ date system:
## Local package index

If you are using a custom local package index, for example if you are working
at a company with private packages, make sure itimplementcorrectly
[pep-503](https://www.python.org/dev/peps/pep-0503/)and let pipknows about
the `python_requires` field. This _mostly_ mean that thehtml you are exposing
at a company with private packages, make sure it correctly implements
[pep-503](https://www.python.org/dev/peps/pep-0503/)to let pipknow about
the `python_requires` field. This _mostly_ mean that theHTML you are exposing
should get a `data-python-requires` data attribute with the (html escaped)
version specifier.

Expand All@@ -129,20 +129,20 @@ insure they support this new functionality.
# Preparing your library


As a library author one of the most importantfactor in a smooth transition is
As a library author one of the most importantfactors in a smooth transition is
planning and communication, letting your user base know in advance that the
transition is happening and what step to take is critical for a transition.

For your library code here the steps you need to take to ensure that
installation will fail in the least number ofcase:
installation will fail in the least number ofcases:

You need to release yournew packages version with
You need to release yourpackage's new version with
[setuptools](https://pypi.python.org/pypi/setuptools) version 24.2.0 or above.
You can also use one of the alternate packagemanager that can set the
You can also use one of the alternate packagemanagers that can set the
[Requires-Python](https://www.python.org/dev/peps/pep-0345/#requires-python)
metadata field. Without this, pip 9.0 **will try** to install non-compatible
metadata field. Without this, pip 9.0 **will try** to installanon-compatible
version of your software on Python 2. This version of setuptools is recent
(July 20, 2016) and this possiblethank to the [work of Xavier
(July 20, 2016) and thisis allpossiblethanks to the [work of Xavier
Fernandez](https://github.com/pypa/setuptools/pull/631)

Add the following to your `setup.py`
Expand DownExpand Up@@ -172,19 +172,20 @@ they will get the right version of your library.
It is recommended **not** to invoke `setup.py` directly either with `install` or
`develop` subcommands. These may not correctly resolve dependencies, and can
install incompatible versions of dependencies. Please recommend and use `pip
install .` and `pip install -e .` for regular and developerinstall.
install .` and `pip install -e .` for regular and developerinstalls, respectively.

Check in scripts, and documentation that the correct installation command is
Check in scripts and documentation that the correct installation command is
used.

# Recommended Mitigations

These are not mandatory but should make the transition seamless by warning your
user early enough _and_ providing useful error messages.
users early enough _and_ providing useful error messages.

## Runtime warning on master

Add a warning at _runtime_ early on master (before switching to Python 3 only)
Add a warning at _runtime_ that triggers early on master
(before switching to Python 3 only)

```
import warnings
Expand All@@ -196,19 +197,20 @@ if sys.version_info < (3,):
UserWarning)
```

Your Python 2userhave a chance to upgrade, or get off master, (for example on
the LTS branch).
Your Python 2users willhave a chance to upgrade, or get off master,
(for example onthe LTS branch).

## Fail early at import time

Add an error early at import at runtime with a clear error message, leave the
early import compatible Python 2 for users to not be welcomed with a useless
`SyntaxError`. Don't hesitate to use multi-line strings in error messages.
Add an error early through import at runtime with a clear error message, leave the
early import compatible Python 2 as users will not feel welcomed with a useless
`SyntaxError` due to their Python 2 usage. Don't hesitate to use multi-line strings
in error messages.

Error at import time _will_ happen onsystem with old version of pip and
Error at import time _will_ happen onsystems with old version of pip and
setuptools. Keep in mind that saying the package is Python 3 only is not a lot
more helpful than aSyntax error. The most reasonable reason would be out of
data pip and setuptools:
more helpful than a`SyntaxError`. The most reasonable reason would be
out-of-date pip and setuptools:


```
Expand All@@ -220,7 +222,7 @@ if sys.version_info < (3,):

Unfortunately Frobulator 6.0 and above are not compatible with Python 2
anymore, and you still ended up with this version installed on your system.
That's a bummer. Sorry about that. It should not have happened. Make sure you
That's a bummer; sorry about that. It should not have happened. Make sure you
have pip ≥ 9.0 to avoid this kind of issues, as well as setuptools ≥ 24.2:

$ pip install pip setuptools --upgrade
Expand All@@ -247,14 +249,15 @@ https://i.am.an/url
## Watch out for beta releases


Make sure your version number match pep 440 or you will get surprises during
beta in particular as the `sdist` and `wheel` will appear as being different
versions, in particular sdist (during beta/rc/post) can appear with a greater
version number than wheels. Pip thus try to install the sdist instead of the
wheel, which have more chance of failing, in particular with pre 24.2 versions
of setuptools.
Make sure your version number matches
[PEP 440](https://www.python.org/dev/peps/pep-0440/) or you will get surprises
during beta, in particular as the `sdist` and `wheel` will appear as being
different versions (the sdist (during beta/rc/post) can appear with
a greater version number than wheels). Pip thus will try to install the sdist
instead of the wheel, which has more chance of failing, in particular with
pre-24.2 versions of setuptools.

The regular expression to check for validity of pep440 can befind below:
The regular expression to check for validity of pep440 can befound below:

^
([1-9]\\d*!)?
Expand All@@ -268,11 +271,11 @@ The regular expression to check for validity of pep440 can be find below:
## fail early in setup.py

Leave `setup.py` python 2 compatible and fail early. If you detect Python 2
raise a clear error message and ask user to make sure they have pip > 9.0 (or
raise a clear error message and asktheuser to make sure they have pip > 9.0 (or
migrate to Python 3). You can (try to) conditionally import pip and check for
its version but this might not be the same pip. Failing early is important to
make sure the Python installation does not install an incompatible version.
Otherwise user code can fail at runtimearbitrary later in the future, which can
Otherwise user code can fail at runtimearbitrarily later in the future, which can
be a difficult to debug and fix. Get inspiration from the message of failure at
runtime, and adapt for installation time.

Expand All@@ -281,7 +284,7 @@ runtime, and adapt for installation time.
If you control dependant packages, Make sure to include conditional dependencies
depending on the version of Python.

# Nonrecommended mitigations
# Non-recommended mitigations

This is a collection of "mitigation" or "solutions" you will find on the web
and that you will hear about. This is an attempt to acknowledge them, and
Expand All@@ -290,65 +293,66 @@ implement them.

### Use a meta-package.

It is possible to release a meta-package that has _virtually_ no code andrely
on conditional dependency to install its actual core code on the user system.
It is possible to release a meta-package that has _virtually_ no code andrelies
onaconditional 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

You can mark your library as dependent on setuptools greater than 24.3 this
You can mark your library as dependent on setuptools greater than 24.3asthis
will insure 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
and to install only on python 2, you will likely have cases where itstill end
up being installed on incompatible versions of Python. Simply because users
upgrades rarely and only an old version of pip or setuptools is enough to make
theallupdate process broken.
and to install only on python 2, you will likely have cases where itwill still
endup 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
the update process broken.

Plus setuptools is rarely an actual dependency of your project but a
requirement to build wheels.


### MultipleSdist.
### Multiplesdist 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
publish multiple sdist of a package targeting various python version.

Though itis not possible anymore to upload multiple sdist on PyPI. This
solution isthus not possible.
Itis not possible anymore to upload multiple sdistfileson PyPI, so this
solution isno longer tenable.

### Wheel only ?

Releasing a package only usingwheel for a given python version is doable, but
Releasing a package only usingwheels for a given python version is doable, but
this will break downstream packages that may require the original source to
reproducethe build.
reproducetheir build.

# Why allthat?
# Why all*this* ?!?

You might wonder why all this, it's 2016 already, so how comeall these
issues ? Python 3 has been out for 8+ years now !
You might wonder why all this, it's 2016 already, so how comethis is now an
issue ? Python 3 has been out for 8+ years now !

Well there are many reasonsto this, first of all, this issue mostlyaffect
Well there are many reasonsfor this. First of all, this issue mostlyaffects
libraries that are currently python 2 and Python 3 compatible at the same time.
Many libraries have transitioned from Python 2-only to Python 2 + 3. And the
issue of transitioning to Python 3 only is relatively recent. Technically it
can also apply to libraries that are only stopping support for 2.6, orevenare
already Python 3 only, but are starting to stopsupport for earlier versions of
Python. For example a library releasing a Python 3.4+ only version.
can also apply to libraries that are only stopping support for 2.6, or are even
already Python 3 only, but are starting to stopsupporting earlier versions of
Python (for example a library releasing a Python 3.4+ only version).

Python 3.3 wasrelease at the end of 2012, and was the first version to
Python 3.3 wasreleased at the end of 2012, and was the first version to
support (again) `u` as a prefix for Unicode string. It was one of the first
minorversion of Python 3 that saw a majority of single-sourceproject working
both on Python 2 and Python 3. These are theProject that will likely be
minorversions of Python 3 that saw a majority of single-sourceprojects working
both on Python 2 and Python 3. These are theprojects that will likely be
affected by this issue.

The introduction of Python 3 was chaotic, there are still strong argument both
in Python 2 and Python 3 camps. In the one suffering the most from this are
users. Starting with the fact that inevitably some libraries will stop support
for Python 2 and release Python 3 only library. And that inevitably some system
will will not be upgraded to Python 3 how can we _ensure_ that users get the
_least_ breakage as possible ? And what are the best practices to follow.
The introduction of Python 3 was chaotic; there are still 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
systems and people will 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.
[8]ページ先頭
©2009-2025 Movatter.jp