From 45204e8ad27eb3a10ea22f5fdfefaeaf098929b3 Mon Sep 17 00:00:00 2001
From: Matthieu Caneill <matthieucan@users.noreply.github.com>
Date: Sat, 22 Jul 2023 17:58:06 +0200
Subject: [PATCH] gh-83006: Document behavior of `shutil.disk_usage` for
 non-mounted filesystems on Unix (GH-107031) (cherry picked from commit
 6e5f2235f3754307292c7d8d3698958136b5e311)

Co-authored-by: Matthieu Caneill <matthieucan@users.noreply.github.com>
---
 Doc/library/shutil.rst                                      | 6 ++++++
 .../Library/2023-07-22-15-51-33.gh-issue-83006.21zaCz.rst   | 2 ++
 2 files changed, 8 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Library/2023-07-22-15-51-33.gh-issue-83006.21zaCz.rst

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 5bd80b10a65806..7699d22a72aaff 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -399,6 +399,12 @@ Directory and files operations
    total, used and free space, in bytes. *path* may be a file or a
    directory.
 
+   .. note::
+
+      On Unix filesystems, *path* must point to a path within a **mounted**
+      filesystem partition. On those platforms, CPython doesn't attempt to
+      retrieve disk usage information from non-mounted filesystems.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.8
diff --git a/Misc/NEWS.d/next/Library/2023-07-22-15-51-33.gh-issue-83006.21zaCz.rst b/Misc/NEWS.d/next/Library/2023-07-22-15-51-33.gh-issue-83006.21zaCz.rst
new file mode 100644
index 00000000000000..e64d1860828430
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2023-07-22-15-51-33.gh-issue-83006.21zaCz.rst
@@ -0,0 +1,2 @@
+Document behavior of :func:`shutil.disk_usage` for non-mounted filesystems
+on Unix.