https://docs.python.org/3.8/library/shutil.html#shutil.disk_usage

There's no mention that this helper function simply calls `os.statvfs()` in the background. Something that is quite troubling when you're trying to get disk_usage (or disk-information) about a non-mounted drive.

It's clear as day if you see the code: https://github.com/python/cpython/blob/master/Lib/shutil.py#L1249

But if you're a novice user, this will puzzle your brain.
Because the end result will be that `disk_usage()` returns the same information for all these cases:

shutil.disk_usage('/dev/sda')
shutil.disk_usage('/dev/sdb')
shutil.disk_usage('/dev/sdc')

Which translates to:

os.statvfs('/dev/sd?')'

--

All I'm asking, is that we add a little note stating:
"On *mounted* filesystems" or a reference to `os.statvfs()` where it's clearly stated that it runs on mounted filesystems.

Thanks in advance.

I modified psutil to shutil since I feel it's a typo. Please revert back if it's incorrect.

xtreak: You are correct, that was a typo. My apologies.

This issue is a bit dated, but here goes: 

   On Unix, the function `statvfs()` is called. `path` should be a path on a mounted filesystem (it should not be a device).

   On Windows, the function `GetDiskFreeSpaceExW()` is called. `path` is any directory on a disk volume.


Looking through the rest of the page, no other functions get into such specifics; maybe this is outside the scope of the document. Maybe the issue should be closed.

Not even the kernel knows how much space is available on a nonmounted partition. It doesn't know much beyond the fact that it exists and where it exists. There exist tools that can analyze nonmounted partitions, but these will vary by filesystem and operating system. If someone wants to implement solutions for the most common filesystem-OS combinations, then that might be helpful.

But considering that no one has done that or even asked for it yet, I'm not sure that doing so is worth the effort. So I agree that documenting it is the best approach. It should be documented such that the limitations are mentioned, not necessarily how it's implemented. If explaining which system calls are used helps explain the limitations, then so be it. Additionally, as far as I'm concerned, there's no reason to restrict other Python implementations from implementing functionality for nonmounted disks. So the limitations should be described as being CPython-specific, akin to what is done for `readline.set_auto_history`.

Something like this:

   .. impl-detail::
      Where applicable (e.g. Unix) *path* must point to somewhere on a
**mounted** filesystem partition.

On Sun, 11 Jul 2021 at 16:18, Tyler Crompton <report@bugs.python.org> wrote:

>
> Tyler Crompton <tyler@tylercrompton.com> added the comment:
>
> Not even the kernel knows how much space is available on a nonmounted
> partition. It doesn't know much beyond the fact that it exists and where it
> exists. There exist tools that can analyze nonmounted partitions, but these
> will vary by filesystem and operating system. If someone wants to implement
> solutions for the most common filesystem-OS combinations, then that might
> be helpful.
>
> But considering that no one has done that or even asked for it yet, I'm
> not sure that doing so is worth the effort. So I agree that documenting it
> is the best approach. It should be documented such that the limitations are
> mentioned, not necessarily how it's implemented. If explaining which system
> calls are used helps explain the limitations, then so be it. Additionally,
> as far as I'm concerned, there's no reason to restrict other Python
> implementations from implementing functionality for nonmounted disks. So
> the limitations should be described as being CPython-specific, akin to what
> is done for `readline.set_auto_history`.
>
> ----------
> nosy: +tylercrompton
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue38825>
> _______________________________________
>