mailbox: document Message vs EmailMessage situation

[spanezz]

Documentation

If I read the email documentation, it makes a clear case for staying away from email.Message:

The foregoing represent the modern (unicode friendly) API of the email package. The remaining sections, starting with the Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The compat32 API does not hide the details of the RFCs from the application, but for applications that need to operate at that level, they can be useful tools. This documentation is also relevant for applications that are still using the compat32 API for backward compatibility reasons.

Changed in version 3.6: Docs reorganized and rewritten to promote the new EmailMessage/EmailPolicy API.

And indeed, there are common tasks that are hard to do in email.Message and easy with EmailMessage (see get_body() for a very common use case).

However in the documentation of mailbox, email.Message is mentioned like it's the standard.

Since at the moment in the standard library, with regards to email handling, the rule "There should be one-- and preferably only one --obvious way to do it." seems to be violated, and there are several classes with confusingly similar names but very different roles (mailbox.Message, email.Message, email.message.EmailMessage) it would help to have a clarification of the situation in the documentation of mailbox, at least until #77156 happens.

I don't know enough of the background that led to this situation to be able to draft a serious proposal for the documentation, but I guess something along the lines of this could be an initial draft:

There are currently two distinct classes for handling emails: email.Message (deprecated), and email.message.EmailMessage. The latter is more featureful and easier to use, but the mailbox module still has not been updated to transition to it.
mailbox subclasses the deprecated email.Message as mailbox.Message, to act as the base hierarchy for messages read from mailboxes.
It is expected that mailbox.Message will become a subclass of email.message.EmailMessage in a future version of Python [insert API compatibility notes].