From c48fe98a7c3bb48fd689088baf3fedf9da7a8c70 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Mon, 25 Jun 2012 04:49:05 -0700 Subject: Issue #15177: Added dir_fd parameter to os.fwalk(). --- Doc/library/os.rst | 7 +++++-- Lib/os.py | 18 +++++++++++------- Lib/test/test_os.py | 29 ++++++++++++++++++++++++----- Misc/NEWS | 2 ++ 4 files changed, 42 insertions(+), 14 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 0b6ab24..6d18300 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -2211,18 +2211,21 @@ features: os.rmdir(os.path.join(root, name)) -.. function:: fwalk(top, topdown=True, onerror=None, followlinks=False) +.. function:: fwalk(top='.', topdown=True, onerror=None, followlinks=False, *, dir_fd=None) .. index:: single: directory; walking single: directory; traversal This behaves exactly like :func:`walk`, except that it yields a 4-tuple - ``(dirpath, dirnames, filenames, dirfd)``. + ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``. *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output, and *dirfd* is a file descriptor referring to the directory *dirpath*. + This function always supports :ref:`paths relative to directory descriptors + `. + .. note:: Since :func:`fwalk` yields file descriptors, those are only valid until diff --git a/Lib/os.py b/Lib/os.py index f990627..381737f 100644 --- a/Lib/os.py +++ b/Lib/os.py @@ -422,9 +422,9 @@ def walk(top, topdown=True, onerror=None, followlinks=False): __all__.append("walk") -if open in supports_dir_fd: +if {open, stat} <= supports_dir_fd and {listdir, stat} <= supports_fd: - def fwalk(top, topdown=True, onerror=None, followlinks=False): + def fwalk(top=".", topdown=True, onerror=None, followlinks=False, *, dir_fd=None): """Directory tree generator. This behaves exactly like walk(), except that it yields a 4-tuple @@ -434,9 +434,13 @@ if open in supports_dir_fd: `dirpath`, `dirnames` and `filenames` are identical to walk() output, and `dirfd` is a file descriptor referring to the directory `dirpath`. - The advantage of walkfd() over walk() is that it's safe against symlink + The advantage of fwalk() over walk() is that it's safe against symlink races (when followlinks is False). + If dir_fd is not None, it should be a file descriptor open to a directory, + and top should be relative; top will then be relative to that directory. + (dir_fd is always supported for fwalk.) + Caution: Since fwalk() yields file descriptors, those are only valid until the next iteration step, so you should dup() them if you want to keep them @@ -455,11 +459,11 @@ if open in supports_dir_fd: """ # Note: To guard against symlink races, we use the standard # lstat()/open()/fstat() trick. - orig_st = lstat(top) - topfd = open(top, O_RDONLY) + orig_st = stat(top, follow_symlinks=False, dir_fd=dir_fd) + topfd = open(top, O_RDONLY, dir_fd=dir_fd) try: if (followlinks or (st.S_ISDIR(orig_st.st_mode) and - path.samestat(orig_st, fstat(topfd)))): + path.samestat(orig_st, stat(topfd)))): yield from _fwalk(topfd, top, topdown, onerror, followlinks) finally: close(topfd) @@ -502,7 +506,7 @@ if open in supports_dir_fd: onerror(err) return try: - if followlinks or path.samestat(orig_st, fstat(dirfd)): + if followlinks or path.samestat(orig_st, stat(dirfd)): dirpath = path.join(toppath, name) yield from _fwalk(dirfd, dirpath, topdown, onerror, followlinks) finally: diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py index 62a7dad..57de993 100644 --- a/Lib/test/test_os.py +++ b/Lib/test/test_os.py @@ -741,19 +741,38 @@ class WalkTests(unittest.TestCase): class FwalkTests(WalkTests): """Tests for os.fwalk().""" - def test_compare_to_walk(self): - # compare with walk() results + def _compare_to_walk(self, walk_kwargs, fwalk_kwargs): + """ + compare with walk() results. + """ for topdown, followlinks in itertools.product((True, False), repeat=2): - args = support.TESTFN, topdown, None, followlinks + d = {'topdown': topdown, 'followlinks': followlinks} + walk_kwargs.update(d) + fwalk_kwargs.update(d) + expected = {} - for root, dirs, files in os.walk(*args): + for root, dirs, files in os.walk(**walk_kwargs): expected[root] = (set(dirs), set(files)) - for root, dirs, files, rootfd in os.fwalk(*args): + for root, dirs, files, rootfd in os.fwalk(**fwalk_kwargs): self.assertIn(root, expected) self.assertEqual(expected[root], (set(dirs), set(files))) + def test_compare_to_walk(self): + kwargs = {'top': support.TESTFN} + self._compare_to_walk(kwargs, kwargs) + def test_dir_fd(self): + try: + fd = os.open(".", os.O_RDONLY) + walk_kwargs = {'top': support.TESTFN} + fwalk_kwargs = walk_kwargs.copy() + fwalk_kwargs['dir_fd'] = fd + self._compare_to_walk(walk_kwargs, fwalk_kwargs) + finally: + os.close(fd) + + def test_yields_correct_dir_fd(self): # check returned file descriptors for topdown, followlinks in itertools.product((True, False), repeat=2): args = support.TESTFN, topdown, None, followlinks diff --git a/Misc/NEWS b/Misc/NEWS index 24a1458..7f4a294 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -59,6 +59,8 @@ Core and Builtins Library ------- +- Issue #15177: Added dir_fd parameter to os.fwalk(). + - Issue #15176: Clarified behavior, documentation, and implementation of os.listdir(). -- cgit v0.12