- Notifications
You must be signed in to change notification settings - Fork121
Start working on the practicalities section.#55
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
Uh oh!
There was an error while loading.Please reload this page.
Conversation
_practicalities/intro.md Outdated
| Make sure you have Pip >= 9.0 | ||
| 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 |
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.
PEP 512 is the GitHub migration, so I think you may mean another PEP.
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.
Ooops, sorry. I'll fix that to 503 :-)
_practicalities/intro.md Outdated
| 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 |
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, emphasisingusers here feels a bit weird.
Let's also put in the command to copy and paste:
pip install --upgrade setuptools pip_practicalities/intro.md Outdated
| 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 comment
The reason will be displayed to describe this comment to others.Learn more.
Double all
concern -> concerns
_practicalities/intro.md Outdated
| 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 comment
The reason will be displayed to describe this comment to others.Learn more.
Link to the PEP?
_practicalities/intro.md Outdated
| # Mitigations | ||
| # Recommende Mitigations |
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.
Recommended
| 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 comment
The 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.
_practicalities/intro.md Outdated
| import sys | ||
| if sys.version_info < (3,): | ||
| Raise ValueError( |
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.
Should be lower caseraise here
Carreau commentedApr 14, 2017
Some revision and refinement in that last commit. In particular adding that invoking |
| python 2. | ||
| 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 that wish to not support Python 3, |
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.
I'm not quite sure what you're saying here. How would this apply to a package that doesn't wish to support Python 3?
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.
All the explanations are perfectly valid for someone who want to publish arequires_python<3 and it won't install on Python 3.
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.
Aha, I see.
_practicalities/intro.md Outdated
| With the recent changes in Python packaging this is now possible. | ||
| As an example let's look at the example of the`fictious` library. |
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.
Do you meanfictitious?
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.
(i.e. 'fictitious' is the English word meaning something doesn't really exist)
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.
done
_practicalities/intro.md Outdated
| Installing an`sdist` will require setuptools make sure you have setuptools | ||
| `>=24.2.0` (mnemonic: 2-42,[why | ||
| 42](https://en.wikipedia.org/wiki/The_answer_to_life_the_universe_and_everything) | ||
| ?) or building Python 3 only libraries is likely to fail. In particular if |
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.
IMO, the mnemonic here only makes things more confusing.
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.
removed.
_practicalities/intro.md Outdated
| insure they support this new functionality. | ||
| You can publish a package with the`requires_python` metadata**now**, it will | ||
| be correctly exposed once pypi is deployed. |
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.
This appears to be working now, no need to wait for PyPI to be deployed again.https://pypi.python.org/simple/flit/
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.
removed.
_practicalities/intro.md Outdated
| ) | ||
| ``` | ||
| 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 comment
The 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 comment
The reason will be displayed to describe this comment to others.Learn more.
done.
_practicalities/intro.md Outdated
| Changes`>=3.3` accordingly depending on what version your library decides to | ||
| support. In particular you can use`>=2.6` or`>=3.5` ! Note that this also | ||
| support the_compable with_ syntax:`~=2.5` (meaning,`>=2.5` and`<3`. |
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.
Close paren
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.
done.
_practicalities/intro.md Outdated
| pip](https://github.com/pypa/pip/pull/3877) to be[made aware of | ||
| this](https://github.com/pypa/pypi-legacy/pull/506). | ||
| Thus as long as your user have a recent enough version of pip, and setuptools |
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.
"...have recent enough versions of pip and setuptools..."
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.
done
_practicalities/intro.md Outdated
| 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`. You are_allowed_ to use multi-line strings in error messages. |
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.
Emphasisingallowed seems odd here. Does that mean it's allowed but discouraged?
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.
rephrased.
_practicalities/intro.md Outdated
| 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 happen. Make sure you |
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.
should not have happened
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.
done.
_practicalities/intro.md Outdated
| ##Depend on setuptools | ||
| You can mark your library as dependent on setuptools greater than 24.3 starting |
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.
I'm reluctant to recommend this because most libraries do not actually depend on setuptools, and it's annoying for packaging systems that install packages another way. With wheels, the possibility of having virtualenvs without setuptools installed is not that far off. Can we at least put in a caveat?
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.
moved and reworded.
_practicalities/intro.md Outdated
| raise a clear error message and ask user 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 and incompatible version. |
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.
and -> an
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.
fixed.
_practicalities/intro.md Outdated
| If you control dependant packages, Make sure to include conditional dependencies | ||
| depending on the version of Python. | ||
| #Incorrect mitigations |
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.
"Incorrect" seems a bit strong considering that the first one can work, and actually works on older versions of pip as well. Maybe "Non-recommended"?
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.
Fixed.
_practicalities/intro.md Outdated
| this approach is_doable_ this can make imports confusing. | ||
| Moreover, upgrading your package may need the user to explicitly tell pip to | ||
| upgrade dependencies as`pip install -U frob` will only upgrade the meta-package. |
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.
Really? I thought the issue with pip was the exact opposite, that there's no way to tell it to upgrade a single package without upgrading all dependencies as well.
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.
Well, yes, but I don't want to get into details. But if the metapackage is already up to date it won't go an resolve dependencies. So for example we get a couple of peoplepip install jupyter --upgrade which never update notebook.
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.
Eliding detail is fine so long as it's not misleading, but "will only upgrade the meta-package" is inaccurate - if it updates the metapackage, it will update the real package too. The practical upshot for package authors is that you need to make a release of the metapackage whenever you make a release of the real package.
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.
I'll just remove these 2 lines then.
_practicalities/intro.md Outdated
| already Python 3 only, but are starting to stop support for earlier versions of | ||
| Python. For example a library releasing a Python 3.4+ only version. | ||
| Python 3.3 was release end of 2012, and was the first version to support |
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.
was released at the end of...
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.
done.
Carreau commentedApr 18, 2017
Thanks, can you re-give a quick look at latest commit ? |
_practicalities/intro.md Outdated
| version of Python 3 that saw a majority of single-source project working both | ||
| on Python 2 and Python 3. These are the Project that will likely be affected by | ||
| this issue. | ||
| Python 3.3 was releaseat theend ofend of2012, and was the first version to |
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.
"end of end of"
takluyver commentedApr 18, 2017
Other than the couple of things I've commented on, I think this is OK. There's still a scattering of minor English wording fixes I could make, but I don't think we need to hold the PR up for it. |
Carreau commentedApr 18, 2017
Last 2 comments taken care of. |
Carreau commentedApr 19, 2017
I'm going to merge and refine in subsequent PR if needed. |
@michaelpacer@takluyver From last week discussion.
Mostly placeholder to throw ideas in for now.