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

Eseguire il reproducer fornito e ispezionare l’entry point email.message_from_bytes, insieme alla documentazione collegata di parser e EmailMessage. Determinare se la correzione prevista consiste nel modificare il tipo restituito o nel correggere la documentazione, quindi aggiungere una copertura per il comportamento dimostrato e verificare che l’API documentata e il risultato a runtime concordino.