dist_meta.metadata_mapping

collections.abc.MutableMapping which supports duplicate, case-insensitive keys.

Caution

These are pretty low-level classes. You probably don’t need to use these directly unless you’re customising the METADATA file creation or parsing.

Classes:

MetadataMapping()	Provides a MutableMapping interface to a list of fields, such as those used for Python core metadata.
MetadataEmitter(fields)	Used to construct METADATA, WHEEL and other email field-like files.

class MetadataMapping

Bases: MutableMapping[str, str]

Provides a MutableMapping interface to a list of fields, such as those used for Python core metadata.

See also

email.message.Message and email.message.EmailMessage

Implements the MutableMapping interface, which assumes there is exactly one occurrence of the field per mapping. Some fields do in fact appear multiple times, and for those fields you must use the get_all() method to obtain all values for that field.

Methods:

__len__()	Return the total number of keys, including duplicates.
__getitem__(name)	Get a field value.
__setitem__(name, val)	Set the value of a field.
__delitem__(name)	Delete all occurrences of a field, if present.
__contains__(name)	Returns whether name is in the MetadataMapping.
__iter__()	Returns an iterator over the keys in the MetadataMapping.
keys()	Return a list of all field names.
values()	Return a list of all field values.
items()	Get all the fields and their values.
get(name[, default])	Get a field value.
get_all(name[, default])	Return a list of all the values for the named field.
__repr__()	Return a string representation of the MetadataMapping.
replace(name, value)	Replace the value of the first matching field, retaining header order and case.

__len__()

Return the total number of keys, including duplicates.

Return type

int

__getitem__(name)

Get a field value.

Note

If the field appears multiple times, exactly which occurrence gets returned is undefined. Use the get_all() method to get all values matching a field name.

Parameters

name (str)

Return type

str

__setitem__(name, val)

Set the value of a field.

Parameters

• name (str)

• val (str)

__delitem__(name)

Delete all occurrences of a field, if present.

Does not raise an exception if the field is missing.

Parameters

name (str)

__contains__(name)

Returns whether name is in the MetadataMapping.

Parameters

name (object)

Return type

bool

__iter__()

Returns an iterator over the keys in the MetadataMapping.

Return type

Iterator[str]

keys()

Return a list of all field names.

These will be sorted by insertion order, and may contain duplicates. Any fields deleted and re-inserted are always appended to the field list.

Return type

List[str]

values()

Return a list of all field values.

These will be sorted by insertion order, and may contain duplicates. Any fields deleted and re-inserted are always appended to the field list.

Return type

List[str]

items()

Get all the fields and their values.

These will be sorted by insertion order, and may contain duplicates. Any fields deleted and re-inserted are always appended to the field list.

Return type

List[Tuple[str, str]]

get(name, default=None)

Get a field value.

Like __getitem__(), but returns default instead of None when the field is missing.

Note

If the field appears multiple times, exactly which occurrence gets returned is undefined. Use the get_all() method to get all values matching a field name.

Parameters

• name (str)

• default – Default None.

Return type

str

Overloads

• get(name: str) -> Optional[str]

• get(name: str, default: Union[str, ~_T] ) -> Union[str, ~_T]

get_all(name, default=None)

Return a list of all the values for the named field.

These will be sorted in the order they appeared in the original message, and may contain duplicates. Any fields deleted and re-inserted are always appended to the field list.

If no such fields exist, default is returned.

Parameters

• name (str)

• default – Default None.

Overloads

• get_all(name: str) -> Optional[List[str]]

• get_all(name: str, default: Union[str, ~_T] ) -> Union[List[str], ~_T]

__repr__()

Return a string representation of the MetadataMapping.

Return type

str

replace(name, value)

Replace the value of the first matching field, retaining header order and case.

Raises

KeyError – If no matching field was found.

class MetadataEmitter(fields)

Bases: StringList

Used to construct METADATA, WHEEL and other email field-like files.

Parameters

fields (MetadataMapping) – The fields the file is being constructed from.

Methods:

add_single(field_name)	Add a single value for the field with the given name.
add_multiple(field_name)	Add all values for the “multiple use” field with the given name.
add_body(body)	Add a body to the file.

add_single(field_name)

Add a single value for the field with the given name.

Parameters

field_name (str)

add_multiple(field_name)

Add all values for the “multiple use” field with the given name.

Parameters

field_name (str)

add_body(body)

Add a body to the file.

In an email message this is the message content itself.

Parameters

body (str)