Documentation for Path.iterdir ( https://docs.python.org/3/library/pathlib.html#pathlib.Path.iterdir ) doesn't specify what happens when the directory change.

This is important, as the function does NOT return a list (which would imply that a "snapshot" of the directory will be returned).

Also, it's not only relevant what would happen if somebody else changes the directory after the iteration is started (will that change be reflected?) but also if it's ALLOWED for the same code that iterates the dir content to change it (or problems would arise, like when changing a dictionary while being iterated).

There is no principal difference between Path.iterdir() and os.listdir(). Somebody can change the directory during iteration. The only difference is that in the latter case you iterate in C instead of Python, so it is less easy to catch a race condition. What would happen is OS and FS specific. Depending on OS and FS it may be even possible to get the same name several times when somebody quickly creates and removes entities in the directory.

However, Serhiy, `os.listdir()` builds a list quickly and gives you that, so the chance of the directory being modified is quite low (however, for big directories, that may happen, and it's probably good to notice that in the docs).

For `Path.iterdir()` that list is not built, and as it's iteration is external, the amount of time between getting one item to the other is unbound, *anything* could happen in the middle. 

In short, I think that both docs should state that the directory could change while it's iterated (in the os.listdir case probably stating that the chances are low).

New changeset 306cfb3a37e1438f6ba9f0a9f3af3c00aae4ec64 by Serhiy Storchaka in branch 'master':
bpo-40486: Specify what happens if directory content change diring iteration (GH-22025)
https://github.com/python/cpython/commit/306cfb3a37e1438f6ba9f0a9f3af3c00aae4ec64

New changeset e52f5bc898c9a11fb1d57a42a1f9ec60b424d576 by Miss Islington (bot) in branch '3.8':
[3.8] bpo-40486: Specify what happens if directory content change diring iteration (GH-22025) (GH-22094)
https://github.com/python/cpython/commit/e52f5bc898c9a11fb1d57a42a1f9ec60b424d576

New changeset bd078df28322f840afd363b6ba097b5506ea5098 by Miss Islington (bot) in branch '3.9':
[3.9] bpo-40486: Specify what happens if directory content change diring iteration (GH-22025) (GH-22093)
https://github.com/python/cpython/commit/bd078df28322f840afd363b6ba097b5506ea5098