The email parser class returns the wrong type for the parsed message

Summary

According to the documentation,

The email package provides a standard parser that understands most email document structures, including MIME documents. You can pass the parser a bytes, string or file object, and the parser will return to you the root EmailMessage instance of the object structure.

In fact, the parser returns an object of the legacy Message class. Code which takes the documentation at face value will blow up if it attempts to invoke methods which the newer class has but the older class does not.

Environment

Python 3.11.1 (v3.11.1:a7a450f84a, Dec 6 2022, 15:24:06) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin

Repro

Here is a small program which demonstrates the problem.

Code

#!/usr/bin/env python3

import email

message_bytes = (
    b'Content-type: multipart/form-data; boundary=------abracadabra\r\n'
    b'\r\n'
    b'------abracadabra\r\n'
    b'Content-Disposition: form-data; name="f"; filename="f1"\r\n'
    b'Content-Type: application/octet-stream\r\n'
    b'\r\n'
    b'\x01\r\n'
    b'------abracadabra--\r\n'
)

message = email.message_from_bytes(message_bytes)
print(f'type of message is {type(message)}')
print('have get_content()?', hasattr(message, 'get_content'))

Output

% ./email-message-repro.py
type of message is <class 'email.message.Message'>
have get_content()? False

运行提供的复现程序，并检查入口点 email.message_from_bytes，以及相关的 parser 和 EmailMessage 文档。确定预期的修复是更改返回类型还是更正文档，然后为所演示的行为添加覆盖测试，并验证文档化的 API 与运行时结果一致。