[Python-checkins] gh-102519: Add doc updates for os.listdrives, listvolumes and listmounts (GH-102585)
zooba
webhook-mailer at python.org
Fri Mar 10 10:41:50 EST 2023
https://github.com/python/cpython/commit/12226bec2588f925f4698e1130ce78e118343934
commit: 12226bec2588f925f4698e1130ce78e118343934
branch: main
author: Steve Dower <steve.dower at python.org>
committer: zooba <steve.dower at microsoft.com>
date: 2023-03-10T15:41:32Z
summary:
gh-102519: Add doc updates for os.listdrives, listvolumes and listmounts (GH-102585)
files:
M Doc/library/os.rst
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 23ce98785bed..5b9f49be1fad 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2188,6 +2188,69 @@ features:
Accepts a :term:`path-like object`.
+.. function:: listdrives()
+
+ Return a list containing the names of drives on a Windows system.
+
+ A drive name typically looks like ``'C:\\'``. Not every drive name
+ will be associated with a volume, and some may be inaccessible for
+ a variety of reasons, including permissions, network connectivity
+ or missing media. This function does not test for access.
+
+ May raise :exc:`OSError` if an error occurs collecting the drive
+ names.
+
+ .. audit-event:: os.listdrives "" os.listdrives
+
+ .. availability:: Windows
+
+ .. versionadded:: 3.12
+
+
+.. function:: listmounts(volume)
+
+ Return a list containing the mount points for a volume on a Windows
+ system.
+
+ *volume* must be represented as a GUID path, like those returned by
+ :func:`os.listvolumes`. Volumes may be mounted in multiple locations
+ or not at all. In the latter case, the list will be empty. Mount
+ points that are not associated with a volume will not be returned by
+ this function.
+
+ The mount points return by this function will be absolute paths, and
+ may be longer than the drive name.
+
+ Raises :exc:`OSError` if the volume is not recognized or if an error
+ occurs collecting the paths.
+
+ .. audit-event:: os.listmounts volume os.listmounts
+
+ .. availability:: Windows
+
+ .. versionadded:: 3.12
+
+
+.. function:: listvolumes()
+
+ Return a list containing the volumes in the system.
+
+ Volumes are typically represented as a GUID path that looks like
+ ``\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\``. Files can
+ usually be accessed through a GUID path, permissions allowing.
+ However, users are generally not familiar with them, and so the
+ recommended use of this function is to retrieve mount points
+ using :func:`os.listmounts`.
+
+ May raise :exc:`OSError` if an error occurs collecting the volumes.
+
+ .. audit-event:: os.listvolumes "" os.listvolumes
+
+ .. availability:: Windows
+
+ .. versionadded:: 3.12
+
+
.. function:: lstat(path, *, dir_fd=None)
Perform the equivalent of an :c:func:`lstat` system call on the given path.
More information about the Python-checkins
mailing list