Skip to content
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

tonybaloney
Copy link
Contributor

@tonybaloney tonybaloney commented Mar 21, 2018

See #450 for discussion

hugovk
hugovk approved these changes Mar 22, 2018
Copy link
Contributor

@hugovk hugovk left a comment

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
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

... 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.
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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


This workflow requires that:

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

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

-> "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,
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

-> "is used"

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

1. Download the newest version of Setuptools
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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.
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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.
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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
Copy link
Contributor

@hugovk hugovk Mar 22, 2018

Choose a reason for hiding this comment

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

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

@tonybaloney
Copy link
Contributor Author

tonybaloney commented Mar 22, 2018

@hugovk all comments taken into account in 003466d

@tonybaloney
Copy link
Contributor Author

tonybaloney commented Mar 22, 2018

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

Copy link
Member

@ncoghlan ncoghlan left a comment

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.
Copy link
Member

@ncoghlan ncoghlan Mar 22, 2018

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

@tonybaloney tonybaloney Apr 3, 2018

Choose a reason for hiding this comment

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

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.

Copy link
Member

@ncoghlan ncoghlan Mar 22, 2018

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

@tonybaloney tonybaloney Apr 3, 2018

Choose a reason for hiding this comment

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

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.
Copy link
Member

@ncoghlan ncoghlan Mar 22, 2018

Choose a reason for hiding this comment

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

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)

Copy link
Contributor Author

@tonybaloney tonybaloney Apr 3, 2018

Choose a reason for hiding this comment

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

👍

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

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

@ncoghlan ncoghlan Mar 22, 2018

Choose a reason for hiding this comment

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

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
Copy link
Contributor Author

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
@ncoghlan
Copy link
Member

ncoghlan commented Apr 3, 2018

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

@ncoghlan
Copy link
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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants