Title: Support PEP 566 metadata in distutils
Type: enhancement Stage: resolved
Components: Distutils Versions: Python 3.8
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: Nosy List: dstufft, eric.araujo, ncoghlan, rbricheno
Priority: normal Keywords: patch

Created on 2018-04-29 18:51 by rbricheno, last changed 2020-05-23 19:43 by eric.araujo. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 6642 closed rbricheno, 2018-04-29 18:54
Messages (4)
msg315907 - (view) Author: Robert Bricheno (rbricheno) * Date: 2018-04-29 18:51
PEP 566 added the metadata fields 'Description-Content-Type' and 'Provides-Extra':

Currently in CPython distutils will warn if they are set, e.g.:

` UserWarning: Unknown distribution option: 'long_description_content_type'`

The warnings are emitted when using setuptools to build a wheel (say) if either of the fields are defined. They seem spurious (I can still build wheels even if I see this warning...). But they looked a bit scary to me as a new user.

There are a few possible ways to fix this. Long-term they should be fully supported by distutils I suppose. In the short term, there are a few different ways to make these warnings go away.

My preferred option would be to simply declare fields for these variables in (as per setuptools). By declaring these variables, the warnings are no longer displayed. long_description_content_type, at least, is being used in the wild since:

msg316700 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2018-05-15 19:14
In the early days, I think distutils was updated to support new metadata PEPs, and then it stopped.  Now we have an ecosystem of tools that know how to work with metadata files created by distutils or setuptools; I worry that changing distutils could break them.

See and github discussions linked from that ticket for a change proposed recently.

The situation seems different here: new params could be added to setup and Distribution, and written only if present (with the right metadata version).  But I still worry that implicitly switching the metadata version could cause trouble.

Some years ago I thought it would be good to add things to distutils (new commands or options that don’t change existing code with all its quirks), like wheel generation or stable ABI tag support.  One could imagine for example a new metadata_version param to setup to have explicit opt-in to newer metadata format.  But this would require changes to the Metadata class, could have unexpected bugs, would only be available in Python 3.8.

If we don’t touch distutils, users can be directed to setuptools that is actively maintained, or other tools like flit that don’t have all the baggage.  It’s not a seamless experience yet, but things are getting better for packaging outside of the stdlib.
msg316907 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-05-17 10:44
If these warnings are being emitted when using setuptools, that's a bug in setuptools (as it should be ensuring these are handled without warnings), and can be reported over on

If these warnings are being emitted when using plain distutils, that's OK, since it genuinely doesn't support them (and folks should be using setuptools instead).

Longer term, we want to get setuptools to the point of being independent of the standard library's copy of distutils:

Once that's the case, then we'll look at the exact mechanics of how we can stop shipping distutils by default in the standard library (and instead require folks to install setuptools in order to get it).
msg369743 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2020-05-23 19:43
Closing as per previous messages.
Date User Action Args
2020-05-23 19:43:08eric.araujosetstatus: open -> closed
title: Support PEP 566 metadata in -> Support PEP 566 metadata in distutils
messages: + msg369743

resolution: wont fix
stage: patch review -> resolved
2018-05-17 10:44:52ncoghlansetmessages: + msg316907
2018-05-15 19:14:37eric.araujosetnosy: + ncoghlan
messages: + msg316700
2018-04-29 18:54:53rbrichenosetkeywords: + patch
stage: patch review
pull_requests: + pull_request6339
2018-04-29 18:51:59rbrichenocreate