gh-83714: Use "stx_" prefix for all os.statx_result members

Doc/library/os.rst

@@ -3412,132 +3412,252 @@ features:
    Information about a file returned by :func:`os.statx`.
 
    :class:`!statx_result` has all the attributes that :class:`~stat_result` has
-   on Linux, making it :term:`duck-typing` compatible, but
+   on Linux, but using ``stx_`` prefix instead of ``st_``.
    :class:`!statx_result` is not a subclass of :class:`~stat_result` and cannot
    be used as a tuple.
 
-   :class:`!statx_result` has the following additional attributes:
+   :class:`!statx_result` has the following attributes:
 
    .. attribute:: stx_mask
 
       Bitmask of :const:`STATX_* <STATX_TYPE>` constants specifying the
       information retrieved, which may differ from what was requested.
 
-   .. attribute:: stx_attributes_mask
+   .. attribute:: stx_atime
 
-      Bitmask of :const:`STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
-      specifying the attributes bits supported for this file.
+      Time of most recent access expressed in seconds.
+
+      Equal to ``None`` if :data:`STATX_ATIME` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_atime_ns
+
+      Time of most recent access expressed in nanoseconds as an integer.
+
+      Equal to ``None`` if :data:`STATX_ATIME` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_atomic_write_segments_max
+
+      Maximum iovecs for direct I/O with torn-write protection.
+
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
+         userspace API headers >= 6.11.
+
+   .. attribute:: stx_atomic_write_unit_min
+
+      Minimum size for direct I/O with torn-write protection.
+
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
+         userspace API headers >= 6.11.
+
+   .. attribute:: stx_atomic_write_unit_max
+
+      Maximum size for direct I/O with torn-write protection.
+
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
+         userspace API headers >= 6.11.
+
+   .. attribute:: stx_atomic_write_unit_max_opt
+
+      Maximum optimized size for direct I/O with torn-write protection.
+
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
+         userspace API headers >= 6.16.
 
    .. attribute:: stx_attributes
 
       Bitmask of :const:`STATX_ATTR_* <stat.STATX_ATTR_COMPRESSED>` constants
       specifying the attributes of this file.
 
-   .. attribute:: stx_dev_major
+   .. attribute:: stx_attributes_mask
 
-      Major number of the device on which this file resides.
+      A mask indicating which bits in :attr:`stx_attributes` are supported by
+      the VFS and the filesystem.
 
-   .. attribute:: stx_dev_minor
+   .. attribute:: stx_blksize
 
-      Minor number of the device on which this file resides.
+      "Preferred" blocksize for efficient file system I/O. Writing to a file in
+      smaller chunks may cause an inefficient read-modify-rewrite.
 
-   .. attribute:: stx_rdev_major
+   .. attribute:: stx_blocks
 
-      Major number of the device this file represents.
+      Number of 512-byte blocks allocated for file.
+      This may be smaller than :attr:`stx_size`/512 when the file has holes.
 
-   .. attribute:: stx_rdev_minor
+      Equal to ``None`` if :data:`STATX_BLOCKS` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      Minor number of the device this file represents.
+   .. attribute:: stx_btime
 
-   .. attribute:: stx_mnt_id
+      Time of file creation expressed in seconds.
 
-      Mount identifier.
+      Equal to ``None`` if :data:`STATX_BTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      Equal to ``None`` if :data:`STATX_MNT_ID` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+   .. attribute:: stx_btime_ns
 
-      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 5.8.
+      Time of file creation expressed in nanoseconds as an integer.
 
-   .. attribute:: stx_dio_mem_align
+      Equal to ``None`` if :data:`STATX_BTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      Direct I/O memory buffer alignment requirement.
+   .. attribute:: stx_ctime
 
-      Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      Time of most recent metadata change expressed in seconds.
 
-      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.1.
+      Equal to ``None`` if :data:`STATX_CTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_ctime_ns
+
+      Time of most recent metadata change expressed in nanoseconds as an
+      integer.
+
+      Equal to ``None`` if :data:`STATX_CTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_dev
+
+      Identifier of the device on which this file resides.
+
+   .. attribute:: stx_dev_major
+
+      Major number of the device on which this file resides.
+
+   .. attribute:: stx_dev_minor
+
+      Minor number of the device on which this file resides.
 
    .. attribute:: stx_dio_offset_align
 
       Direct I/O file offset alignment requirement.
 
       Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      :attr:`~statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.1.
 
