Skip to content

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

Closed
@s-hamann

Description

@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

Metadata

Metadata

Assignees

No one assigned

    Labels

    3.12only security fixes3.13bugs and security fixes3.14bugs and security fixesstdlibPython modules in the Lib dirtype-bugAn unexpected behavior, bug, or error

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions