gh-88569: add ntpath.isreserved()

Doc/library/os.path.rst

@@ -295,6 +295,15 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
+.. function:: isreserved(path)
+
+   Return ``True`` if *path* is a reserved pathname on the current system. On
+   Windows, reserved names include "NUL", "AUX" and "CON". On other platforms,
+   this function always returns ``False``.
+
+   .. versionadded:: 3.12
+
+
 .. function:: join(path, *paths)
 
    Join one or more path components intelligently.  The return value is the

Doc/library/pathlib.rst

@@ -1392,6 +1392,7 @@ Below is a table mapping various :mod:`os` functions to their corresponding
                                        :meth:`Path.owner`,
                                        :meth:`Path.group`
 :func:`os.path.isabs`                  :meth:`PurePath.is_absolute`
+:func:`os.path.isreserved`             :meth:`PurePath.is_reserved`
 :func:`os.path.join`                   :func:`PurePath.joinpath`
 :func:`os.path.basename`               :data:`PurePath.name`
 :func:`os.path.dirname`                :data:`PurePath.parent`

Lib/ntpath.py

@@ -27,8 +27,8 @@
 __all__ = ["normcase","isabs","join","splitdrive","split","splitext",
            "basename","dirname","commonprefix","getsize","getmtime",
            "getatime","getctime", "islink","exists","lexists","isdir","isfile",
-           "ismount", "expanduser","expandvars","normpath","abspath",
-           "curdir","pardir","sep","pathsep","defpath","altsep",
+           "ismount","isreserved","expanduser","expandvars","normpath",
+           "abspath","curdir","pardir","sep","pathsep","defpath","altsep",
            "extsep","devnull","realpath","supports_unicode_filenames","relpath",
            "samefile", "sameopenfile", "samestat", "commonpath"]
 
@@ -311,6 +311,28 @@ def ismount(path):
         return False
 
 
+_reserved_names = frozenset(
+    {'CON', 'PRN', 'AUX', 'NUL', 'CONIN$', 'CONOUT$'} |
+    {f'COM{c}' for c in '123456789\xb9\xb2\xb3'} |
+    {f'LPT{c}' for c in '123456789\xb9\xb2\xb3'}
+)
+def isreserved(path):
+    """Return true if the pathname is reserved by the system."""
+    # Refer to "Naming Files, Paths, and Namespaces":
+    # https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file
+    path = os.fspath(path)
+    name = os.fsdecode(basename(path))
+    # Trailing spaces and dots are reserved.
+    # File streams are reserved (e.g. "filename:stream[:type]").
+    if name.rstrip('. ') != name or ':' in name:
+        return True
+    # DOS device names are reserved (e.g. "nul" or "nul .txt"). The rules
+    # are complicated and vary across Windows versions (e.g. "../nul" is
+    # reserved but not "foo/nul" if "foo" does not exist). On the side of
+    # caution, return True for names that may not be reserved.
+    return name.partition('.')[0].rstrip(' ').upper() in _reserved_names
+
+
 # Expand paths beginning with '~' or '~user'.
 # '~' means $HOME; '~user' means that user's home directory.
 # If the path doesn't begin with '~', or if the user or $HOME is unknown,

Lib/pathlib.py

@@ -127,12 +127,6 @@ class _WindowsFlavour(_Flavour):
 
     is_supported = (os.name == 'nt')
 
-    reserved_names = (
-        {'CON', 'PRN', 'AUX', 'NUL', 'CONIN$', 'CONOUT$'} |
-        {'COM%s' % c for c in '123456789\xb9\xb2\xb3'} |
-        {'LPT%s' % c for c in '123456789\xb9\xb2\xb3'}
-        )
-
     def splitroot(self, part, sep=sep):
         drv, rest = self.pathmod.splitdrive(part)
         if drv[:1] == sep or rest[:1] == sep:
@@ -149,19 +143,6 @@ def casefold_parts(self, parts):
     def compile_pattern(self, pattern):
         return re.compile(fnmatch.translate(pattern), re.IGNORECASE).fullmatch
 
-    def is_reserved(self, parts):
-        # NOTE: the rules for reserved names seem somewhat complicated
-        # (e.g. r"..\NUL" is reserved but not r"foo\NUL" if "foo" does not
-        # exist). We err on the side of caution and return True for paths
-        # which are not considered reserved by Windows.
-        if not parts:
-            return False
-        if parts[0].startswith('\\\\'):
-            # UNC paths are never reserved
-            return False
-        name = parts[-1].partition('.')[0].partition(':')[0].rstrip(' ')
-        return name.upper() in self.reserved_names
-
     def make_uri(self, path):
         # Under Windows, file URIs use the UTF-8 encoding.
         drive = path.drive
@@ -207,9 +188,6 @@ def casefold_parts(self, parts):
     def compile_pattern(self, pattern):
         return re.compile(fnmatch.translate(pattern)).fullmatch
 
-    def is_reserved(self, parts):
-        return False
-
     def make_uri(self, path):
         # We represent the path using the local filesystem encoding,
         # for portability to other applications.
@@ -750,7 +728,7 @@ def is_absolute(self):
     def is_reserved(self):
         """Return True if the path contains one of the special names reserved
         by the system, if any."""
