gh-117705: Add follow_symlinks to os.path.exists()

Doc/library/os.path.rst

@@ -127,10 +127,11 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: exists(path)
+.. function:: exists(path, *, follow_symlinks=True)
 
    Return ``True`` if *path* refers to an existing path or an open
-   file descriptor.  Returns ``False`` for broken symbolic links.  On
+   file descriptor.  Returns ``False`` for broken symbolic links if
+   *follow_symlinks* is set, otherwise ``True``.  On
    some platforms, this function may return ``False`` if permission is
    not granted to execute :func:`os.stat` on the requested file, even
    if the *path* physically exists.
@@ -142,6 +143,8 @@ the :mod:`glob` module.)
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: 3.13
+      Added the *follow_symlinks* parameter.
 
 .. function:: lexists(path)
 

Lib/genericpath.py

@@ -13,10 +13,11 @@
 
 # Does a path exist?
 # This is false for dangling symbolic links on systems that support them.
-def exists(path):
-    """Test whether a path exists.  Returns False for broken symbolic links"""
+def exists(path, *, follow_symlinks=True):
+    """Test whether a path exists.  Returns False for broken symbolic links
+    if follow_symlinks is set, otherwise True"""
     try:
-        os.stat(path)
+        os.stat(path, follow_symlinks=follow_symlinks)
     except (OSError, ValueError):
         return False
     return True

Lib/ntpath.py

@@ -899,6 +899,7 @@ def commonpath(paths):
     from nt import _path_isfile as isfile
     from nt import _path_islink as islink
     from nt import _path_exists as exists
+    from nt import _path_lexists as lexists
 except ImportError:
     # Use genericpath.* as imported above
     pass

Lib/test/test_genericpath.py

@@ -128,31 +128,42 @@ def test_filetime(self):
         )
 
     def test_exists(self):
+        def check_exists(filename, expected):
+            bfilename = os.fsencode(filename)
+            self.assertIs(self.pathmodule.exists(filename), expected)
+            self.assertIs(self.pathmodule.exists(bfilename), expected)
+            self.assertIs(self.pathmodule.exists(filename, follow_symlinks=True),
+                          expected)
+            self.assertIs(self.pathmodule.exists(bfilename, follow_symlinks=True),
+                          expected)
+
+        def check_lexists(filename, expected):
+            bfilename = os.fsencode(filename)
+            self.assertIs(self.pathmodule.lexists(filename), expected)
+            self.assertIs(self.pathmodule.lexists(bfilename), expected)
+            self.assertIs(self.pathmodule.exists(filename, follow_symlinks=False),
+                          expected)
+            self.assertIs(self.pathmodule.exists(bfilename, follow_symlinks=False),
+                          expected)
+
         filename = os_helper.TESTFN
         bfilename = os.fsencode(filename)
         self.addCleanup(os_helper.unlink, filename)
 
-        self.assertIs(self.pathmodule.exists(filename), False)
-        self.assertIs(self.pathmodule.exists(bfilename), False)
+        check_exists(filename, False)
+        check_lexists(filename, False)
 
         create_file(filename)
 
-        self.assertIs(self.pathmodule.exists(filename), True)
-        self.assertIs(self.pathmodule.exists(bfilename), True)
-
+        check_exists(filename, True)
         self.assertIs(self.pathmodule.exists(filename + '\udfff'), False)
         self.assertIs(self.pathmodule.exists(bfilename + b'\xff'), False)
-        self.assertIs(self.pathmodule.exists(filename + '\x00'), False)
-        self.assertIs(self.pathmodule.exists(bfilename + b'\x00'), False)
-
-        if self.pathmodule is not genericpath:
-            self.assertIs(self.pathmodule.lexists(filename), True)
-            self.assertIs(self.pathmodule.lexists(bfilename), True)
+        check_exists(filename + '\x00', False)
 
-            self.assertIs(self.pathmodule.lexists(filename + '\udfff'), False)
-            self.assertIs(self.pathmodule.lexists(bfilename + b'\xff'), False)
-            self.assertIs(self.pathmodule.lexists(filename + '\x00'), False)
-            self.assertIs(self.pathmodule.lexists(bfilename + b'\x00'), False)
+        check_lexists(filename, True)
+        self.assertIs(self.pathmodule.lexists(filename + '\udfff'), False)
+        self.assertIs(self.pathmodule.lexists(bfilename + b'\xff'), False)
+        check_lexists(filename + '\x00', False)
 
     @unittest.skipUnless(hasattr(os, "pipe"), "requires os.pipe()")
     @unittest.skipIf(is_emscripten, "Emscripten pipe fds have no stat")

Lib/test/test_ntpath.py

@@ -1115,6 +1115,8 @@ def test_fast_paths_in_use(self):
         self.assertFalse(inspect.isfunction(os.path.islink))
         self.assertTrue(os.path.exists is nt._path_exists)
         self.assertFalse(inspect.isfunction(os.path.exists))
+        self.assertTrue(os.path.lexists is nt._path_lexists)
+        self.assertFalse(inspect.isfunction(os.path.lexists))
 
     @unittest.skipIf(os.name != 'nt', "Dev Drives only exist on Win32")
     def test_isdevdrive(self):

Misc/NEWS.d/next/Core and Builtins/2024-04-10-20-41-15.gh-issue-117705.2pDs7H.rst

@@ -0,0 +1 @@
+Added the *follow_symlinks* parameter to :func:`os.path.exists`.