metadata object has unspecified API which leaks EmailMessage implementation
Noted on IRC,
Technically, the returned distribution metadata object is an email.message.EmailMessage instance, but this is an implementation detail, and not part of the stable API. You should only use dictionary-like methods and syntax to access the metadata contents.
According to this definition, something like
.get_all() should not be relied upon, because it is not a dictionary method. But
.get_all() serves a valuable role, see for example the implementation of
_read_dist_info_reqs(), which retrieves multiple definitions of
Requires-Dist to define the
With only access to
metadata['Requires-Dist'] it's impossible to get reliable information for metadata that can have multiple values. With
metadata.items() it's possible to get this information, but then you'd need to filter it yourself, which is clumsy and inefficient.
<jaraco> What the project needs is: A test capturing the need for multi-valued keys, a protocol describing the interface that 'metadata' guarantees to provide, and then an update to the docs to point to the protocol as the proper interface such that EmailMessage need not be mentioned.
tl;dr it seems like a good idea to document
.get_all() and anything else generally useful as part of the public
Distribution.metadata, API, without mentioning
EmailMessage at all.