gh-101100: Document os.uname_result and os.statvfs_result with related constants (GH-151301)

Author: cmaloney

Doc/library/os.rst

@@ -800,36 +800,61 @@ process and user.
       single: gethostbyaddr() (in module socket)
 
    Returns information identifying the current operating system.
-   The return value is an object with five attributes:
-
-   * :attr:`sysname` - operating system name
-   * :attr:`nodename` - name of machine on network (implementation-defined)
-   * :attr:`release` - operating system release
-   * :attr:`version` - operating system version
-   * :attr:`machine` - hardware identifier
-
-   For backwards compatibility, this object is also iterable, behaving
-   like a five-tuple containing :attr:`sysname`, :attr:`nodename`,
-   :attr:`release`, :attr:`version`, and :attr:`machine`
-   in that order.
-
-   Some systems truncate :attr:`nodename` to 8 characters or to the
-   leading component; a better way to get the hostname is
-   :func:`socket.gethostname`  or even
-   ``socket.gethostbyaddr(socket.gethostname())``.
+   The return value is a :class:`uname_result`.
 
    On macOS, iOS and Android, this returns the *kernel* name and version (i.e.,
    ``'Darwin'`` on macOS and iOS; ``'Linux'`` on Android). :func:`platform.uname`
    can be used to get the user-facing operating system name and version on iOS and
    Android.
 
+   .. seealso::
+      :data:`sys.platform` which has finer granularity.
+
+      The :mod:`platform` module provides detailed checks for the
+      system's identity.
+
    .. availability:: Unix.
 
    .. versionchanged:: 3.3
       Return type changed from a tuple to a tuple-like object
       with named attributes.
 
 
+.. class:: uname_result
+
+   Name and information about the system returned by :func:`os.uname`.
+   These attributes correspond to the members described in :manpage:`uname(2)`.
+
+   For backwards compatibility, this object is also iterable, behaving
+   like a five-tuple containing :attr:`~uname_result.sysname`,
+   :attr:`~uname_result.nodename`, :attr:`~uname_result.release`,
+   :attr:`~uname_result.version`, and :attr:`~uname_result.machine`
+   in that order.
+
+   .. attribute:: sysname
+
+      Operating system name.
+
+   .. attribute:: nodename
+
+      Name of machine on network. Some systems truncate
+      :attr:`~uname_result.nodename` to 8 characters or to the leading
+      component; a better way to get the hostname is :func:`socket.gethostname`
+      or even ``socket.gethostbyaddr(socket.gethostname())``.
+
+   .. attribute:: release
+
+      Operating system release.
+
+   .. attribute:: version
+
+      Operating system version.
+
+   .. attribute:: machine
+
+      Hardware identifier.
+
+
 .. function:: unsetenv(key, /)
 
    .. index:: single: environment variables; deleting
@@ -1112,8 +1137,8 @@ as internal buffering of data.
 .. function:: fstatvfs(fd, /)
 
    Return information about the filesystem containing the file associated with
-   file descriptor *fd*, like :func:`statvfs`.  As of Python 3.3, this is
-   equivalent to ``os.statvfs(fd)``.
+   file descriptor *fd* in a :class:`statvfs_result`, like :func:`statvfs`.
+   As of Python 3.3, this is equivalent to ``os.statvfs(fd)``.
 
    .. availability:: Unix.
 
@@ -3784,48 +3809,174 @@ features:
 
 .. function:: statvfs(path)
 
-   Perform a :c:func:`!statvfs` system call on the given path.  The return value is
-   an object whose attributes describe the filesystem on the given path, and
-   correspond to the members of the :c:struct:`statvfs` structure, namely:
-   :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
-   :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
-   :attr:`f_flag`, :attr:`f_namemax`, :attr:`f_fsid`.
-
-   Two module-level constants are defined for the :attr:`f_flag` attribute's
-   bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted
-   read-only, and if :const:`ST_NOSUID` is set, the semantics of
-   setuid/setgid bits are disabled or not supported.
-
-   Additional module-level constants are defined for GNU/glibc based systems.
-   These are :const:`ST_NODEV` (disallow access to device special files),
-   :const:`ST_NOEXEC` (disallow program execution), :const:`ST_SYNCHRONOUS`
-   (writes are synced at once), :const:`ST_MANDLOCK` (allow mandatory locks on an FS),
-   :const:`ST_WRITE` (write on file/directory/symlink), :const:`ST_APPEND`
-   (append-only file), :const:`ST_IMMUTABLE` (immutable file), :const:`ST_NOATIME`
-   (do not update access times), :const:`ST_NODIRATIME` (do not update directory access
-   times), :const:`ST_RELATIME` (update atime relative to mtime/ctime).
+   Perform a :manpage:`statvfs(3)` system call on the given path.  The return value
+   is a :class:`statvfs_result` whose attributes describe the filesystem
+   on the given path and correspond to the members of the :c:struct:`statvfs`
+   structure.
 
    This function can support :ref:`specifying a file descriptor <path_fd>`.
 
    .. availability:: Unix.
 
