homepage

> The documentation of this function is generally ambiguous, because
> os.walk is a generator. Thus "generate" means (1) yielded from a 
> generator and (2) prepared for later use within the generator. To avoid 
> the ambiguity, "generate" should be avoided if possible. (1) might be 
> replaced by "return" and (2) by "prepare".
It think that you are wrong here: generate is consistently used in
meaning (1) in the docstring. Also "return" means something completely different. "generate" is better than "prepare", because it is more specific,
especially from the POV of the user of the function, who only cares about
when something is yielded, not when it is prepared.
> Proposal (very verbose I'm afraid):
> If you change the directory structure below dirpath while topdown=True, 
> you can modify dirnames in-place so that walk will visit the right 
> directories. If you change the directory structure below dirpath while 
> topdown=False (maybe while you where there), dirnames and filenames can 
> still reflect the old situation and it might be necessary to call 
> os.listdir again.
Hm, I think that the difference in behaviour between topdown=False and topdown=True is smaller then this proposal implies.
When topdown=True, the list is not updated after changes on disk. So both removing and adding directories does _not_ cause them to added or removed from the list of subdirectories to visit. Nevertheless, the default behaviour on
error is to do nothing, so it _looks_ like they were skipped.
So I think that the documentation could only clarify that the list of subdirectories is queried first, before the dir or the subdirectories are "generated".