From 5394e294efc67f08a618528f0186634a63ef4d64 Mon Sep 17 00:00:00 2001 From: jianwenzhou <118164769+zhou-jianwen@users.noreply.github.com> Date: Wed, 28 Oct 2026 14:23:30 +0800 Subject: [PATCH] Add pathlib-compatible recursive globbing --- newsfragments/214.feature.20261028.rst | 1 + path/__init__.py | 21 ++++++- tests/test_path.py | 84 ++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 newsfragments/214.feature.20261028.rst diff --git a/newsfragments/214.feature.20261028.rst b/newsfragments/214.feature.20261028.rst new file mode 100644 index 0000000..c5d2ae4 --- /dev/null +++ b/newsfragments/214.feature.20261028.rst @@ -0,0 +1 @@ +Added ``Path.rglob`` for lazy recursive globbing using host-platform ``pathlib`` matching semantics. diff --git a/path/__init__.py b/path/__init__.py index 731e88e..a87a060 100644 --- a/path/__init__.py +++ b/path/__init__.py @@ -643,7 +643,7 @@ def glob(self, pattern: str) -> list[Self]: .. seealso:: :func:`glob.glob` .. note:: Glob is **not** recursive, even when using ``**``. - To do recursive globbing see :func:`walk`, + To do recursive globbing see :meth:`rglob`, :func:`walk`, :func:`walkdirs` or :func:`walkfiles`. """ cls = self._next_class @@ -661,12 +661,29 @@ def iglob(self, pattern: str) -> Iterator[Self]: .. seealso:: :func:`glob.iglob` .. note:: Glob is **not** recursive, even when using ``**``. - To do recursive globbing see :func:`walk`, + To do recursive globbing see :meth:`rglob`, :func:`walk`, :func:`walkdirs` or :func:`walkfiles`. """ cls = self._next_class return (cls(s) for s in glob.iglob(self / pattern)) + def rglob(self, pattern: str) -> Iterator[Self]: + """Return an iterator of paths matching `pattern` recursively. + + `pattern` is relative to this directory. For example, + ``Path('/users').rglob('*.py')`` finds Python files at any depth. + + Matching follows :meth:`pathlib.Path.rglob` on the host platform, + including its case and separator rules, regardless of :attr:`module`. + Hidden files and directories are included. Recursive ``**`` expansion + does not follow directory symlinks, but the links themselves may match. + An explicit pattern segment may follow a named directory symlink. + + The filesystem is scanned lazily and results use ``self._next_class``. + """ + cls = self._next_class + return (cls(s) for s in pathlib.Path(self).rglob(pattern)) + # # --- Reading or writing an entire file at once. diff --git a/tests/test_path.py b/tests/test_path.py index 55d733c..814c153 100644 --- a/tests/test_path.py +++ b/tests/test_path.py @@ -15,6 +15,7 @@ import contextlib import datetime +import errno import importlib import ntpath import os @@ -401,6 +402,89 @@ def test_skip_symlinks(self, tmpdir): assert len(list(skip_links(root.walk()))) == 3 +class TestRglob: + @pytest.mark.parametrize('parent', ['root', 'root[1]']) + def test_matches(self, tmp_path, parent): + root = tmp_path / parent + names = ['top.txt', 'a/deep/file.txt', '.hidden.txt', '.hidden/file.txt'] + for name in names + ['a/other.bin']: + target = root / name + target.parent.mkdir(parents=True, exist_ok=True) + target.touch() + results = list(Path(root).rglob('*.txt')) + assert set(results) == {str(root / name) for name in names} + assert all(type(item) is Path for item in results) + assert list(Path(root).rglob('*.missing')) == [] + assert list(Path(root).rglob('deep/*.txt')) == [str(root / 'a/deep/file.txt')] + + def test_lazy(self, tmp_path): + root = tmp_path / 'later' + matches = Path(root).rglob('*.txt') + assert iter(matches) is matches + root.mkdir() + target = root / 'file.txt' + target.touch() + assert list(matches) == [str(target)] + + def test_subclass(self, tmp_path): + class SubPath(Path): + pass + + target = tmp_path / 'file.txt' + target.touch() + matches = list(SubPath(tmp_path).rglob('*.txt')) + assert matches == [str(target)] + assert type(matches[0]) is SubPath + + def test_captures_next_class(self, tmp_path, monkeypatch): + class SubPath(Path): + pass + + (tmp_path / 'file.txt').touch() + matches = SubPath(tmp_path).rglob('*.txt') + monkeypatch.setattr(SubPath, '_next_class', Path) + assert type(next(matches)) is SubPath + + def test_tempdir(self, tmp_path): + directory = TempDir(dir=tmp_path) + with directory: + target = (directory / 'file.txt').touch() + matches = list(directory.rglob('*.txt')) + assert matches == [target] + assert type(matches[0]) is Path + + @pytest.mark.parametrize('module', [ntpath, posixpath]) + @pytest.mark.parametrize('pattern', ['*.TXT', 'nested/*.txt', r'nested\*.txt']) + def test_host_semantics(self, tmp_path, module, pattern): + (tmp_path / 'nested').mkdir() + (tmp_path / 'nested/file.txt').touch() + (tmp_path / 'ROOT.txt').touch() + cls = Path.using_module(module) + matches = list(cls(tmp_path).rglob(pattern)) + assert set(matches) == {str(item) for item in tmp_path.rglob(pattern)} + assert all(type(item) is cls for item in matches) + + def test_directory_symlinks(self, tmp_path): + root = tmp_path / 'root' + root.mkdir() + outside = tmp_path / 'outside' + outside.mkdir() + (outside / 'file.txt').touch() + link = root / 'linked' + try: + link.symlink_to(outside, target_is_directory=True) + except OSError as exc: + if exc.errno in (errno.EPERM, errno.EACCES, errno.ENOSYS, errno.ENOTSUP): + pytest.skip(f'Directory symlinks unavailable: {exc}') + raise + assert list(Path(root).rglob('*')) == [str(link)] + assert list(root.rglob('*')) == [link] + assert list(Path(root).rglob('*.txt')) == [] + assert list(root.rglob('*.txt')) == [] + assert list(Path(root).rglob('linked/*.txt')) == [str(link / 'file.txt')] + assert list(root.rglob('linked/*.txt')) == [link / 'file.txt'] + + class TestSelfReturn: """ Some methods don't necessarily return any value (e.g. makedirs,