[Python-checkins] bpo-40635: Fix getfqdn() docstring and docs (GH-27971)

[miss-islington]

https://github.com/python/cpython/commit/f1e3fc4631da5e6ca1ea047c82bd9b42db9dd9ae
commit: f1e3fc4631da5e6ca1ea047c82bd9b42db9dd9ae
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-08-26T12:55:22-07:00
summary:

bpo-40635: Fix getfqdn() docstring and docs (GH-27971)


Co-authored-by: Łukasz Langa <lukasz at langa.pl>
(cherry picked from commit fdcb675eed47b1f6054fae381af4388b16a6fff4)

Co-authored-by: andrei kulakov <andrei.avk at gmail.com>

files:
M Doc/library/socket.rst
M Lib/socket.py

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 26892c99268ba9..609fbe86b31449 100755
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -795,8 +795,9 @@ The :mod:`socket` module also offers various network-related services:
    it is interpreted as the local host.  To find the fully qualified name, the
    hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
    host, if available.  The first name which includes a period is selected.  In
-   case no fully qualified domain name is available, the hostname as returned by
-   :func:`gethostname` is returned.
+   case no fully qualified domain name is available and *name* was provided,
+   it is returned unchanged.  If *name* was empty or equal to ``'0.0.0.0'``,
+   the hostname from :func:`gethostname` is returned.
 
 
 .. function:: gethostbyname(hostname)
diff --git a/Lib/socket.py b/Lib/socket.py
index cafa573a30c052..46fc49ca3233e0 100755
--- a/Lib/socket.py
+++ b/Lib/socket.py
@@ -781,8 +781,9 @@ def getfqdn(name=''):
     An empty argument is interpreted as meaning the local host.
 
     First the hostname returned by gethostbyaddr() is checked, then
-    possibly existing aliases. In case no FQDN is available, hostname
-    from gethostname() is returned.
+    possibly existing aliases. In case no FQDN is available and `name`
+    was given, it is returned unchanged. If `name` was empty or '0.0.0.0',
+    hostname from gethostname() is returned.
     """
     name = name.strip()
     if not name or name == '0.0.0.0':