Update SMTP example to use smtp.gmail.com so ping actually works

[ab12gu]

No description provided.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[sepehr-rs]

Hi, thanks for your contribution!

I think domain.org was likely intentional as a placeholder hostname. Using smtp.gmail.com would make the example depend on an external third-party service, while this example seems mainly intended to demonstrate the API usage.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32645674 | 📁 Comparing e982900 against main (54a5fd4)

  🔍 Preview build  

2 files changed

± library/pickle.html
± library/smtplib.html

[bitdancer]

I believe that is correct. We could change it to example.com to make that clearer. (I don't know why you want it to be pingable, but FWIW example.com is.)

[ab12gu]

@bitdancer yeah example is better, but if you ping it via smtplib, you still get an error.

I guess my issue was that I had to reference an old python textbook to know that the subdomain smtp was needed to access the smtp of the website.

This is pretty much standard for using smtp , but wasn't apparent to me... and the docs don't talk about that either...

So even with using example.com you can ping it with an error response due to it not being smtp and doesn't have a supporting smtp subdomain...

So I understand @sepehr-rs 3rd party issue, but sometimes its difficult to know these nuances and would prefer a working ping example :).

[sepehr-rs]

So I understand @sepehr-rs 3rd party issue, but sometimes its difficult to know these nuances and would prefer a working ping example :).

Fair point. I think the confusion comes from the example not making it obvious that domain.org is not meant to be a real SMTP server. Maybe a short note in the docs explaining that users must replace it with an actual SMTP hostname could help.

Though maintainers would probably be better positioned to weigh in on whether that approach fits the documentation style here.

[ByteFlowing1337]

Maybe changing it to smtp.domain.org or smtp.example.com is better for clarity that it should be an SMTP server; although they are still not pingable, but it does not rely on a 3rd party service. What's more, at some countries, smtp.gmail.com is actually still not pingable.

[bitdancer]

'smtp' being in the name has nothing to do with whether or not smtplib will be able to connect to it. What matters if whether or not an smtp server is listening on the smtp port of the IP that the name resolves to, regardless of what the name itself is.

Looking at the rest of the doc, there is another more complete example later, and it uses localhost. i think it would be better to change this example to use localhost as well. That makes it clear that if you want the example to run there has to be an SMTP server listening on localhost. If that doesn't make it clear to the reader, the reader will of necessity look elsewhere for help. I'm afraid it isn't appropriate for the python docs to try teach the details of how internet protocols work; even the socket module docs don't do that.

This seems particularly appropriate in that in general one should not do testing like this against a server that someone else controls. Get your software working locally first, then test it against real servers ;)

Hmm. It occurs to me, though, that it wouldn't be crazy to have a link to https://aiosmtpd.aio-libs.org as a way to run a test smtp server on localhost. That should serve as a pretty big clue ;) Maybe put it in a footnote and reference it from both examples? Note that the examples were written back when the stdlib included an 'smtpd' module, which may be why they assume you know how to run an smtp server on localhost...