[New-bugs-announce] [issue38825] psutil.disk_usage - Lacking documentation

[Lord Anton Hvornum]

New submission from Lord Anton Hvornum <anton.doxid at gmail.com>:

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.

----------
assignee: docs at python
components: Documentation
messages: 356771
nosy: Lord Anton Hvornum, docs at python
priority: normal
severity: normal
status: open
title: psutil.disk_usage - Lacking documentation
type: enhancement
versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38825>
_______________________________________