shutil.disk_usage - Lacking documentation

[LordAntonHvornum]

BPO	38825
Nosy	@giampaolo, @tarekziade, @tylercrompton, @tirkarthi, @normanlorrain

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-11-16.22:19:58.065>
labels = ['easy', '3.9', '3.10', '3.11', 'type-feature', 'docs']
title = 'shutil.disk_usage - Lacking documentation'
updated_at = <Date 2021-07-12.21:07:41.352>
user = 'https://bugs.python.org/LordAntonHvornum'

bugs.python.org fields:

activity = <Date 2021-07-12.21:07:41.352>
actor = 'Norman Lorrain'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-11-16.22:19:58.065>
creator = 'Lord Anton Hvornum'
dependencies = []
files = []
hgrepos = []
issue_num = 38825
keywords = ['easy']
message_count = 6.0
messages = ['356771', '356788', '356796', '396520', '397267', '397357']
nosy_count = 7.0
nosy_names = ['giampaolo.rodola', 'tarek', 'docs@python', 'tylercrompton', 'Lord Anton Hvornum', 'xtreak', 'Norman Lorrain']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38825'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-83006: Document behavior of shutil.disk_usage for non-mounted filesystems on Unix #107031
• [3.12] gh-83006: Document behavior of shutil.disk_usage for non-mounted filesystems on Unix (GH-107031) #107047
• [3.11] gh-83006: Document behavior of shutil.disk_usage for non-mounted filesystems on Unix (GH-107031) #107048

[LordAntonHvornum]

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.

[tirkarthi]

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

[LordAntonHvornum]

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