-   .. attribute:: stx_subvol
+   .. attribute:: stx_dio_mem_align
 
-      Subvolume identifier.
+      Direct I/O memory buffer alignment requirement.
 
-      Equal to ``None`` if :data:`STATX_SUBVOL` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
+      :attr:`~statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.10.
+         userspace API headers >= 6.1.
 
-   .. attribute:: stx_atomic_write_unit_min
+   .. attribute:: stx_dio_read_offset_align
 
-      Minimum size for direct I/O with torn-write protection.
+      Direct I/O file offset alignment requirement for reads.
 
-      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      Equal to ``None`` if :data:`STATX_DIO_READ_ALIGN` is missing from
+      :attr:`~statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.11.
+         userspace API headers >= 6.14.
 
-   .. attribute:: stx_atomic_write_unit_max
+   .. attribute:: stx_gid
 
-      Maximum size for direct I/O with torn-write protection.
+      Group identifier of the file owner.
 
-      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      Equal to ``None`` if :data:`STATX_GID` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.11.
+   .. attribute:: stx_ino
 
-   .. attribute:: stx_atomic_write_unit_max_opt
+      Inode number.
 
-      Maximum optimized size for direct I/O with torn-write protection.
+      Equal to ``None`` if :data:`STATX_INO` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+   .. attribute:: stx_mnt_id
+
+      Mount identifier.
+
+      Equal to ``None`` if :data:`STATX_MNT_ID` is missing from
+      :attr:`~statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.16.
+         userspace API headers >= 5.8.
 
-   .. attribute:: stx_atomic_write_segments_max
+   .. attribute:: stx_mode
 
-      Maximum iovecs for direct I/O with torn-write protection.
+      File mode: file type and file mode bits (permissions).
 
-      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+   .. attribute:: stx_mtime
 
-      .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.11.
+      Time of most recent content modification expressed in seconds.
 
-   .. attribute:: stx_dio_read_offset_align
+      Equal to ``None`` if :data:`STATX_MTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
 
-      Direct I/O file offset alignment requirement for reads.
+   .. attribute:: stx_mtime_ns
 
