Feedback on Django Email API Changes Proposal

Your proposal to modify Django's email APIs to enforce keyword-only arguments for less common parameters is well-reasoned and aligns with modern Python practices. Here's my analysis of your proposal:

Benefits of the Proposed Change

1. Future-proofing: Making parameters after the common ones keyword-only would allow Django to reorder or add parameters in the future without breaking existing code.

2. Code clarity: Enforcing keyword arguments for optional parameters improves readability, especially for functions with many parameters like send_mail().

3. Consistency with modern Python: This approach follows Python 3's support for keyword-only arguments, which has become a best practice for complex function signatures.

Implementation Considerations

1. Deprecation path: Your mention of a deprecation period is crucial. Django has a strong commitment to backward compatibility, so a proper deprecation warning should be issued in at least one release before enforcing the change.

2. Documentation updates: The change would need clear documentation in both the function signatures and release notes.

3. Impact assessment: While you mentioned most code already uses keywords for parameters after the first four, it would be good to analyze popular Django packages to estimate the potential impact.

Specific API Changes

Your proposed changes to send_mail() look appropriate:

PYTHONCopied
def send_mail(
    subject, message, from_email, recipient_list,
    *,  # keyword-only arguments below
    fail_silently=False, auth_user=None, auth_password=None,
    connection=None, html_message=None):

The same approach for EmailMessage constructor makes sense, keeping the first four parameters as positional-or-keyword and making the rest keyword-only.

Historical Context

This change follows Django's evolution toward more object-oriented email handling. As noted in the documentation, send_mail() and related functions were originally the only interface, but the growing parameter list led to the more flexible EmailMessage class. Your proposal continues this evolution by improving the API design.

Conclusion

The proposal is sound and follows good API design principles. It maintains backward compatibility through a deprecation period while setting up Django's email system for more flexible future development. The change would be particularly valuable given the recent work on multiple email providers, which is adding complexity to the API.