gh-157889: minor changes to the implementation of os.readlink.

* Simplified/unified error handling in case reading fds referring to symlinks is not supported.
* Docs: centralized the information on the return type of os.readlink in a single paragraph.
* Docs/comments: rewrite from "MacOS" to "macOS" (lower-case).

Author: OOTS

Doc/library/os.rst

@@ -2799,24 +2799,23 @@ features:
    may be converted to an absolute pathname using
    ``os.path.join(os.path.dirname(path), result)``.
 
-   If the *path* is a string object (directly or indirectly through a
-   :class:`PathLike` interface), the result will also be a string object,
-   and the call may raise a UnicodeDecodeError. If the *path* is a bytes
-   object (direct or indirectly), the result will be a bytes object.
-
    This function can also support :ref:`paths relative to directory descriptors
    <dir_fd>`.
 
-   On Linux, Android and MacOS, *path* can also be a file descriptor referring
-   to a symbolic link. In that case, *dir_fd* must be ``None``, and the return
-   value will be a string.
-   (On Linux and Android, such a file descriptor can be obtained through
-   :func:`os.open` with ``os.RDONLY | os.O_PATH | os.O_NOFOLLOW``.
-   On MacOS, this is possible by calling :func:`os.open` with
+   On Linux, Android and macOS, *path* can also be a file descriptor referring
+   to a symbolic link. In that case, *dir_fd* must be ``None``.
+   (On Linux and Android, such a file descriptor must be obtained through
+   :func:`os.open` with ``os.O_RDONLY | os.O_PATH | os.O_NOFOLLOW``.
+   On macOS, :func:`os.open` must be called with
    ``os.O_RDONLY | os.O_SYMLINK``.)
    On other operating systems, a ``NotImplementedError`` is raised if *path*
    is an integer.
 
+   If the *path* is a string object (directly or indirectly through a
+   :class:`PathLike` interface) or a file descriptor, the result will be a
+   string object, and the call may raise a UnicodeDecodeError. If the *path*
+   is a bytes object (direct or indirectly), the result will be a bytes object.
+
    When trying to resolve a path that may contain links, use
    :func:`~os.path.realpath` to properly handle recursion and platform
    differences.
@@ -2839,9 +2838,9 @@ features:
       substitution path (which typically includes ``\\?\`` prefix) rather
       than the optional "print name" field that was previously returned.
 
-   .. versionchanged:: 3.16
+   .. versionchanged:: next
       Accepts file descriptors pointing to symbolic links as *path* on
-      Linux, Android and MacOS.
+      Linux, Android and macOS.
 
 .. function:: remove(path, *, dir_fd=None)
 

Doc/whatsnew/3.16.rst

@@ -510,7 +510,7 @@ os
   (Contributed by Md Arif in :gh:`152936`.)
 
 * :func:`os.readlink` now accepts a file descriptor referring to a symlink on
-  Linux, Android and MacOS.
+  Linux, Android and macOS.
   (Contributed by OOTS in :gh:`157899`.)
 
 

Lib/test/test_os/test_posix.py

@@ -1883,7 +1883,7 @@ def test_readlink_dir_fd(self):
 
 
     _support_readlink_with_fd = hasattr(os, 'readlink') and (
-        "HAVE_FREADLINK" in posix._have_functions  # MacOS
+        "HAVE_FREADLINK" in posix._have_functions  # macOS
         or (
             os.readlink in os.supports_dir_fd
             and sys.platform in ["linux", "android"]
@@ -1892,7 +1892,7 @@ def test_readlink_dir_fd(self):
 
     def _open_symlink_as_fd(self, path):
         open_flags = os.O_RDONLY
-        if hasattr(os, "O_SYMLINK"):  # MacOS
+        if hasattr(os, "O_SYMLINK"):  # macOS
             open_flags |= os.O_SYMLINK
         elif hasattr(os, "O_NOFOLLOW") and hasattr(os, "O_PATH"):  # Linux
             open_flags |= os.O_NOFOLLOW | os.O_PATH
@@ -1918,7 +1918,7 @@ def test_readlink_with_fd_not_referring_to_symlink_throws(self):
             self.addCleanup(os.close, fd)
             # on Linux/Android, readlinkat("", fd, ...) fails with ENOENT, which
             # Python translates to a FileNotFoundError, a subclass of OSError.
-            # On MacOS, freadlink(fd, ...) fails with EINVAL, which gets raised
+            # On macOS, freadlink(fd, ...) fails with EINVAL, which gets raised
             # as a OSError.
             # So catching OSError here covers both cases.
             with self.assertRaises(OSError):
@@ -2698,8 +2698,8 @@ def test_freadlink(self):
 
         else:
             self.assertNotIn("HAVE_FREADLINK", posix._have_functions)
-
-            with self.assertRaisesRegex(NotImplementedError, "readlink cannot read file descriptors on this platform"):
+            errmsg = "readlink cannot read file descriptors on this platform"
+            with self.assertRaisesRegex(NotImplementedError, errmsg):
                 os.readlink(0)
 
     def test_symlink(self):

Misc/NEWS.d/next/Library/2026-09-21-14-41-07.gh-issue-157899.s6vBQC.rst

@@ -1,2 +1,2 @@
 :func:`os.readlink` now accepts a file descriptor referring to a
-symlink on Linux, Android and MacOS.
+symlink on Linux, Android and macOS.

Modules/clinic/posixmodule.c.h

@@ -11016,22 +11016,22 @@ that directory.
 dir_fd may not be implemented on your platform.  If it is unavailable,
 using it will raise a NotImplementedError.
 
-On Linux, Android and MacOS, path may be a file descriptor referring to
+On Linux, Android and macOS, path may be a file descriptor referring to
 a symlink. If it is, dir_fd must be None, and the return value will be a
 string object. (File descriptors for symlinks can be obtained with
 
     os.open(..., os.O_RDONLY | os.O_PATH | os.O_NOFOLLOW)
 
-on Linux and Android, and
+on Linux and Android, and:
 
     os.open(..., os.O_RDONLY | os.O_SYMLINK)
 
-on MacOS.)
+on macOS.)
 [clinic start generated code]*/
 
 static PyObject *
 os_readlink_impl(PyObject *module, path_t *path, int dir_fd)
-/*[clinic end generated code: output=d21b732a2e814030 input=eda43153b2f38ee6]*/
+/*[clinic end generated code: output=d21b732a2e814030 input=14546747b3db62f6]*/
 {
 #if defined(HAVE_READLINK)
     char buffer[MAXPATHLEN+1];
@@ -11047,33 +11047,21 @@ os_readlink_impl(PyObject *module, path_t *path, int dir_fd)
             Py_BEGIN_ALLOW_THREADS
             length = freadlink(path->fd, buffer, MAXPATHLEN);
             Py_END_ALLOW_THREADS
-        } else {
-            PyErr_SetString(PyExc_NotImplementedError,
-                "readlink cannot read file descriptors on this platform, "
-                "freadlink() is unavailable");
-            return NULL;
-        }
+        } else
 #elif defined(HAVE_READLINKAT) && defined(_Py_READLINKAT_SUPPORTS_EMPTY_PATH)
         // linux/android:
         // readlinkat(fd, "", ...) reads the link that fd refers to.
         if (HAVE_READLINKAT_RUNTIME) {
             Py_BEGIN_ALLOW_THREADS
             length = readlinkat(path->fd, "", buffer, MAXPATHLEN);
             Py_END_ALLOW_THREADS
-        } else {
-            // this should be unreachable:
-            // HAVE_READLINKAT_RUNTIME is always 1 on Linux/Android.
-            // Leaving it here as a safeguard.
+        } else
+#endif
+        {
             PyErr_SetString(PyExc_NotImplementedError,
-                "readlink cannot read file descriptors on this platform, "
-                "readlinkat() is unavailable");
+                "readlink cannot read file descriptors on this platform");
             return NULL;
         }
-#else
-        PyErr_SetString(PyExc_NotImplementedError,
-            "readlink cannot read file descriptors on this platform");
-        return NULL;
-#endif
     } else
 #ifdef HAVE_READLINKAT
     if (dir_fd != DEFAULT_DIR_FD) {