-   .. versionchanged:: 3.2
-      The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
-
    .. versionchanged:: 3.3
       Added support for specifying *path* as an open file descriptor.
 
-   .. versionchanged:: 3.4
-      The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`,
-      :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`,
-      :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`,
-      and :const:`ST_RELATIME` constants were added.
-
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
-   .. versionchanged:: 3.7
-      Added the :attr:`f_fsid` attribute.
+
+.. class:: statvfs_result
+
+   Filesystem statistics returned by :func:`os.statvfs` and :func:`os.fstatvfs`.
+   See :manpage:`statvfs(3)` for more details.
+
+   .. attribute:: f_bsize
+
+      Block size.
+
+   .. attribute:: f_frsize
+
+      Fragment size.
+
+   .. attribute:: f_blocks
+
+      Number of :attr:`~statvfs_result.f_frsize` sized blocks the filesystem
+      can contain.
+
+   .. attribute:: f_bfree
+
+      Number of free blocks.
+
+   .. attribute:: f_bavail
+
+      Number of free blocks for unprivileged users.
+
+   .. attribute:: f_files
+
+      Number of file entries, inodes, the filesystem can contain.
+
+   .. attribute:: f_ffree
+
+      Number of free files entries.
+
+   .. attribute:: f_favail
+
+      Number of free file entries for unprivileged users.
+
+   .. attribute:: f_flag
+
+      Bit-mask of mount flags.  The following flags are defined:
+      :data:`ST_RDONLY`, :data:`ST_NOSUID`, :data:`ST_NODEV`,
+      :data:`ST_NOEXEC`, :data:`ST_SYNCHRONOUS`, :data:`ST_MANDLOCK`,
+      :data:`ST_WRITE`, :data:`ST_APPEND`, :data:`ST_IMMUTABLE`,
+      :data:`ST_NOATIME`, :data:`ST_NODIRATIME`, and :data:`ST_RELATIME`.
+
+   .. attribute:: f_namemax
+
+      Filesystem max filename length. OS specific limitations such as
+      :ref:`Windows MAX_PATH <max-path>` and those described in Linux
+      :manpage:`pathname(7)` may exist.
+
+   .. attribute:: f_fsid
+
+      Filesystem ID.
+
+      .. versionadded:: 3.7
+
+
+The following flags are used in :attr:`statvfs_result.f_flag`.
+
+.. data:: ST_RDONLY
+
+   Read-only filesystem.
+
+   .. versionadded:: 3.2
+
+.. data:: ST_NOSUID
+
+   Setuid/setgid bits are disabled or not supported.
+
+   .. versionadded:: 3.2
+
+.. data:: ST_NODEV
+
+   Disallow access to device special files.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_NOEXEC
+
+   Disallow program execution.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_SYNCHRONOUS
+
+   Writes are synced at once.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_MANDLOCK
+
+   Allow mandatory locks on an FS.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_WRITE
+
+   Write on file/directory/symlink.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_APPEND
+
+   Append-only file.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_IMMUTABLE
+
+   Immutable file.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_NOATIME
+
+   Do not update access times.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_NODIRATIME
+
+   Do not update directory access times.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
+
+.. data:: ST_RELATIME
+
+   Update atime relative to mtime/ctime.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.4
 
 
 .. data:: supports_dir_fd

Doc/tools/.nitignore

@@ -18,7 +18,6 @@ Doc/library/lzma.rst
 Doc/library/mmap.rst
 Doc/library/multiprocessing.rst
 Doc/library/optparse.rst
-Doc/library/os.rst
 Doc/library/pickletools.rst
 Doc/library/pyexpat.rst
 Doc/library/select.rst

Misc/NEWS.d/3.10.0a4.rst

@@ -622,7 +622,7 @@ Harmonized :func:`random.randrange` argument handling to match :func:`range`.
 .. nonce: O4VcCY
 .. section: Library
 
-Restore compatibility for ``uname_result`` around deepcopy and _replace.
+Restore compatibility for :class:`os.uname_result` around deepcopy and _replace.
 
 ..
 

Misc/NEWS.d/3.12.0a3.rst

@@ -454,8 +454,8 @@ event loop but the current event loop was set.
 .. nonce: humlhz
 .. section: Library
 
-On ``uname_result``, restored expectation that ``_fields`` and ``_asdict``
-would include all six properties including ``processor``.
+On :class:`os.uname_result`, restored expectation that ``_fields`` and
+``_asdict`` would include all six properties including ``processor``.
 
 ..