gh-60856: Be explicit about localhost for socket.getfqdn #93451
Conversation
|
Noticed there's duplicate wording in the last sentence, will change the PR for that |
Doc/library/socket.rst
Outdated
| Return a fully qualified domain name for *name*. If *name* is omitted or empty, | ||
| it is interpreted as the local host. To find the fully qualified name, the | ||
| Return a fully qualified domain name for *name*. If *name* is empty or equal to | ||
| ``'0.0.0.0'``, the hostname from :func:`gethostname` is returned. |
There was a problem hiding this comment.
Is it so? Looking at the sources, it tries to return one of names returned by gethostbyaddr(gethostname()).
The new wording also leaves unclear what getfqdn() returns.
There was a problem hiding this comment.
The source/behavior was changed in #100375 after this PR was opened, so wording definitely does need updating.
Regarding the unclear new wording, could you expand on that? My interpretation is that previously the entire paragraph needs to be read through before the return of getfqdn(), but now it's right at the top: If *name* is empty ...
There was a problem hiding this comment.
Now it starts from the rare corner case (why would anyone pass an empty name to getfqdn()?), but the documentation for getfqdn() without arguments is removed.
There was a problem hiding this comment.
You are very correct, leaving out the empty argument is my mistake. What do you think about this instead?
Return a fully qualified domain name for *name*.
To find the fully qualified name, ...
...
... it is returned unchanged.
If *name* is empty, or equal to "0.0.0.0," "::", or "",
the hostname from :func:`gethostname` is returned.
There's also an option of changing getfqdn([name]) to getfqdn(name=''), but not sure if it helps with improving the wording much.
There was a problem hiding this comment.
I think that both changing the wording and changing the signature are worth to do.
There was a problem hiding this comment.
Done, let me know if there's anything that looks off. For reference, here's the preview of getfqdn.
| *backlog* is the queue size passed to :meth:`socket.listen`; if not specified | ||
| , a default reasonable value is chosen. | ||
| *backlog* is the queue size passed to :meth:`socket.listen`; if not | ||
| specified, a default reasonable value is chosen. |
There was a problem hiding this comment.
Small formatting fix to remove space before comma for this:
#60856
This moves the wording from #27971 to the front to reduce the duplicated wording
https://docs.python.org/3/library/socket.html#socket.getfqdn
https://github.com/python/cpython/blob/main/Lib/socket.py#L792