Merge branch 'main' into gh-151627-odict-iterator-race

Author: pedramkarimii

Doc/library/curses.rst

@@ -204,6 +204,17 @@ The module :mod:`!curses` defines the following functions:
    character-at-a-time  line editing without touching the rest of the screen.
 
 
+.. function:: nofilter()
+
+   Undo the effect of a previous :func:`.filter` call.
+   Like :func:`.filter`, it must be called before :func:`initscr` so that the
+   next initialization uses the full screen again.
+
+   Availability: if the underlying curses library provides ``nofilter()``.
+
+   .. versionadded:: next
+
+
 .. function:: flash()
 
    Flash the screen.  That is, change it to reverse-video and then change it back

Doc/library/os.rst

@@ -541,7 +541,7 @@ process and user.
    Return a tuple (ruid, euid, suid) denoting the current process's
    real, effective, and saved user ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not macOS, not iOS.
 
    .. versionadded:: 3.2
 
@@ -551,7 +551,7 @@ process and user.
    Return a tuple (rgid, egid, sgid) denoting the current process's
    real, effective, and saved group ids.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not macOS, not iOS.
 
    .. versionadded:: 3.2
 
@@ -725,7 +725,7 @@ process and user.
 
    Set the current process's real, effective, and saved group ids.
 
-   .. availability:: Unix, not WASI, not Android.
+   .. availability:: Unix, not WASI, not Android, not macOS, not iOS.
 
    .. versionadded:: 3.2
 
@@ -734,7 +734,7 @@ process and user.
 
    Set the current process's real, effective, and saved user ids.
 
-   .. availability:: Unix, not WASI, not Android.
+   .. availability:: Unix, not WASI, not Android, not macOS, not iOS.
 
    .. versionadded:: 3.2
 
@@ -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
@@ -1071,10 +1096,7 @@ as internal buffering of data.
    Force write of file with filedescriptor *fd* to disk. Does not force update of
    metadata.
 
-   .. availability:: Unix.
-
-   .. note::
-      This function is not available on MacOS.
+   .. availability:: Unix, not macOS, not iOS.
 
 
 .. function:: fpathconf(fd, name, /)
@@ -1112,8 +1134,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.
 
@@ -1426,7 +1448,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
    respectively.
 
-   .. availability:: Unix, not WASI.
+   .. availability:: Unix, not WASI, not macOS, not iOS.
 
    .. versionadded:: 3.3
 
@@ -1436,7 +1458,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Ensures that enough disk space is allocated for the file specified by *fd*
    starting from *offset* and continuing for *len* bytes.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not macOS, not iOS.
 
    .. versionadded:: 3.3
 
@@ -1451,7 +1473,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
    :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
 
-   .. availability:: Unix.
+   .. availability:: Unix, not macOS, not iOS.
 
    .. versionadded:: 3.3
 
@@ -3784,48 +3806,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
@@ -5107,7 +5255,7 @@ written in Python, such as a mail server's external command delivery program.
    Lock program segments into memory.  The value of *op* (defined in
    ``<sys/lock.h>``) determines which segments are locked.
 
-   .. availability:: Unix, not WASI, not iOS.
+   .. availability:: Unix, not WASI, not macOS, not iOS.
 
 
 .. function:: popen(cmd, mode='r', buffering=-1)