-      Equal to ``None`` if :data:`STATX_DIO_READ_ALIGN` is missing from
-      :attr:`~os.statx_result.stx_mask`.
+      Time of most recent content modification expressed in nanoseconds as an
+      integer.
+
+      Equal to ``None`` if :data:`STATX_MTIME` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_nlink
+
+      Number of hard links.
+
+      Equal to ``None`` if :data:`STATX_NLINK` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_rdev
+
+      Type of device if an inode device.
+
+   .. attribute:: stx_rdev_major
+
+      Major number of the device this file represents.
+
+   .. attribute:: stx_rdev_minor
+
+      Minor number of the device this file represents.
+
+   .. attribute:: stx_size
+
+      Size of the file in bytes, if it is a regular file or a symbolic link.
+      The size of a symbolic link is the length of the pathname it contains,
+      without a terminating null byte.
+
+      Equal to ``None`` if :data:`STATX_SIZE` is missing from
+      :attr:`~statx_result.stx_mask`.
+
+   .. attribute:: stx_subvol
+
+      Subvolume identifier.
+
+      Equal to ``None`` if :data:`STATX_SUBVOL` is missing from
+      :attr:`~statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
-         userspace API headers >= 6.14.
+         userspace API headers >= 6.10.
+
+   .. attribute:: stx_uid
+
+      User identifier of the file owner.
+
+      Equal to ``None`` if :data:`STATX_UID` is missing from
+      :attr:`~statx_result.stx_mask`.
 
    .. seealso:: The :manpage:`statx(2)` man page.
 

Lib/test/test_os/test_os.py

@@ -750,52 +750,53 @@ def check_statx_attributes(self, filename):
         result = os.statx(filename, maximal_mask)
         basic_result = os.stat(filename)
 
-        time_attributes = ('st_atime', 'st_mtime', 'st_ctime', 'st_birthtime')
-        # gh-83714: st_birthtime can be None on tmpfs even if STATX_BTIME mask
+        time_attributes = ('stx_atime', 'stx_btime', 'stx_ctime', 'stx_mtime')
+        # gh-83714: stx_btime can be None on tmpfs even if STATX_BTIME mask
         # is used
         time_attributes = [name for name in time_attributes
                            if getattr(result, name) is not None]
         self.check_timestamp_agreement(result, time_attributes)
 
         # Check that valid attributes match os.stat.
         requirements = (
-            ('st_mode', os.STATX_TYPE | os.STATX_MODE),
-            ('st_nlink', os.STATX_NLINK),
-            ('st_uid', os.STATX_UID),
-            ('st_gid', os.STATX_GID),
-            ('st_atime', os.STATX_ATIME),
-            ('st_atime_ns', os.STATX_ATIME),
-            ('st_mtime', os.STATX_MTIME),
-            ('st_mtime_ns', os.STATX_MTIME),
-            ('st_ctime', os.STATX_CTIME),
-            ('st_ctime_ns', os.STATX_CTIME),
-            ('st_ino', os.STATX_INO),
-            ('st_size', os.STATX_SIZE),
-            ('st_blocks', os.STATX_BLOCKS),
-            ('st_birthtime', os.STATX_BTIME),
-            ('st_birthtime_ns', os.STATX_BTIME),
+            ('stx_mode', os.STATX_TYPE | os.STATX_MODE),
+            ('stx_nlink', os.STATX_NLINK),
+            ('stx_uid', os.STATX_UID),
+            ('stx_gid', os.STATX_GID),
+            ('stx_atime', os.STATX_ATIME),
+            ('stx_atime_ns', os.STATX_ATIME),
+            ('stx_mtime', os.STATX_MTIME),
+            ('stx_mtime_ns', os.STATX_MTIME),
+            ('stx_ctime', os.STATX_CTIME),
+            ('stx_ctime_ns', os.STATX_CTIME),
+            ('stx_ino', os.STATX_INO),
+            ('stx_size', os.STATX_SIZE),
+            ('stx_blocks', os.STATX_BLOCKS),
+            ('stx_birthtime', os.STATX_BTIME),
+            ('stx_birthtime_ns', os.STATX_BTIME),
             # unconditionally valid members
-            ('st_blksize', 0),
-            ('st_rdev', 0),
-            ('st_dev', 0),
+            ('stx_blksize', 0),
+            ('stx_rdev', 0),
+            ('stx_dev', 0),
         )
         for name, bits in requirements:
-            if result.stx_mask & bits == bits and hasattr(basic_result, name):
+            st_name = "st_" + name[4:]
+            if result.stx_mask & bits == bits and hasattr(basic_result, st_name):
                 x = getattr(result, name)
-                b = getattr(basic_result, name)
+                b = getattr(basic_result, st_name)
                 self.assertEqual(type(x), type(b))
                 if isinstance(x, float):
                     self.assertAlmostEqual(x, b, msg=name)
                 else:
                     self.assertEqual(x, b, msg=name)
 
-        self.assertEqual(result.stx_rdev_major, os.major(result.st_rdev))
-        self.assertEqual(result.stx_rdev_minor, os.minor(result.st_rdev))
-        self.assertEqual(result.stx_dev_major, os.major(result.st_dev))
-        self.assertEqual(result.stx_dev_minor, os.minor(result.st_dev))
+        self.assertEqual(result.stx_rdev_major, os.major(result.stx_rdev))
+        self.assertEqual(result.stx_rdev_minor, os.minor(result.stx_rdev))
+        self.assertEqual(result.stx_dev_major, os.major(result.stx_dev))
+        self.assertEqual(result.stx_dev_minor, os.minor(result.stx_dev))
 
         members = [name for name in dir(result)
-                   if name.startswith('st_') or name.startswith('stx_')]
+                   if name.startswith('stx_')]
         for name in members:
             try:
                 setattr(result, name, 1)