logging.handlers.SMTPHandler: secure argument is broken in Python 3.12+

[s-hamann]

Bug report

Bug description:

The documentation for logging.handlers.SMTPHandler describes the secure argument as follows:

To specify the use of a secure protocol (TLS), pass in a tuple to the secure argument. This will only be used when authentication credentials are supplied. The tuple should be either an empty tuple, or a single-value tuple with the name of a keyfile, or a 2-value tuple with the names of the keyfile and certificate file. (This tuple is passed to the smtplib.SMTP.starttls() method.)

However, from Python 3.12 on, only the empty tuple actually works.
With a single-value-tuple or a two-value-tuple, smtplib.SMTP.starttls() throws an exception like this:

Traceback (most recent call last):
  File "/usr/lib/python3.13/logging/handlers.py", line 1097, in emit
    smtp.starttls(*self.secure)
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^
TypeError: SMTP.starttls() takes 1 positional argument but 3 were given

The reason seems immediately obvious from the last sentence in the description of the secure argument: The tuple is passed to smtplib.SMTP.starttls().
The documentation for this method states:

Changed in version 3.12: The deprecated keyfile and certfile parameters have been removed.

SMTPHandler still relies on the these parameters.

Here's a minimal script to reproduce the error (requires a mocked SMTP server on port 1025):

#!/usr/bin/env python3

import logging
from logging.handlers import SMTPHandler

logger = logging.getLogger()
handler = SMTPHandler(
    mailhost=("localhost", 1025),
    fromaddr="foo@localhost",
    toaddrs="bar@localhost",
    subject="Test",
    credentials=("foo", "bar"),
    secure=(
        "/path/to/private.key",
        "/path/to/cert.pem"
    ),
)
logger.addHandler(handler)
logger.error("SMTPHandler is broken")

Note that Python 3.11 is not affected and the above code successfully attempts to issue a STARTTLS command.

CPython versions tested on:

3.11, 3.12, 3.13

Operating systems tested on:

Linux

Linked PRs

• gh-127712: Fix secure argument of logging.handlers.SMTPHandler #127726
• [3.13] gh-127712: Fix secure argument of logging.handlers.SMTPHandler (GH-127726) #129955
• [3.12] gh-127712: Fix secure argument of logging.handlers.SMTPHandler (GH-127726) #129956