Clarify host and port Parameter Behavior in smtplib.SMTP and SMTP_SSL Initialization #137339
Description
The description of the smtplib.SMTP and smtplib.SMTP_SSL classes should explicitly clarify the behavior when the host and port parameters are omitted.
This clarification is necessary to prevent a common misunderstanding. Since the class __init__ method checks whether host is a non-empty string before automatically calling connect(), explicitly stating that no connection occurs if host is omitted will help developers avoid unexpected behavior and write correct code from the start.
1. For smtplib.SMTP
https://docs.python.org/3/library/smtplib.html#smtplib.SMTP
Current:
class smtplib.SMTP(host='', port=0, ...)
... If the optional host and port parameters are given, the SMTP connect() method is called with those parameters during initialization. ...
Proposed:
class smtplib.SMTP(host='', port=0, ...)
... If the optional host and port parameters are given, connect() is called with those parameters during initialization. If host is omitted or empty, no connection is made; connect() must be called manually. If port is zero, the default SMTP port (25) is used. ...
2. For smtplib.SMTP_SSL
https://docs.python.org/3.15/library/smtplib.html#smtplib.SMTP_SSL
Current:
class smtplib.SMTP_SSL(host='', port=0, ...)
... If host is not specified, the local host is used. If port is zero, the standard SMTP-over-SSL port (465) is used. ...
Proposed:
class smtplib.SMTP_SSL(host='', port=0, ...)
... If the optional host and port parameters are given, connect() is called with those parameters during initialization. If host is omitted or empty, no connection is made; connect() must be called manually. If port is zero, the standard SMTP-over-SSL port (465) is used. ...