On Friday, June 28, 2024 at 1:07:35 PM UTC-7 Florian Apolloner wrote: > Are all of those documented? If not we can simply remove them (especially if the deprecation implementation turns out to be a PITA).
It sort of depends on the definition of "documented." I've dug into real-world usage; results and proposals below. Incidentally, I thought there was (used to be?) a policy that internal undocumented APIs were fair game for use by third-party libraries, subclassing, etc., so long as they didn't start with an underscore. (But "private" underscore APIs could have breaking changes at any time.) Am I remembering that wrong? Or was internal API stability only guaranteed for patch-level releases? *Should go through deprecation process* (in my opinion, sorted roughly by real-world usage) - *BadHeaderError* is mentioned in the docs <https://docs.djangoproject.com/en/5.0/topics/email/#preventing-header-injection> as potentially raised during sending - Exposed in django.core.mail.__all__ - Real-world use: ~2300+ cases in GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*BadHeaderError%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code>, seems to be primarily error handling <https://github.com/python/pythondotorg/blob/2a45f8cbb0254f7f0a62e5aba0e6dd2349686559/events/views.py#L145> - Proposal: deprecate on import. (Modern Python email API raises ValueError for newlines in headers. In our deprecation, we'll need `BadHeaderError = ValueError`—rather than subclassing ValueError—to preserve behavior of existing error handling code.) - Suggested replacement for docs: change `except BadHeaderError` to `except ValueError` - *sanitize_address()* is not documented, but is widely used - Not exposed in django.core.mail (have to import from django.core.mail.message) - Real-world use: ~430 cases in GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*sanitize_address%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code>, often in custom EmailBackend implementations <https://github.com/Blueshoe/django-exchange/blob/fe49ed8f934d147d0435c9669239684ab0af6eaa/django_exchange/backend.py#L69-L70> or for special case handling <https://github.com/zulip/zulip/blob/41b431de70e9718ca60ce3307b392eb04c1e86a9/zerver/lib/send_email.py#L113> that needs knowledge of how django.core.mail handles addresses. - Proposal: deprecate. (Have to keep implementation around anyway as part of other deprecated code.) - Suggested replacement for docs: none (it's an internal, undocumented API). Or we could say it depends on the use case: just skip it if no longer relevant, use something like Python's modern email Address object if you need formatting cleanup, or copy sanitize_address() into your code and adapt for your needs. (Incidentally, it's already pretty common to copy <https://github.com/search?q=symbol%3Asanitize_address+language%3Apython+NOT+path%3Adjango%2Fcore%2Fmail&type=code> and adapt sanitize_address().) - *SafeMIMEText* and *SafeMIMEMultipart* are mentioned in the docs <https://docs.djangoproject.com/en/5.0/topics/email/#the-emailmessage-class:~:text=constructs%20a%20django.core.mail.SafeMIMEText%20object%20(a%20subclass%20of%20Python%E2%80%99s%20MIMEText%20class)%20or%20a%20django.core.mail.SafeMIMEMultipart%20object> as the return type of EmailMessage.message(), but not further documented - Exposed in django.core.mail.__all__ - Real-world use: ~240 cases in GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*SafeMIME%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code>, both for type checking <https://github.com/freelawproject/courtlistener/blob/430747e03e085f6d83c02e2a9ce8546b648bbefa/cl/users/email_handlers.py#L221> and for constructing text or message attachments <https://github.com/openedx/edx-platform/blob/57dd2135a655bc4e6d29e4e90706ac8955f6d9b2/openedx/core/djangoapps/credit/email_utils.py#L100> - Proposal: deprecate (on import, to catch type checking uses) - Suggested replacement for docs: django.mail.EmailMessage.message() will now return an email.message.EmailMessage; to construct text or message attachments, switch to modern email.message.EmailMessage - [Tip for django-stubs: SafeMIMEText, SafeMIMEMultipart, and email.message.EmailMessage are all subclasses of email.message.Message] - *forbid_multi_line_headers()* is not documented, but seems to be an intentional part of the public API for implementing pluggable email backends - Exposed in django.core.mail as part of ticket-10355 <https://code.djangoproject.com/ticket/10355> "add support for email backends," and added to __all__ by Tim Graham via ticket-21302 <https://code.djangoproject.com/ticket/21302> - Real-world use: ~100 cases in GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*forbid_multi_line_headers%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code&p=1>, mostly false positives; at least one real use in openedx/edx-platform <https://github.com/openedx/edx-platform/blob/57dd2135a655bc4e6d29e4e90706ac8955f6d9b2/lms/djangoapps/bulk_email/tasks.py#L409> to construct a from address - Proposal: deprecate. (Have to keep implementation around anyway as part of deprecated SafeMIME*.) - Suggested replacement for docs: modern Python email already detects CR/NL in headers; or use `if '\r' in value or '\n' in value` if your code needs to check it directly *Can remove without deprecation* (We'll have to keep these around as part of the implementation of things that *are* being deprecated, but can move them to a place that would break imports in existing code.) - *MIMEMixin* and *SafeMIMEMessage* are not documented, not exposed in django.core.mail - Used to implement SafeMIMEText and SafeMIMEMultipart - Real-world use: virtually nonexistent - GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*%28MIMEMixin%7CSafeMIMEMessage%29%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code> - Proposal: remove without deprecation - *utf8_charset*, *utf8_charset_qp*, *RFC5322_EMAIL_LINE_LENGTH_LIMIT* are not documented, not exposed in django.core.mail - Used to implement MIMEMixin, SafeMIME*; not exposed in django.core.mail - Real-world use: virtually nonexistent - GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*%28utf8_charset%7CRFC5322_EMAIL_LINE_LENGTH_LIMIT%29%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code> is mainly false positives, one use in third-party library <https://github.com/nekonaq/djangoexpack/blob/6ad39bb305cbac7cafbbc323a9db21830f69b811/djangoexpack/mail/__init__.py#L34> - Proposal: remove without deprecation - *ADDRESS_HEADERS* is not documented, not exposed in django.core.mail - Used to implement forbid_multi_line_headers() - Real-world use: virtually nonexistent - GitHub code search <https://github.com/search?q=%2F%5Efrom%5Cs%2Bdjango%5C.core%5C.mail%28%5C.message%29%3F%5Cs%2Bimport%28.%7C%5Cn%29*ADDRESS_HEADERS%2F+language%3Apython+NOT+path%3Adjango%2Fcore&type=code> is mainly false positives, one use in third-party code <https://github.com/APSL/django-yubin/blob/2dcb33d08a5c8a0001e1e5a6abd0b8d940afa0b6/django_yubin/models.py#L29> - Proposal: remove without deprecation [Real-world GitHub code search numbers are clearly not exact. I've tried to catch wrapped import statements and ignore Django forks and vendored copies, but it's not perfect. The search expressions find false positives (overcount) in comments and obsolete branches, as well as forks of popular libraries. But they miss (undercount) some creative approaches <https://github.com/Tivix/django-common/blob/407d208121011a8425139e541629554114d96c18/django_common/email_backends.py#L29-L30> and any usage outside of a public repo hosted on GitHub.] - Mike -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/95e993a0-4b61-47d8-a365-d63676187f43n%40googlegroups.com.
