gh-137339: Clarify host and port parameter behavior in smtplib.SMTP_SSL initialization

[Aniketsy]

(GH #137339)
This PR updates the documentation for the smtplib.SMTP_SSL class to explicitly clarify the behavior of the host and port parameters during initialization.
Specifically, it now states that if host is omitted or an empty string, no connection is made during initialization and connect() must be called manually. It also clarifies that if port is zero,

Please let me know if this fix needs any improvements . I’m open to feedback and happy to make changes based on suggestions.
Thankyou!

---

📚 Documentation preview 📚: https://cpython-previews--137340.org.readthedocs.build/

• Issue: Clarify host and port Parameter Behavior in smtplib.SMTP and SMTP_SSL Initialization #137339

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[picnixz]

I don't think this requires a change as we already mention what happens when the optional parameters are given. If you want to rephrase it, you should remove the "if the optional parameters are given then [...¨]" as it makes the paragraph more confusing IMO.

[picnixz]

This is not always the case that the default SMTP port is 25. It depends on the default_port attribute. Also, this now contradicts the last sentence:

If omitted (or if host or port are '' and/or 0
respectively) the OS default behavior will be used.

We should also make more paragraphs. This description is too compact for the reader.

[Aniketsy]

If port is zero, the value of the instance's default_port attribute will be used.

I'd appreciate any insights or suggestions to expand our descriptions so that its not too compact for reader

[picnixz]

This is already hinted in the previous sentence and this would somehow conflict with the last sentence IMO.

If the optional host and port parameters are given, the SMTP :meth:connect method is called with those parameters during initialization

[Aniketsy]

Thankyou for the feedback !
I will remove this "if the optional parameters are given then [...¨]" as it makes the paragraph more confusing.

[StanFromIreland]

My comment from the issue:

As for this one,

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.

I think we can simplify by stating that host is not optional. connect is linked and there you can find further details on behaviour, duplicate docs will simply create problems down the line.

The host and optional port arguments are passed to connect during initialization.

[picnixz]

I think we can simplify by stating that host is not optional

It is optional though?

The host and optional port arguments are passed to connect during initialization.

This is incorrect. connect() is only called in __init__ if the host is truthy. It's never called otherwise.

[Aniketsy]

@picnixz
I have removed the contradiction part as per your suggestions. I would also love to work on this part (We should also make more paragraphs. This description is too compact for the reader) .
Thankyou !