管理包元数据

警告： 此项目是一个非常早期的alpha版本，因此所有API都可能在没有通知的情况下更改。

Python包有描述如包名、版本等信息的元数据。此元数据的详细信息定义在打包用户指南中。当存储在文件中（无论是在文件系统还是在包分发中）时，元数据以基于电子邮件标题的格式保存。

此库将元数据转换为与JSON兼容的格式，并定义在PEP 566中。JSON形式在编程环境中更容易使用。提供了两个函数

• msg_to_json(msg) - 将电子邮件标题格式转换为JSON。参数msg是电子邮件格式的元数据，作为email.message.Message对象。返回一个遵循“json”布局的字典。
• json_to_msg(json) - 将JSON形式转换回电子邮件标题。参数json是遵循“json”形式的字典。返回一个包含消息格式的（Unicode）字符串。

注意两个msg形式之间的差异：一个Message对象和一个字符串。这可能是一个可能改变的地方，因为这是一个有点尴尬的差异，但存在这种方法的理由

1. 在读取元数据时，文件应使用UTF-8编码，但历史上这并不总是如此。通过使用Message作为输入，可以从文本或字节（message_from_string或message_from_bytes）构建它，这使得电子邮件包能够处理编码问题。如果项目使用非UTF8元数据，则这种方法可能导致mojibake，但至少数据将是可用的。
2. 在编写元数据时，使用Message对象会导致出现不需要的标题字段，因为该对象假设这是一个“真实”的电子邮件，而不是仅仅重复使用该格式的数据。因此，更可靠的方法是简单地以字符串格式返回输出。然后可以按照需要将其写入UTF-8格式的文件。

使用该库的示例

with open(metadata_file, "r", encoding="utf-8") as f:
    msg = email.message_from_file(f)
metadata = pkg_metadata.msg_to_json(msg)
metadata["keywords"] = ["example", "artificial"]
with open(metadata_file, "w", encoding="utf-8") as f:
    f.write(json_to_msg(metadata))

除了元数据文件格式外，项目元数据还可以在pyproject.toml文件中指定，格式如PEP 621中所述。该库提供了一个函数，用于读取pyproject.toml中的[project]部分并将其转换为（JSON格式）元数据字典。

• pyproject_to_json(pyproject) - 将pyproject.toml元数据转换为元数据字典。pyproject参数是一个字典，表示pyproject.toml的[project]部分中的数据。

示例

with open("pyproject.toml", "rb") as f:
    pyproject_data = tomli.load(f)

metadata = pkg_metadata.pyproject_to_json(pyproject_data["project"])