bpo-40486: Specify what happens if directory content change diring iteration (GH-22025)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 275b2d3..8c3bc5f 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1852,6 +1852,8 @@
Return a list containing the names of the entries in the directory given by
*path*. The list is in arbitrary order, and does not include the special
entries ``'.'`` and ``'..'`` even if they are present in the directory.
+ If a file is removed from or added to the directory during the call of
+ this function, whether a name for that file be included is unspecified.
*path* may be a :term:`path-like object`. If *path* is of type ``bytes``
(directly or indirectly through the :class:`PathLike` interface),
@@ -2257,7 +2259,9 @@
Return an iterator of :class:`os.DirEntry` objects corresponding to the
entries in the directory given by *path*. The entries are yielded in
arbitrary order, and the special entries ``'.'`` and ``'..'`` are not
- included.
+ included. If a file is removed from or added to the directory after
+ creating the iterator, whether an entry for that file be included is
+ unspecified.
Using :func:`scandir` instead of :func:`listdir` can significantly
increase the performance of code that also needs file type or file
@@ -3007,7 +3011,10 @@
*filenames* is a list of the names of the non-directory files in *dirpath*.
Note that the names in the lists contain no path components. To get a full path
(which begins with *top*) to a file or directory in *dirpath*, do
- ``os.path.join(dirpath, name)``.
+ ``os.path.join(dirpath, name)``. Whether or not the lists are sorted
+ depends on the file system. If a file is removed from or added to the
+ *dirpath* directory during generating the lists, whether a name for that
+ file be included is unspecified.
If optional argument *topdown* is ``True`` or not specified, the triple for a
directory is generated before the triples for any of its subdirectories