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 our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Start working on the practicalities section. #55
Changes from 1 commit
2cf782e
b5e2324
c344f31
b30b966
3bf0156
958ec43
7cf319e
b542e01
f9ed6e8
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,39 +11,75 @@ This actually made the above easier and less-likely to break. | |
|
||
# As a user | ||
|
||
## Install Pip 9.0 | ||
|
||
If you are already a Python 3 user, you should not encounter a lot of | ||
disruption. Please check that the libraries you use follow best practices not | ||
to break for Python 3 users. | ||
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 a decide to run, making sure that things works make | ||
the community strong. | ||
|
||
Make sure you have Pip >= 9.0, this is especially important if you have Python | ||
2 installations. Having pip 9.0+ will not insure that you install will not | ||
break, but they are more likely not to. Having a version off 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. | ||
|
||
Make 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 concern all all installations. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Double all concern -> concerns |
||
|
||
## Setuptools | ||
|
||
If you are on a system that will not install python wheel and use `setuptools`, | ||
make sure you have setuptools >=24.2.0, or building Python 3 only libraries | ||
might fail, even on Python 2. | ||
|
||
Make sure you have Pip >= 9.0 | ||
## Local package index | ||
|
||
If you are using a custom local package index, for example if you are working | ||
at a company, make sure it implement correctly pep-512 and let pip knows about | ||
the `python_requires` field. | ||
at a company with private packages, make sure it implement correctly pep-503 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Link to the PEP? |
||
and let pip knows about the `python_requires` field. | ||
|
||
## The state of PyPI | ||
|
||
Note that at the time of this writing the patches to `pypi.python.org` are not | ||
deployed yet but should hopefully be deployed soon. | ||
|
||
|
||
# Preparing your library | ||
|
||
Things to speak about: | ||
|
||
- Be on recent enough setuptools, since [This | ||
PR](https://github.com/pypa/setuptools/pull/631), 24.2.0 (or above, July 20, | ||
2016, Xavier Fernandez PR.) | ||
|
||
Add the followign to your setup.py | ||
As a library author one of the most important factor 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 of case: | ||
|
||
You need to release your new packages version with [setuptools] version 24.2.0 | ||
or above, or use one of the alternate package manager that can set the | ||
[`python_require`] metadata field. Without this, pip 9.0 **will try** to | ||
install non-compatible version of your software on Python 2. This version of | ||
setuptools is recent (July 20, 2016) and this possible thank to the [work of | ||
Xavier Fernandez](https://github.com/pypa/setuptools/pull/631) | ||
|
||
Add the following to your `setup.py` | ||
|
||
``` | ||
setup( | ||
... | ||
python_requires='>=3.3' | ||
... | ||
) | ||
setup( | ||
... | ||
python_requires='>=3.3' | ||
... | ||
) | ||
``` | ||
|
||
change >= | ||
Changes `>=3.3` accordingly depending on what version your library decides to | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Changes -> Change There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. done. |
||
support. | ||
|
||
This will make [PyPI aware](linkto mike's PR on warehouse) that your package is | ||
Python 3 only, and [allow pip](link to pip's PR) to be [made aware of this](link to PyPI PR). | ||
|
||
|
||
- Add a warning at _runtime_ early on master (before switching to Python 3 | ||
|
@@ -102,9 +138,17 @@ This this page for more information : url to here for example. | |
|
||
`^([1-9]\\d*!)?(0|[1-9]\\d*)(\\.(0|[1-9]\\d*))*((a|b|rc)(0|[1-9]\\d*))?(\\.post(0|[1-9]\\d*))?(\\.dev(0|[1-9]\\d*))?` | ||
|
||
- depend on setuptools greater than 24.3 | ||
|
||
|
||
|
||
# Mitigations | ||
# Recommende Mitigations | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Recommended |
||
|
||
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 it still 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 | ||
the all update process broken. | ||
|
||
- 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 | ||
|
@@ -115,5 +159,22 @@ This this page for more information : url to here for example. | |
dependencies depending on the version of Python. | ||
|
||
|
||
# Non recommended mitigation | ||
|
||
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 acknowlege them, and | ||
explain why they can't work and what are their drawbacks before you attempt to | ||
implement them. | ||
|
||
### Use a meta-package. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think I'd call this something like 'alternative' rather than 'non-recommended'. It can work, and it will work with older versions of pip than our favoured strategy, it's just a bit messy and inconvenient. |
||
|
||
|
||
|
||
|
||
# Why all that ? | ||
|
||
You might wonder why all thi, it's 2016 already, so how come all these issues ? | ||
Python 3 has been out for 8+ years now ! | ||
|
||
Well there are many reasons to this, | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's say 'help' (other users to install..) rather than 'make', which sounds rather forceful. Also, emphasising users here feels a bit weird.
Let's also put in the command to copy and paste: