gh-56915: Fix documented timeout default in ftplib

[Monstertov]

the FTP.connect docs and the FTP class docstring both describe the wrong default for timeout:

• FTP.connect uses a private sentinel. omitting timeout preserves the instance's timeout, initially set by the constructor.
• FTP defaults to socket._GLOBAL_DEFAULT_TIMEOUT, so sockets use the global default timeout. passing None explicitly disables the timeout.

this fixes the FTP.connect default text and the FTP class docstring. the timeout=None signatures in the docs are left as is for now, see the discussion above.

docs and docstring only, no behaviour change, so i think this can skip news.

quick check of the socket timeout after a successful connection:

socket.setdefaulttimeout(7.0)
FTP().connect(host, port)              # sock.gettimeout() -> 7.0
FTP(timeout=None).connect(host, port)  # sock.gettimeout() -> None
FTP(timeout=3).connect(host, port)     # sock.gettimeout() -> 3.0

• Issue: timeout sentinel in ftplib and poplib documentation #56915

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34950506 | 📁 Comparing c291531 against main (1a85213)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• c-api/exceptions.html
• c-api/interp-lifecycle.html
• c-api/sys.html
• c-api/unicode.html
• library/ctypes.html
• library/ftplib.html
• using/configure.html
• whatsnew/3.15.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[bitdancer]

The [, timeout] style is, as far as I can tell, old. It probably predates _GLOBAL_DEFAULT_TIMEOUT. I think using it is incorrect: the arguments are keyword arguments with values, not optional positional arguments or required keywords.

What I recommend here is to revisit #91225 in light of the introduction of sentinel support in Python. That doesn't fix the inconsistency in the docs for the maintenance versions, but I don't think the change suggested in this PR is the correct approach to fixing that. Any suggestion for a doc-only fix should also be applied to those other arguably incorrect (and I believe legacy) uses of [ timeout,].

[Monstertov]

thanks, agreed. [, timeout] is wrong here, especially after * in FTP_TLS and POP3_SSL.

as i see it, two options:

1. docs-only, backportable: use timeout=GLOBAL_DEFAULT like socket.create_connection does, and apply it everywhere [, timeout] is used now (smtplib, http.client, urllib.request, poplib).
2. main only: make _GLOBAL_DEFAULT_TIMEOUT a real sentinel (socket._GLOBAL_DEFAULT_TIMEOUT being an object() makes for ugly docstrings, can be better #91225), and give FTP.connect its own sentinel instead of -999.

the FTP.connect default text and the class docstring are wrong either way. should i keep only those here and drop the signature changes, then follow up with whichever option you prefer?

[bitdancer]

I think timeout=GLOBAL_DEFAULT is also misleading since GLOBAL_DEFAULT doesn't exist in any namespace.

So let's go with the non-signature fixes only here, and fix the signatures after adding the sentinels..

[Monstertov]

@bitdancer done. dropped the signature changes and kept only the non-signature fixes: the FTP.connect default text and the FTP class docstring. the [, timeout] edits are reverted to timeout=None as on main.

i'll do the signatures in a follow-up after the sentinels land (#91225).

[Monstertov]

the MSan failure (test_os.test_posix.test_fexecve) is unrelated to this change, it's the same failure as gh-158868.