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

Tutorial for phasing out Python versions #459

Merged
merged 6 commits into from Apr 3, 2018

Conversation

Projects
None yet
3 participants
@tonybaloney
Contributor

tonybaloney commented Mar 21, 2018

See #450 for discussion

tonybaloney added some commits Mar 13, 2018

@hugovk

hugovk approved these changes Mar 22, 2018

Looks good, just some little nitpicks.


Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.

Metadata 1.2+ clients, such as Pip 9.0+ will adhere to this specification by matching the current Python runtime and comparing it with the required version

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

... clients, such as Pip 9.0+ will ...

This comma acts parenthetically. So either a closing one is needed:

... clients, such as Pip 9.0+, will ...

Or the opening one not needed:

... clients such as Pip 9.0+ will ...

Metadata 1.2+ clients, such as Pip 9.0+ will adhere to this specification by matching the current Python runtime and comparing it with the required version
in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.

This mechanism can be leveraged to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.

This comment has been minimized.

@hugovk

This workflow requires that:

1. The publisher be using the latest version of :ref:`setuptools`,

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

-> "The publisher is using"

This workflow requires that:

1. The publisher be using the latest version of :ref:`setuptools`,
2. The latest version of :ref:`twine` be used to upload the package,

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

-> "is used"

Defining the Python version required
------------------------------------

1. Download the newest version of Setuptools

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

The requirements also say the latest version of Pip and Twine are needed.

Shall we make this section cover all of those, and update the command to pip install --upgrade pip setuptools twine all at once?

Or, because Pip can be a bit of a special case, at least for Setuptools and Twine.

4. Using Twine to publish
~~~~~~~~~~~~~~~~~~~~~~~~~

Twine has a number of advantages, apart from being faster is now the supported method for publishing packages.

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

Add "it" -> "apart from being faster it is now"


It must be done in this order for the automated fail-back to work.

For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

Remove "if"


For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.

If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

Remove comma:
-> "publish a new version 2.0.0 of your package"


For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.

If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

Caps:
-> "Pip 9.0+"


For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.

If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will

This comment has been minimized.

@hugovk

hugovk Mar 22, 2018

Contributor

"from version 2.7 of Python will"
->
"from Python 2.7 will"

@tonybaloney

This comment has been minimized.

Contributor

tonybaloney commented Mar 22, 2018

@hugovk all comments taken into account in 003466d

@tonybaloney

This comment has been minimized.

Contributor

tonybaloney commented Mar 22, 2018

and thank you for the thorough review! You are quite the wordsmith :-)

@hugovk

This comment has been minimized.

Contributor

hugovk commented on source/guides/dropping-older-python-versions.rst in 003466d Mar 22, 2018

Duplicate "now"

This comment has been minimized.

Contributor

tonybaloney replied Mar 22, 2018

fixed in 8f171d7

@ncoghlan

This looks excellent, thank you! There's just the one actual change request in my comments: adding a note at the top about the guide being distutils/setuptools centric. I think that's fine given that this guide is focused on long-lived projects that are most likely to be using one or the other of those projects (or a closely related derivative, like d2to1), but we should call it out so that folks using newer publishing tools like flit know they'll need to look at the flit documentation for additional details.

The rest of my comments are take-it-or-leave-it comments where we can easily postpone doing anything about them.


1. The publisher is using the latest version of :ref:`setuptools`,
2. The latest version of :ref:`twine` is used to upload the package,
3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.

This comment has been minimized.

@ncoghlan

ncoghlan Mar 22, 2018

Member

There's potentially a 4th requirement here, which is that the package index server has to populate the data-requires-python link attribute described in PEP 503. Both pypi.org (the warehouse codebase) and pypi.python.org (the legacy PyPI codebase) do that, but we're not sure about the various caching proxies that are out there - those may confound the client's version requirement detection.

However, I think we can leave that out for now, and potentially add it if folks report problems that get traced back to that issue.

This comment has been minimized.

@tonybaloney

tonybaloney Apr 3, 2018

Contributor

I'll leave this out I think

in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.

This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.

This comment has been minimized.

@ncoghlan

ncoghlan Mar 22, 2018

Member

We should include a caveat here that this guide is specifically for users of setuptools, or users of distutils that will need to upgrade to setuptools in order to be able to include the Requires-Python field in their metadata.

Users of other packaging tools will need to consult the relevant project's documentation on how to set Requires-Python, but the general approach described here will otherwise hold.

This comment has been minimized.

@tonybaloney

tonybaloney Apr 3, 2018

Contributor

added in top comment

3. Validating the Metadata before publishing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.

This comment has been minimized.

@ncoghlan

ncoghlan Mar 22, 2018

Member

While I think this section will be fine if we add an "Aimed at distutils/setuptools users" caveat at the top, it does suggest to me that a twine upload --dry-run option that printed out the headers that would be sent without actually making a POST request to the server could be very helpful. (I'll add a comment to pypa/twine#207 pointing back to this PR as an example use case)

This comment has been minimized.

@tonybaloney

tonybaloney Apr 3, 2018

Contributor

👍

4. Using Twine to publish
~~~~~~~~~~~~~~~~~~~~~~~~~

Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages.

This comment has been minimized.

@ncoghlan

ncoghlan Mar 22, 2018

Member

In addition to mentioning support here, I'd also suggest noting that it's the most reliable when it comes to correctly passing the artifact metadata to the publication server (the server doesn't inspect the artifacts directly - it relies on the client to supply the relevant metadata).

@tonybaloney

This comment has been minimized.

Contributor

tonybaloney commented Apr 3, 2018

@ncoghlan added a comment in a04ed9c

@ncoghlan ncoghlan merged commit 9cadc66 into pypa:master Apr 3, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@ncoghlan

This comment has been minimized.

Member

ncoghlan commented Apr 3, 2018

Thank you! Merged, and already up at https://packaging.python.org/guides/dropping-older-python-versions/ :)

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented Apr 3, 2018

I spotted a couple of things in the rendered version that I'd missed on review: e88a088

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment