Updated docs for class django.core.mail.EmailMessage to use Sphinx
`method::` directives, allowing cross references to those methods
elsewhere in the docs.
Updated references to those methods in the email docs and 6.0 release
notes to link directly to the specific methods.
Lines in the docs files were manually adjusted to conform to the
79 columns limit per line (plus newline), improving readability and
consistency across the content.
- Changed EmailMessage.message() to construct a "modern email API"
email.message.EmailMessage and added policy keyword arg.
- Added support for modern MIMEPart objects in EmailMessage.attach()
(and EmailMessage constructor, EmailMessage.attachments list).
- Updated SMTP EmailBackend to use modern email.policy.SMTP.
Deprecated:
- Attaching MIMEBase objects (replace with MIMEPart)
- BadHeaderError (modern email uses ValueError)
- SafeMIMEText, SafeMIMEMultipart (unnecessary for modern email)
- django.core.mail.forbid_multi_line_headers()
(undocumented, but exposed via `__all__` and in wide use)
- django.core.mail.message.sanitize_address()
(undocumented, but in wide use)
Removed without deprecation (all undocumented):
- EmailMessage.mixed_subtype
- EmailMultiAlternatives.alternative_subtype
- Support for setting (undocumented) EmailMessage.encoding property
to a legacy email.charset.Charset object
Related changes:
- Dropped tests for incorrect RFC 2047 encoding of non-ASCII email
address localparts. This is specifically prohibited by RFC 2047, and
not supported by any known MTA or email client. (Python still
mis-applies encoded-word to non-ASCII localparts, but it is a bug that
may be fixed in the future.)
- Added tests that try to discourage using Python's legacy email APIs
in future updates to django.core.mail.
Reordered the keyword-only EmailMessage parameters in the documentation
to group similar options together and move rarely used options later.
Used keywords for *all* parameters in EmailMessage examples to improve
clarity.
In public mail APIs, changed less frequently used parameters from
keyword-or-positional to keyword-only, emitting a warning during the
required deprecation period.
This also removes unnecessary comments with the previous spelling.
AP Stylebook has a short entry to advise the preferred spelling for
"en-us". "Afterwards" is preferred in British English.
This patch does not remove all occurrences of the words in question.
Rather, I went through all of the occurrences of the words listed
below, and judged if they a) suggested the reader had some kind of
knowledge/experience, and b) if they added anything of value (including
tone of voice, etc). I left most of the words alone. I looked at the
following words:
- simply/simple
- easy/easier/easiest
- obvious
- just
- merely
- straightforward
- ridiculous
Thanks to Carlton Gibson for guidance on how to approach this issue, and
to Tim Bell for providing the idea. But the enormous lion's share of
thanks go to Adam Johnson for his patient and helpful review.
The fallback logic which allows non-UTF-8 encoded files to be passed to
attach_file() even when a `text/*` mime type has been specified is
moved to attach(). Both functions now fall back to a content type of
`application/octet-stream`.
A side effect is that a file's content is decoded in memory instead of
opening it in text mode and reading it into a string.
Some mimetype-related logic in _create_attachment() has become
obsolete as the code moved from attach_file() to attach() already
handles this.
