Re: Proposal to upgrade django.core.mail to Python's modern email API

[Othniel Davidson]

Thank you for the update

On Sat, Jul 20, 2024 at 15:26 Pankaj Kumar  wrote:

> Hi Sir,
>I hope this message finds you well.
>
> I am writing to inform you that we have reviewed and decided to accept the
> proposal to upgrade django.core.mail to Python's modern email API. We
> believe that this upgrade will bring significant improvements to our
> system's performance and maintainability.
>
> I would also like to extend my sincere apologies for the delay in our
> response. I received the proposal seven days ago, and I regret not being
> able to get back to you sooner. Thank you for your patience and
> understanding in this matter.
>
> We are looking forward to the successful implementation of this upgrade
> and are excited about the enhancements it will bring to our project. Please
> let us know the next steps and how we can assist in the process.
>
> Thank you once again for your proposal and for your continued support.
>
> Best regards,
>
> - PANKAJ NEEMA
>
>
>
> On Sat, 6 Jul 2024 at 04:00, Mike Edmunds  wrote:
>
>> 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
>>
>> 
>>  as
>>potentially raised during sending
>>   - Exposed in django.core.mail.__all__
>>   - Real-world use: ~2300+ cases in GitHub code search
>>   
>> ,
>>   seems to be primarily error handling
>>   
>> 
>>   - 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
>>   
>> ,
>>   often in custom EmailBackend implementations
>>   
>> 
>>  or
>>   for special case handling
>>   
>> 
>>  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
>>   
>> 
>>   and adapt sanitize_address().)
>>
>>   - *SafeMIMEText* and *SafeMIMEMultipart* are mentioned in the docs
>>
>> 
>>as the return type of EmailMessage.message(), but not further documented
>>   - Exposed in django.core.mail.__all__
>>

Re: Proposal to upgrade django.core.mail to Python's modern email API

['Adam Johnson' via Django developers (Contributions to Django itself)]

I wish this discussion was on the forum so I could mark Pankaj’s response as 
spam 😅

On Sun, 21 Jul 2024, at 08:26, Othniel Davidson wrote:
> Thank you for the update 
> 
> On Sat, Jul 20, 2024 at 15:26 Pankaj Kumar  wrote:
>> Hi Sir,
>>I hope this message finds you well.
>> I am writing to inform you that we have reviewed and decided to accept the 
>> proposal to upgrade `django.core.mail` to Python's modern email API. We 
>> believe that this upgrade will bring significant improvements to our 
>> system's performance and maintainability.
>> 
>> I would also like to extend my sincere apologies for the delay in our 
>> response. I received the proposal seven days ago, and I regret not being 
>> able to get back to you sooner. Thank you for your patience and 
>> understanding in this matter.
>> 
>> We are looking forward to the successful implementation of this upgrade and 
>> are excited about the enhancements it will bring to our project. Please let 
>> us know the next steps and how we can assist in the process.
>> 
>> Thank you once again for your proposal and for your continued support.
>> 
>> Best regards,
>> 
>> - PANKAJ NEEMA
>> 
>> 
>> 
>> 
>> On Sat, 6 Jul 2024 at 04:00, Mike Edmunds  wrote:
>>> 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 
>>> 
>>>  as potentially raised during sending
>>>• Exposed in django.core.mail.__all__
>>>• Real-world use: ~2300+ cases in GitHub code search 
>>> ,
>>>  seems to be primarily error handling 
>>> 
>>>• 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 
>>> ,
>>>  often in custom EmailBackend implementations 
>>> 
>>>  or for special case handling 
>>> 
>>>  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 
>>> 
>>>  and adapt sanitize_address().)
>>>  • *SafeMIMEText* and *SafeMIMEMultipart* are mentioned in the docs 
>>> 
>>>  as the return type of EmailMessage.message(), but not further documented
>>>• Expo