[issue38825] shutil.disk_usage - Lacking documentation

[Norman Lorrain]

Norman Lorrain  added the comment:

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  wrote:

>
> Tyler Crompton  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 
> 
> ___
>

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38825] shutil.disk_usage - Lacking documentation

[Tyler Crompton]

Tyler Crompton  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38825] shutil.disk_usage - Lacking documentation

[Norman Lorrain]

Norman Lorrain  added the comment:

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.

--
nosy: +Norman Lorrain

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38825] shutil.disk_usage - Lacking documentation

[Irit Katriel]

Change by Irit Katriel :


--
keywords: +easy
versions: +Python 3.10, Python 3.11 -Python 3.5, Python 3.6, Python 3.7, Python 
3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38825] shutil.disk_usage - Lacking documentation

[Lord Anton Hvornum]

Lord Anton Hvornum  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38825] shutil.disk_usage - Lacking documentation

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

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

--
nosy: +giampaolo.rodola, tarek, xtreak
title: psutil.disk_usage - Lacking documentation -> shutil.disk_usage - Lacking 
documentation

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com