Start working on the practicalities section. #55

Carreau · 2016-11-21T18:09:22Z

@michaelpacer @takluyver From last week discussion.

Mostly placeholder to throw ideas in for now.

brettcannon · 2016-11-21T20:11:04Z

_practicalities/intro.md

+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


PEP 512 is the GitHub migration, so I think you may mean another PEP.

Ooops, sorry. I'll fix that to 503 :-)

takluyver · 2016-11-24T22:57:27Z

_practicalities/intro.md

+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


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:

pip install --upgrade setuptools pip

takluyver · 2016-11-24T22:59:59Z

_practicalities/intro.md

+
+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.


Double all

concern -> concerns

takluyver · 2016-11-24T23:02:01Z

_practicalities/intro.md


 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


Link to the PEP?

takluyver · 2016-11-24T23:10:27Z

_practicalities/intro.md



-# Mitigations
+# Recommende Mitigations


Recommended

takluyver · 2016-11-24T23:12:54Z

_practicalities/intro.md

+explain why they can't work and what are their drawbacks before you attempt to
+implement them.
+
+### Use a meta-package.


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.

lelit · 2017-01-21T00:09:26Z

_practicalities/intro.md

+import sys
+
+if sys.version_info < (3,):
+    Raise ValueError(


Should be lower case raise here

Carreau · 2017-04-14T21:09:05Z

Some revision and refinement in that last commit. In particular adding that invoking setup.py directly may get the wrong dependency and pip install [-e] . is prefered.

takluyver · 2017-04-18T16:33:48Z

_practicalities/intro.md

-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,


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?

All the explanations are perfectly valid for someone who want to publish a requires_python<3 and it won't install on Python 3.

Aha, I see.

takluyver · 2017-04-18T17:16:48Z

_practicalities/intro.md

+
+With the recent changes in Python packaging this is now possible.
+
+As an example let's look at the example of the `fictious` library.


Do you mean fictitious?

(i.e. 'fictitious' is the English word meaning something doesn't really exist)

takluyver · 2017-04-18T17:19:25Z

_practicalities/intro.md

+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


IMO, the mnemonic here only makes things more confusing.

takluyver · 2017-04-18T17:21:48Z

_practicalities/intro.md

+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.


This appears to be working now, no need to wait for PyPI to be deployed again. https://pypi.python.org/simple/flit/

takluyver · 2017-04-18T17:22:21Z

_practicalities/intro.md

+)
+```
+
+Changes `>=3.3` accordingly depending on what version your library decides to


Changes -> Change

takluyver · 2017-04-18T17:22:44Z

_practicalities/intro.md

+
+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`.


Close paren

takluyver · 2017-04-18T17:23:30Z

_practicalities/intro.md

+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


"...have recent enough versions of pip and setuptools..."

takluyver · 2017-04-18T17:24:58Z

_practicalities/intro.md

+
+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.


Emphasising allowed seems odd here. Does that mean it's allowed but discouraged?

takluyver · 2017-04-18T17:25:32Z

_practicalities/intro.md

+
+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


should not have happened

takluyver · 2017-04-18T17:29:22Z

_practicalities/intro.md

+
+## Depend on setuptools
+
+You can mark your library as dependent on setuptools greater than 24.3 starting


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?

moved and reworded.

takluyver · 2017-04-18T17:29:46Z

_practicalities/intro.md

+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.


takluyver · 2017-04-18T17:32:12Z

_practicalities/intro.md

+If you control dependant packages, Make sure to include conditional dependencies
+depending on the version of Python.
+
+# Incorrect mitigations


"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"?

takluyver · 2017-04-18T17:34:53Z

_practicalities/intro.md

+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.


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.

pypa/pip#304

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 people pip install jupyter --upgrade which never update notebook.

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.

I'll just remove these 2 lines then.

takluyver · 2017-04-18T17:36:05Z

_practicalities/intro.md

+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


was released at the end of...

Carreau · 2017-04-18T18:48:52Z

Thanks, can you re-give a quick look at latest commit ?

takluyver · 2017-04-18T18:52:23Z

_practicalities/intro.md

-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 release at the end of end of 2012, and was the first version to


"end of end of"

takluyver · 2017-04-18T18:54:49Z

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 · 2017-04-18T20:42:07Z

Last 2 comments taken care of.

Carreau · 2017-04-19T17:36:19Z

I'm going to merge and refine in subsequent PR if needed.
Thanks !

Carreau added 2 commits November 21, 2016 10:08

Start working on the practicalities section.

2cf782e

Expand informations

b5e2324

brettcannon reviewed Nov 21, 2016

View reviewed changes

Expand more sections

c344f31

takluyver reviewed Nov 24, 2016

View reviewed changes

_practicalities/intro.md Outdated

# Mitigations

# Recommende Mitigations

Copy link

Member

takluyver Nov 24, 2016

Choose a reason for hiding this comment

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

Recommended

takluyver reviewed Nov 24, 2016

View reviewed changes

Carreau added 2 commits November 26, 2016 13:09

Fix some comments

b30b966

More infos

3bf0156

lelit reviewed Jan 21, 2017

View reviewed changes

_practicalities/intro.md Outdated

import sys

if sys.version_info < (3,):

Raise ValueError(

Copy link

lelit Jan 21, 2017

Choose a reason for hiding this comment

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

Should be lower case raise here

Some refinments

958ec43

Carreau force-pushed the practicalities branch from fe0cf4a to 958ec43 Compare April 14, 2017 21:08

'finish up practicalities'

7cf319e

takluyver reviewed Apr 18, 2017

View reviewed changes

Take into account most of Thomas comments.

b542e01

takluyver reviewed Apr 18, 2017

View reviewed changes

Last changes from Thomas

f9ed6e8

Carreau merged commit 5881c44 into python3statement:master Apr 19, 2017

Carreau deleted the practicalities branch April 19, 2017 17:36


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

		As an example let's look at the example of the `fictious` library.


		## Depend on setuptools

		You can mark your library as dependent on setuptools greater than 24.3 starting

Start working on the practicalities section. #55

Start working on the practicalities section. #55

Conversation

Carreau commented Nov 21, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Carreau commented Apr 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Carreau commented Apr 18, 2017

Choose a reason for hiding this comment

takluyver commented Apr 18, 2017

Carreau commented Apr 18, 2017

Carreau commented Apr 19, 2017