I think the changes that relate to python/cpython#128110 should be pulled into a separate commit.
I assume the hope is that this will be fixed and these changes are not required? Does this feel like a blocker to move to the new mail api?
It's strange to me to only see references to working around a Python bug within our test suite (as we use message_from_bytes in our code)

It's strange to me to only see references to working around a Python bug within our test suite (as we use message_from_bytes in our code)

Ah, I'd been thinking message_from_bytes was only used in the test suite. But you're correct, there is a single use in django.core.mail. You can add a message/rfc822 attachment with EmailMessage.attach("filename.eml", b"From: ...\r\nTo: ...\r\n...", "message/rfc822"). We use message_from_bytes to convert the content to a message attachment.

The Python bug is not a security issue, and I don't believe should be a blocker for this PR.

Unlike that one relatively narrow case in django.core.mail, the tests use message_from_bytes a lot, and go out of their way to test cases impacted by the bug, so a workaround in the tests made sense to me.

There a few options:

• Pull the workaround into django.core.mail. I'm confident the workaround is sufficiently good for purposes of the test cases; I'm less confident about treating it as a supported feature.
• Wait for the cpython fix to land. (Realistically, that could happen next month, next year, or five years from now. Also, since it's not a security issue, backports will be limited.)
• Recognize that Python modern email has bugs too, and that they're different bugs from legacy email. (I mentioned that as a risk in the original discussion.) This is one of those bugs. If a similar non-security bug were reported against django.core.mail due to the legacy APIs, I suspect we would close it as wontfix, point to the upstream issue, and suggest the user implement their own workarounds. (I could even preemptively open and close a Django ticket for this issue once this PR is merged 😄 )

(Pulled workaround into a separate commit, but kept it test-only.)

That the return type of a documented function has changed feels like a breaking change (especially as there is a note about overwriting this in the docs).
We might want to have a way for folks to opt-in/out to the return format (and that this opt-in/out method is deprecated).

We might want to have a way for folks to opt-in/out to the return format (and that this opt-in/out method is deprecated).

Hmm, the old return format is "a django.core.mail.SafeMIMEText object (a subclass of Python’s MIMEText class) or a django.core.mail.SafeMIMEMultipart object."

That is also the total extent of Django's documentation for those classes.

As part of the django-developers discussion last year, I looked into how SafeMIMEText and SafeMIMEMultipart are being used in public codebases. As the return value of EmailMessage.message(), usage was either:

• For type checking
• To call documented methods of Python's email.message.Message (primarily as_bytes())

email.message.Message is the root class of all legacy MIME* classes and modern email.message.EmailMessage, so existing code using documented APIs should continue to work with the new return type. (Other than varying constructor args, there are no documented APIs on MIMEText or any of its base classes until you get to email.message.Message.)

So an opt-in for the old return type seems relevant only for type checking usage. There are a few approaches we could consider:

• In django.core.mail, set (deprecated) SafeMIMEText = SafeMIMEMultipart = email.message.EmailMessage. This would make type checking strictly accurate for the new return type. But it would also break a lot of real world code that uses the SafeMIME classes off label (mainly to safely construct attachments to pass to EmailMessage.attach()).
• Change the documented return type of EmailMessage.message() to email.message.Message in Django 6.0, and make no other changes for now. Wait until Django 7.0 to land this PR.
• Add a setting or EmailMessage option that opts into/out of the old SafeMIME objects. I worry that would involve a substantial reworking of this PR to offer both code paths in parallel. (Maybe you had a better approach in mind?)
• Suggest that django-stubs declare the return type of EmailMessage.message() to be email.message.Message, which is accurate both before and after this PR.

Since Django doesn't officially support type checking, my preference would be the last one.

Ugh, sorry, here's a much shorter version of what I wanted to say:

The new return type of EmailMessage.message() supports all of the documented behavior of the old return type, with one exception: isinstance(SafeMIMEText) won't be true for the new return type.

In my public code search last year, I don't recall seeing any usage of isinstance() checks on EmailMessage.message() return values. And the ways I can think to maintain isinstance() compatibility would either break a lot of code I did see that uses the SafeMIME classes for other (albeit undocumented) purposes, or would involve maintaining two versions of EmailMessage.message() and everything below it.

(Maybe I should mention in the release notes that Python's email.message.EmailMessage supports the same API as SafeMIMEText and SafeMIMEMultipart?)

(I've updated the 6.0 release notes with this information.)

Perhaps:

I am also thinking we have a section in the "What's new", something like:

Adoption of Python’s modern email API
-------------------------------------

Email handling in Django now uses Python's modern email API, introduced in
Python 3.6. This API, centered around the
:py:class:`email.message.EmailMessage` class, offers a cleaner and
Unicode-friendly interface for composing and sending emails. It replaces use of
Python's older legacy (``Compat32``) API, which relied on lower-level MIME
classes (from :py:mod:`email.mime`) and required more manual handling of
message structure and encoding.

Notably, return type of ``EmailMessage.message()`` is now an instance of
Python's :py:class:`email.message.EmailMessage`. This supports the same API as
the previous ``SafeMIMEText`` and ``SafeMIMEMultipart`` return types, but is
not an instance of those now-deprecated classes.

I think as this behavior is not deprecated but just changed, this is more appropriate 🤔

I'm not sure this comment helps me, are we refering to encoding here?

I can revert this without test failures

I think this has been done so the import path can stay the same? Would we not want to do BadHeaderError, SafeMIMEText, SafeMIMEMultipart as well?