> > Also be aware that symlinks mean sometimes you won't have a dirfd: if
> > you have a symlink that points to another directory, you can't open that
> > directory using openat from the symlink's directory. So if you follow
> > symlinks (or have an option to do so) you must also take that case into
> > account.
> 
> I'm not sure I understand this. Why "you can't open that directory
> using openat from the symlink's directory". Could you elaborate?

Hmm, sorry, I must have misremembered. I thought openat didn't follow
symlinks.

As for the patch, I think there's a problem with the API:

+    This behaves exactly like walk(), except that it accepts a file descriptor
+    as top directory, and yields a 3-tuple
+
+        dirfd, dirnames, filenames

It doesn't tell you to which dirname corresponds dirfd, so you don't
know the path of the directory you are handed (which can be useful for
progress report, error report, or anything else where you need the name
- e.g. making a zip archive of the directory). Also giving the dirnames
without their fds encourages using them by name, not by fd ;-)

Also, walkfd would be easier to use if callable with a str or bytes path
rather than an int fd.