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 Distribution.requires
property.
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.