-        return self._flavour.is_reserved(self._parts)
+        return self._flavour.pathmod.isreserved(self)
 
     def match(self, path_pattern):
         """

Lib/posixpath.py

@@ -31,8 +31,8 @@
 __all__ = ["normcase","isabs","join","splitdrive","split","splitext",
            "basename","dirname","commonprefix","getsize","getmtime",
            "getatime","getctime","islink","exists","lexists","isdir","isfile",
-           "ismount", "expanduser","expandvars","normpath","abspath",
-           "samefile","sameopenfile","samestat",
+           "ismount","isreserved","expanduser","expandvars","normpath",
+           "abspath","samefile","sameopenfile","samestat",
            "curdir","pardir","sep","pathsep","defpath","altsep","extsep",
            "devnull","realpath","supports_unicode_filenames","relpath",
            "commonpath"]
@@ -216,6 +216,12 @@ def ismount(path):
     return False
 
 
+def isreserved(path):
+    """Return true if the pathname is reserved by the system."""
+    os.fspath(path)
+    return False
+
+
 # Expand paths beginning with '~' or '~user'.
 # '~' means $HOME; '~user' means that user's home directory.
 # If the path doesn't begin with '~', or if the user or $HOME is unknown,

Lib/test/test_ntpath.py

@@ -822,6 +822,49 @@ def test_ismount(self):
             self.assertTrue(ntpath.ismount(b"\\\\localhost\\c$"))
             self.assertTrue(ntpath.ismount(b"\\\\localhost\\c$\\"))
 
+    def test_isreserved(self):
+        self.assertFalse(ntpath.isreserved(''))
+        self.assertFalse(ntpath.isreserved('/'))
+        self.assertFalse(ntpath.isreserved('/foo/bar'))
+        # A name that ends with a space or dot is reserved.
+        self.assertTrue(ntpath.isreserved('foo.'))
+        self.assertTrue(ntpath.isreserved('foo '))
+        # A name with a file stream is reserved.
+        self.assertTrue(ntpath.isreserved('foo:bar'))
+        # Case-insensitive DOS-device names are reserved.
+        self.assertTrue(ntpath.isreserved('nul'))
+        self.assertTrue(ntpath.isreserved('aux'))
+        self.assertTrue(ntpath.isreserved('prn'))
+        self.assertTrue(ntpath.isreserved('con'))
+        self.assertTrue(ntpath.isreserved('conin$'))
+        self.assertTrue(ntpath.isreserved('conout$'))
+        # COM/LPT + 1-9 or + superscript 1-3 are reserved.
+        self.assertTrue(ntpath.isreserved('COM1'))
+        self.assertTrue(ntpath.isreserved('LPT9'))
+        self.assertTrue(ntpath.isreserved('com\xb9'))
+        self.assertTrue(ntpath.isreserved('com\xb2'))
+        self.assertTrue(ntpath.isreserved('lpt\xb3'))
+        # DOS-device name matching ignores characters after a dot or
+        # a colon and also ignores trailing spaces.
+        self.assertTrue(ntpath.isreserved('NUL.txt'))
+        self.assertTrue(ntpath.isreserved('PRN  '))
+        self.assertTrue(ntpath.isreserved('AUX  .txt'))
+        self.assertTrue(ntpath.isreserved('COM1:bar'))
+        self.assertTrue(ntpath.isreserved('LPT9   :bar'))
+        # DOS-device names are only matched at the beginning
+        # of a path component.
+        self.assertFalse(ntpath.isreserved('bar.com9'))
+        self.assertFalse(ntpath.isreserved('bar.lpt9'))
+        # Only the last path component matters.
+        self.assertTrue(ntpath.isreserved('c:/baz/con/NUL'))
+        self.assertFalse(ntpath.isreserved('c:/NUL/con/baz'))
+        # Bytes are supported.
+        self.assertFalse(ntpath.isreserved(b''))
+        self.assertFalse(ntpath.isreserved(b'/'))
+        self.assertFalse(ntpath.isreserved(b'/foo/bar'))
+        self.assertTrue(ntpath.isreserved(b'foo.'))
+        self.assertTrue(ntpath.isreserved(b'nul'))
+
     def assertEqualCI(self, s1, s2):
         """Assert that two strings are equal ignoring case differences."""
         self.assertEqual(s1.lower(), s2.lower())

Lib/test/test_posixpath.py

@@ -242,6 +242,16 @@ def fake_lstat(path):
         finally:
             os.lstat = save_lstat
 
+    def test_isreserved(self):
+        self.assertFalse(posixpath.isreserved(''))
+        self.assertFalse(posixpath.isreserved(b''))
+        self.assertFalse(posixpath.isreserved('/'))
+        self.assertFalse(posixpath.isreserved(b'/'))
+        self.assertFalse(posixpath.isreserved('hi'))
+        self.assertFalse(posixpath.isreserved(b'hi'))
+        self.assertFalse(posixpath.isreserved('NUL'))
+        self.assertFalse(posixpath.isreserved(b'NUL'))
+
     def test_expanduser(self):
         self.assertEqual(posixpath.expanduser("foo"), "foo")
         self.assertEqual(posixpath.expanduser(b"foo"), b"foo")

Misc/NEWS.d/next/Library/2022-07-31-01-24-40.gh-issue-88569.eU0--b.rst

@@ -0,0 +1,3 @@
+Add :func:`os.path.isreserved`, which identifies reserved pathnames. On
+Windows, reserved names include "NUL", "AUX" and "CON". On other platforms,
+this function always returns ``False``.