classification
Title: shutil.disk_usage - Lacking documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Lord Anton Hvornum, Norman Lorrain, docs@python, giampaolo.rodola, tarek, tylercrompton, xtreak
Priority: normal Keywords: easy

Created on 2019-11-16 22:19 by Lord Anton Hvornum, last changed 2021-07-12 21:07 by Norman Lorrain.

Messages (6)
msg356771 - (view) Author: Lord Anton Hvornum (Lord Anton Hvornum) Date: 2019-11-16 22:19
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.
msg356788 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2019-11-17 02:30
I modified psutil to shutil since I feel it's a typo. Please revert back if it's incorrect.
msg356796 - (view) Author: Lord Anton Hvornum (Lord Anton Hvornum) Date: 2019-11-17 10:04
xtreak: You are correct, that was a typo. My apologies.
msg396520 - (view) Author: Norman Lorrain (Norman Lorrain) * Date: 2021-06-25 00:37
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.
msg397267 - (view) Author: Tyler Crompton (tylercrompton) * Date: 2021-07-11 22:18
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`.
msg397357 - (view) Author: Norman Lorrain (Norman Lorrain) * Date: 2021-07-12 21:07
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>
> _______________________________________
>
History
Date User Action Args
2021-07-12 21:07:41Norman Lorrainsetmessages: + msg397357
2021-07-11 22:18:49tylercromptonsetnosy: + tylercrompton
messages: + msg397267
2021-06-25 00:37:19Norman Lorrainsetnosy: + Norman Lorrain
messages: + msg396520
2021-06-21 16:36:23iritkatrielsetkeywords: + easy
versions: + Python 3.10, Python 3.11, - Python 3.5, Python 3.6, Python 3.7, Python 3.8
2019-11-17 10:04:58Lord Anton Hvornumsetmessages: + msg356796
2019-11-17 02:30:20xtreaksetnosy: + xtreak, tarek, giampaolo.rodola

messages: + msg356788
title: psutil.disk_usage - Lacking documentation -> shutil.disk_usage - Lacking documentation
2019-11-16 22:19:58Lord Anton Hvornumcreate