gh-85264: Request actual filesize from 'os.path.getsize'

Provide the ability to get the actual, on-disk size of a file using
'os.path.getsize'. This is helpful when dealing with things like sparse
files.

Signed-off-by: Stephen Finucane <stephen@that.guru>

Author: stephenfin

Doc/library/os.path.rst

@@ -239,14 +239,24 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: getsize(path, /)
+.. function:: getsize(path, /, apparent=True)
 
    Return the size, in bytes, of *path*.  Raise :exc:`OSError` if the file does
-   not exist or is inaccessible.
+   not exist or is inaccessible.  If *apparent* is ``True``, the apparent size
+   (number of bytes) of the file is returned.  If ``False``, the actual size
+   (disk space occupied) is returned. The actual size reflects the block size,
+   meaning it will typically be larger than the apparent size. However, the
+   inverse may also be true due to holes in ("sparse") files, internal
+   fragmentation, indirect blocks, etc. Passing ``apparent=False`` is only
+   supported on platforms where :data:`os.DEV_BSIZE` is available; a
+   :exc:`NotImplementedError` is raised otherwise.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: 3.15
+      Add the optional *apparent* parameter.
+
 
 .. function:: isabs(path, /)
 

Lib/genericpath.py

@@ -82,9 +82,27 @@ def isdevdrive(path):
     return False
 
 
-def getsize(filename, /):
-    """Return the size of a file, reported by os.stat()."""
-    return os.stat(filename).st_size
+def getsize(filename, /, apparent=True):
+    """Return the size of a file, reported by os.stat().
+
+    If 'apparent' is True (default), the apparent size (number of bytes) of the
+    file is returned. If False, the actual size (disk space occupied) is
+    returned. The actual size reflects the block size, meaning it will
+    typically be larger than the apparent size. However, the inverse may also
+    be true due to holes in ("sparse") files, internal fragmentation, indirect
+    blocks, etc.
+
+    Not all platforms support apparent=False; a NotImplementedError is raised
+    on platforms where os.DEV_BSIZE is not available.
+    """
+    if apparent:
+        return os.stat(filename).st_size
+    _dev_bsize = getattr(os, 'DEV_BSIZE', None)
+    if _dev_bsize is None:
+        raise NotImplementedError(
+            "os.path.getsize() with apparent=False is not supported on this platform"
+        )
+    return os.stat(filename).st_blocks * _dev_bsize
 
 
 def getmtime(filename, /):

Lib/test/test_genericpath.py

@@ -114,6 +114,53 @@ def test_getsize(self):
 
         create_file(filename, b'Hello World!')
         self.assertEqual(self.pathmodule.getsize(filename), 12)
+        os.remove(filename)
+
+        open(filename, 'xb', 0).close()
+        os.truncate(filename, 512)
+        self.assertEqual(self.pathmodule.getsize(filename), 512)
+
+    @unittest.skipUnless(hasattr(os, 'DEV_BSIZE'),
+                         "os.DEV_BSIZE not available on this platform")
+    def test_getsize_actual(self):
+        filename = os_helper.TESTFN
+        self.addCleanup(os_helper.unlink, filename)
+
+        # DEV_BSIZE varies across platforms
+        if support.is_android:
+            expected = 8192
+        elif support.is_wasi:
+            expected = 0
+        else:
+            expected = 4096
+
+        create_file(filename, b'Hello')
+        self.assertEqual(self.pathmodule.getsize(filename, apparent=False), expected)
+        os.remove(filename)
+
+        create_file(filename, b'Hello World!')
+        self.assertEqual(self.pathmodule.getsize(filename, apparent=False), expected)
+        os.remove(filename)
+
+        # DEV_BSIZE varies across platforms
+        if support.is_android:
+            expected = 4096
+        else:
+            expected = 0
+
+        open(filename, 'xb', 0).close()
+        os.truncate(filename, 512)
+        self.assertEqual(self.pathmodule.getsize(filename, apparent=False), expected)
+
+    @unittest.skipIf(hasattr(os, 'DEV_BSIZE'),
+                     "os.DEV_BSIZE is available on this platform")
+    def test_getsize_actual_not_supported(self):
+        filename = os_helper.TESTFN
+        self.addCleanup(os_helper.unlink, filename)
+
+        create_file(filename, b'Hello')
+        with self.assertRaises(NotImplementedError):
+            self.pathmodule.getsize(filename, apparent=False)
 
     def test_filetime(self):
         filename = os_helper.TESTFN

Misc/NEWS.d/next/Library/2026-03-27-13-26-47.gh-issue-85264.iA_8Al.rst

@@ -0,0 +1,2 @@
+Add support for an ``apparent`` option for ``os.get_size`` to allow
+retrieving the actual on-disk size of sparse files.