dissect.target 3.14.dev28__py3-none-any.whl → 3.15__py3-none-any.whl

dissect/target/helpers/fsutil.py

@@ -1,20 +1,16 @@
-"""Pathlib like abstraction helpers for target filesystem.
-
-Also contains some other filesystem related utilities.
-"""
+"""Filesystem and path related utilities."""
 
 from __future__ import annotations
 
-import errno
 import fnmatch
 import gzip
 import hashlib
 import io
 import logging
 import os
-import posixpath
 import re
-from pathlib import Path, PurePath, _PathParents, _PosixFlavour
+import sys
+from pathlib import Path
 from typing import Any, BinaryIO, Iterator, Optional, Sequence, TextIO, Union
 
 try:
@@ -25,66 +21,67 @@ except ImportError:
     HAVE_BZ2 = False
 
 import dissect.target.filesystem as filesystem
-from dissect.target.exceptions import (
-    FileNotFoundError,
-    NotADirectoryError,
-    NotASymlinkError,
-    SymlinkRecursionError,
+from dissect.target.exceptions import FileNotFoundError, SymlinkRecursionError
+from dissect.target.helpers.polypath import (
+    abspath,
+    basename,
+    commonpath,
+    dirname,
+    isabs,
+    join,
+    normalize,
+    normpath,
+    relpath,
+    split,
+    splitdrive,
+    splitext,
+    splitroot,
 )
 
-log = logging.getLogger(__name__)
-
-re_normalize_path = re.compile(r"[/]+")
-re_normalize_sbs_path = re.compile(r"[\\/]+")
-re_glob_magic = re.compile(r"[*?[]")
-re_glob_index = re.compile(r"(?<=\/)[^\/]*[*?[]\/?")
-
-
-def normalize(path: str, alt_separator: str = "") -> str:
-    if alt_separator == "\\":
-        return re_normalize_sbs_path.sub("/", path)
-    else:
-        return re_normalize_path.sub("/", path)
-
-
-def join(*args, alt_separator: str = "") -> str:
-    return posixpath.join(*[normalize(part, alt_separator=alt_separator) for part in args])
-
-
-def dirname(path: str, alt_separator: str = "") -> str:
-    return posixpath.dirname(normalize(path, alt_separator=alt_separator))
-
-
-def basename(path: str, alt_separator: str = "") -> str:
-    return posixpath.basename(normalize(path, alt_separator=alt_separator))
+if sys.version_info >= (3, 12):
+    from dissect.target.helpers.compat.path_312 import PureDissectPath, TargetPath
+elif sys.version_info >= (3, 11):
+    from dissect.target.helpers.compat.path_311 import PureDissectPath, TargetPath
+elif sys.version_info >= (3, 10):
+    from dissect.target.helpers.compat.path_310 import PureDissectPath, TargetPath
+elif sys.version_info >= (3, 9):
+    from dissect.target.helpers.compat.path_39 import PureDissectPath, TargetPath
+else:
+    raise RuntimeError("dissect.target requires at least Python 3.9")
 
 
-def split(path: str, alt_separator: str = "") -> str:
-    return posixpath.split(normalize(path, alt_separator=alt_separator))
-
-
-def isabs(path: str, alt_separator: str = "") -> str:
-    return posixpath.isabs(normalize(path, alt_separator=alt_separator))
-
-
-def normpath(path: str, alt_separator: str = "") -> str:
-    return posixpath.normpath(normalize(path, alt_separator=alt_separator))
-
-
-def abspath(path: str, cwd: str = "", alt_separator: str = "") -> str:
-    cwd = cwd or "/"
-    cwd = normalize(cwd, alt_separator=alt_separator)
-    path = normalize(path, alt_separator=alt_separator)
-    if not isabs(path):
-        path = join(cwd, path)
-    return posixpath.normpath(path)
-
+log = logging.getLogger(__name__)
 
-def relpath(path: str, start: str, alt_separator: str = "") -> str:
-    return posixpath.relpath(
-        normalize(path, alt_separator=alt_separator),
-        normalize(start, alt_separator=alt_separator),
-    )
+re_glob_magic = re.compile(r"[*?[]")
+re_glob_index = re.compile(r"(?<=\/)[^\/]*[*?[]")
+
+__all__ = [
+    "abspath",
+    "basename",
+    "commonpath",
+    "dirname",
+    "fs_attrs",
+    "generate_addr",
+    "glob_ext",
+    "glob_split",
+    "isabs",
+    "join",
+    "normalize",
+    "normpath",
+    "open_decompress",
+    "PureDissectPath",
+    "relpath",
+    "resolve_link",
+    "reverse_readlines",
+    "split",
+    "splitdrive",
+    "splitext",
+    "splitroot",
+    "stat_result",
+    "TargetPath",
+    "walk_ext",
+    "walk",
+]
 
 
 def generate_addr(path: Union[str, Path], alt_separator: str = "") -> int:
@@ -94,9 +91,6 @@ def generate_addr(path: Union[str, Path], alt_separator: str = "") -> int:
     return int(hashlib.sha256(path.encode()).hexdigest()[:8], 16)
 
 
-splitext = posixpath.splitext
-
-
 class stat_result:  # noqa
     """Custom stat_result object, designed to mimick os.stat_result.
 
@@ -240,583 +234,6 @@ class stat_result:  # noqa
         return st
 
 
-# fmt: off
-"""
-A pathlib.Path compatible implementation for dissect.target starts here. This allows for the
-majority of the pathlib.Path API to "just work" on dissect.target filesystems.
-
-Most of this consists of subclassed internal classes with dissect.target specific patches,
-but sometimes the change to a function is small, so the entire internal function is copied
-and only a small part changed. To ease updating this code, the order of functions, comments
-and code style is kept exactly the same as the original pathlib.py.
-
-Yes, we know, this is playing with fire and it can break on new CPython releases.
-
-Commit hash of CPython we're currently in sync with: 9f101c23a41e739f5f80cf38419df1281835d452
-
-Notes:
-- CPython 3.11 ditched the _Accessor class, so we override the methods that should use it
-"""
-
-
-class _DissectFlavour(_PosixFlavour):
-    is_supported = True
-
-    __variant_instances = {}
-
-    def __new__(cls, case_sensitive=False, alt_separator=None):
-        idx = (case_sensitive, alt_separator)
-        instance = cls.__variant_instances.get(idx, None)
-        if instance is None:
-            instance = _PosixFlavour.__new__(cls)
-            cls.__variant_instances[idx] = instance
-
-        return instance
-
-    def __init__(self, case_sensitive=False, alt_separator=""):
-        super().__init__()
-        self.altsep = alt_separator
-        self.case_sensitive = case_sensitive
-
-    def casefold(self, s):
-        return s if self.case_sensitive else s.lower()
-
-    def casefold_parts(self, parts):
-        return parts if self.case_sensitive else [p.lower() for p in parts]
-
-    def compile_pattern(self, pattern):
-        return re.compile(fnmatch.translate(pattern), 0 if self.case_sensitive else re.IGNORECASE).fullmatch
-
-    # CPython <= 3.9
-    def resolve(self, path, strict=False):
-        sep = self.sep
-        accessor = path._accessor
-        seen = {}
-
-        def _resolve(fs, path, rest):
-            if rest.startswith(sep):
-                path = ''
-
-            for name in rest.split(sep):
-                if not name or name == '.':
-                    # current dir
-                    continue
-                if name == '..':
-                    # parent dir
-                    path, _, _ = path.rpartition(sep)
-                    continue
-                if path.endswith(sep):
-                    newpath = path + name
-                else:
-                    newpath = path + sep + name
-                if newpath in seen:
-                    # Already seen this path
-                    path = seen[newpath]
-                    if path is not None:
-                        # use cached value
-                        continue
-                    # The symlink is not resolved, so we must have a symlink loop.
-                    raise RuntimeError("Symlink loop from %r" % newpath)
-                # Resolve the symbolic link
-                try:
-                    target = accessor.readlink(fs.path(newpath))
-                except OSError as e:
-                    if e.errno != errno.EINVAL and strict:
-                        raise
-                    # Not a symlink, or non-strict mode. We just leave the path
-                    # untouched.
-                    path = newpath
-                else:
-                    seen[newpath] = None  # not resolved symlink
-                    path = _resolve(fs, path, target)
-                    seen[newpath] = path  # resolved symlink
-
-            return path
-
-        return _resolve(path._fs, '', str(path)) or sep
-
-    # CPython <= 3.9
-    def gethomedir(self, username):
-        raise NotImplementedError()
-
-
-def _get_oserror(path):
-    # We emulate some OSError exceptions to play nice with pathlib
-    try:
-        return path.get()
-    except FileNotFoundError:
-        e = OSError(errno.ENOENT)
-        e.errno = errno.ENOENT
-        raise e
-    except NotADirectoryError:
-        e = OSError(errno.ENOTDIR)
-        e.errno = errno.ENOTDIR
-        raise e
-
-
-class _DissectScandirIterator:
-    """This class implements a ScandirIterator for dissect's scandir()
-
-    The _DissectScandirIterator provides a context manager, so scandir can be called as:
-
-    ```
-    with scandir(path) as it:
-        for entry in it
-            print(entry.name)
-    ```
-
-    similar to os.scandir() behaviour since Python 3.6.
-    """
-
-    def __init__(self, iterator):
-        self._iterator = iterator
-
-    def __del__(self):
-        self.close()
-
-    def __enter__(self):
-        return self._iterator
-
-    def __exit__(self, *args, **kwargs):
-        return False
-
-    def __iter__(self):
-        return self._iterator
-
-    def __next__(self, *args):
-        return next(self._iterator, *args)
-
-    def close(self):
-        # close() is not defined in the various filesystem implementations. The
-        # python ScandirIterator does define the interface however.
-        pass
-
-
-class _DissectAccessor:
-    # CPython >= 3.10
-    @staticmethod
-    def stat(path, follow_symlinks=True):
-        if follow_symlinks:
-            return path.get().stat()
-        else:
-            return path.get().lstat()
-
-    # CPython <= 3.9
-    @staticmethod
-    def lstat(path):
-        return path.get().lstat()
-
-    @staticmethod
-    def open(path, mode='rb', buffering=0, encoding=None,
-             errors=None, newline=None, *args, **kwargs):
-        """Open file and return a stream.
-
-        Supports a subset of features of the real pathlib.open/io.open.
-
-        Note: in contrast to regular Python, the mode is binary by default. Text mode
-        has to be explicitly specified. Buffering is also disabled by default.
-        """
-        modes = set(mode)
-        if modes - set('rbt') or len(mode) > len(modes):
-            raise ValueError("invalid mode: %r" % mode)
-
-        reading = 'r' in modes
-        binary = 'b' in modes
-        text = 't' in modes or 'b' not in modes
-
-        if not reading:
-            raise ValueError("must be reading mode")
-        if text and binary:
-            raise ValueError("can't have text and binary mode at once")
-        if binary and encoding is not None:
-            raise ValueError("binary mode doesn't take an encoding argument")
-        if binary and errors is not None:
-            raise ValueError("binary mode doesn't take an errors argument")
-        if binary and newline is not None:
-            raise ValueError("binary mode doesn't take a newline argument")
-
-        raw = path.get().open()
-        result = raw
-
-        line_buffering = False
-        if buffering == 1 or buffering < 0 and raw.isatty():
-            buffering = -1
-            line_buffering = True
-        if buffering < 0 or text and buffering == 0:
-            buffering = io.DEFAULT_BUFFER_SIZE
-        if buffering == 0:
-            if binary:
-                return result
-            raise ValueError("can't have unbuffered text I/O")
-
-        buffer = io.BufferedReader(raw, buffering)
-        result = buffer
-        if binary:
-            return result
-
-        result = io.TextIOWrapper(buffer, encoding, errors, newline, line_buffering)
-        result.mode = mode
-
-        return result
-
-    @staticmethod
-    def listdir(path):
-        return path.get().listdir()
-
-    @staticmethod
-    def scandir(path):
-        return _DissectScandirIterator(path.get().scandir())
-
-    @staticmethod
-    def chmod(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def lchmod(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def mkdir(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def unlink(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython >= 3.10
-    @staticmethod
-    def link(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython <= 3.9
-    @staticmethod
-    def link_to(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def rmdir(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def rename(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def replace(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def symlink(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython >= 3.10
-    @staticmethod
-    def touch(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython <= 3.9
-    @staticmethod
-    def utime(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def readlink(path):
-        entry = _get_oserror(path)
-        if not entry.is_symlink():
-            e = OSError(errno.EINVAL)
-            e.errno = errno.EINVAL
-            raise e
-        return entry.readlink()
-
-    @staticmethod
-    def owner(*args, **kwargs):
-        raise NotImplementedError()
-
-    @staticmethod
-    def group(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython >= 3.10
-    @staticmethod
-    def getcwd(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython >= 3.10
-    @staticmethod
-    def expanduser(*args, **kwargs):
-        raise NotImplementedError()
-
-    # CPython >= 3.10
-    @staticmethod
-    def realpath(*args, **kwargs):
-        raise NotImplementedError()
-
-
-_dissect_accessor = _DissectAccessor()
-
-
-class _DissectPathParents(_PathParents):
-    __slots__ = ('_fs')
-
-    def __init__(self, path):
-        super().__init__(path)
-        self._fs = path._fs
-        self._flavour = path._flavour
-
-    def __getitem__(self, idx):
-        result = super().__getitem__(idx)
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-
-class PureDissectPath(PurePath):
-    _flavour = _DissectFlavour(case_sensitive=False)
-
-    def __reduce__(self):
-        raise TypeError("pickling is currently not supported")
-
-    @classmethod
-    def _from_parts(cls, args, *_args, **_kwargs):
-        fs = args[0]
-
-        if not isinstance(fs, filesystem.Filesystem):
-            raise TypeError(
-                "invalid PureDissectPath initialization: missing filesystem, "
-                "got %r (this might be a bug, please report)"
-                % args
-            )
-
-        alt_separator = fs.alt_separator
-        path_args = []
-        for arg in args[1:]:
-            if isinstance(arg, str):
-                arg = normalize(arg, alt_separator=alt_separator)
-            path_args.append(arg)
-
-        self = super()._from_parts(path_args, *_args, **_kwargs)
-        self._fs = fs
-
-        self._flavour = _DissectFlavour(
-            alt_separator=fs.alt_separator,
-            case_sensitive=fs.case_sensitive
-        )
-
-        return self
-
-    def _make_child(self, args):
-        child = super()._make_child(args)
-        child._fs = self._fs
-        child._flavour = self._flavour
-        return child
-
-    def with_name(self, name):
-        result = super().with_name(name)
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-    def with_stem(self, stem):
-        result = super().with_stem(stem)
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-    def with_suffix(self, suffix):
-        result = super().with_suffix(suffix)
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-    def relative_to(self, *other):
-        result = super().relative_to(*other)
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-    def __rtruediv__(self, key):
-        try:
-            return self._from_parts([self._fs, key] + self._parts)
-        except TypeError:
-            return NotImplemented
-
-    @property
-    def parent(self):
-        result = super().parent
-        result._fs = self._fs
-        result._flavour = self._flavour
-        return result
-
-    @property
-    def parents(self):
-        return _DissectPathParents(self)
-
-
-class TargetPath(Path, PureDissectPath):
-    # CPython >= 3.10
-    _accessor = _dissect_accessor
-    __slots__ = '_entry'
-
-    # CPython <= 3.9
-    def _init(self, template=None):
-        self._accessor = _dissect_accessor
-
-    def _make_child_relpath(self, part):
-        child = super()._make_child_relpath(part)
-        child._fs = self._fs
-        child._flavour = self._flavour
-        return child
-
-    def get(self):
-        try:
-            return self._entry
-        except AttributeError:
-            self._entry = self._fs.get(str(self))
-            return self._entry
-
-    @classmethod
-    def cwd(cls):
-        raise NotImplementedError()
-
-    @classmethod
-    def home(cls):
-        raise NotImplementedError()
-
-    def iterdir(self):
-        for entry in self._accessor.scandir(self):
-            if entry.name in {'.', '..'}:
-                # Yielding a path object for these makes little sense
-                continue
-            child_path = self._make_child_relpath(entry.name)
-            child_path._entry = entry
-            yield child_path
-
-    def _scandir(self):
-        return self._accessor.scandir(self)
-
-    def absolute(self):
-        raise NotImplementedError()
-
-    def resolve(self, strict=False):
-        s = self._flavour.resolve(self)
-        if s is None:
-            # No symlink resolution => for consistency, raise an error if
-            # the path doesn't exist or is forbidden
-            self.stat()
-            s = str(self.absolute())
-        # Now we have no symlinks in the path, it's safe to normalize it.
-        normed = self._flavour.pathmod.normpath(s)
-        obj = self._from_parts((self._fs, normed,))
-        return obj
-
-    # CPython >= 3.11
-    def stat(self, *, follow_symlinks=True):
-        """
-        Return the result of the stat() system call on this path, like
-        os.stat() does.
-        """
-        return self._accessor.stat(self, follow_symlinks=follow_symlinks)
-
-    def owner(self):
-        raise NotImplementedError()
-
-    def group(self):
-        raise NotImplementedError()
-
-    def open(self, mode='rb', buffering=0, encoding=None,
-             errors=None, newline=None):
-
-        if "b" not in mode:
-            encoding = encoding or "UTF-8"
-            # CPython >= 3.10
-            if hasattr(io, "text_encoding"):
-                # Vermin linting needs to be skipped for this line as this is
-                # guarded by an explicit check for availability.
-                # novermin
-                encoding = io.text_encoding(encoding)
-        return self._accessor.open(self, mode, buffering, encoding, errors,
-                                   newline)
-
-    def write_bytes(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def write_text(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def readlink(self):
-        """
-        Return the path to which the symbolic link points.
-        """
-        path = self._accessor.readlink(self)
-        obj = self._from_parts((self._fs, path,))
-        return obj
-
-    def touch(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def mkdir(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def chmod(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def lchmod(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def unlink(self):
-        raise NotImplementedError()
-
-    def rmdir(self):
-        raise NotImplementedError()
-
-    def rename(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def replace(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def symlink_to(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def hardlink_to(self, target):
-        raise NotImplementedError()
-
-    def link_to(self, *args, **kwargs):
-        raise NotImplementedError()
-
-    def exists(self):
-        try:
-            # .exists() must resolve possible symlinks
-            self.get().stat()
-            return True
-        except (FileNotFoundError, NotADirectoryError, NotASymlinkError, SymlinkRecursionError, ValueError):
-            return False
-
-    def is_dir(self):
-        try:
-            return self.get().is_dir()
-        except (FileNotFoundError, NotADirectoryError, NotASymlinkError, SymlinkRecursionError, ValueError):
-            return False
-
-    def is_file(self):
-        try:
-            return self.get().is_file()
-        except (FileNotFoundError, NotADirectoryError, NotASymlinkError, SymlinkRecursionError, ValueError):
-            return False
-
-    def is_symlink(self):
-        try:
-            return self.get().is_symlink()
-        except (FileNotFoundError, NotADirectoryError, NotASymlinkError, SymlinkRecursionError, ValueError):
-            return False
-
-    def expanduser(self):
-        raise NotImplementedError()
-
-
-# fmt: on
-
-
 def walk(path_entry, topdown=True, onerror=None, followlinks=False):
     for path_list, dirs, files in walk_ext(path_entry, topdown, onerror, followlinks):
         dir_names = [d.name for d in dirs]
@@ -857,7 +274,17 @@ def walk_ext(path_entry, topdown=True, onerror=None, followlinks=False):
         yield [path_entry], dirs, files
 
 
-def glob_split(pattern: str, alt_separator: str = "") -> str:
+def glob_split(pattern: str, alt_separator: str = "") -> tuple[str, str]:
+    """Split a pattern on path part boundaries on the first path part with a glob pattern.
+
+    Args:
+        pattern: A glob pattern to match names of filesystem entries against.
+        alt_separator: An optional alternative path separator in use by the filesystem being matched.
+
+    Returns:
+        A tuple of a string with path parts up to the first path part that has a glob pattern and a string of
+        the remaining path parts.
+    """
     # re_glob_index expects a normalized pattern
     pattern = normalize(pattern, alt_separator=alt_separator)
 
@@ -870,75 +297,110 @@ def glob_split(pattern: str, alt_separator: str = "") -> str:
     return pattern[:pos], pattern[pos:]
 
 
-def glob_ext(direntry: filesystem.FilesystemEntry, pattern: str) -> filesystem.FilesystemEntry:
+def glob_ext(direntry: filesystem.FilesystemEntry, pattern: str) -> Iterator[filesystem.FilesystemEntry]:
+    """Recursively search and return filesystem entries matching a given glob pattern.
+
+    Args:
+        direntry: The filesystem entry relative to which to search.
+        pattern: A glob pattern to match names of filesystem entries against.
+
+    Yields:
+        Matching filesystem entries (files and/or directories).
+    """
+
+    # Split the pattern on the last path part. base_name will contain the last path part (which is
+    # '' if pattern ends with a /) and dir_name will contain the other parts.
     dir_name, base_name = split(pattern, alt_separator=direntry.fs.alt_separator)
 
+    # The simple case where there are no globs.
     if not has_glob_magic(pattern):
         try:
             entry = direntry.get(pattern)
         except FileNotFoundError:
             pass
         else:
+            # Patterns ending with a slash, so without a base_name, should match only directories.
             if base_name:
                 yield entry
-            # Patterns ending with a slash should match only directories
             elif entry.is_dir():
                 yield entry
         return
 
+    # The pattern has only one path part, so we can match directly against the files in direntry.
     if not dir_name:
         for entry in glob_ext1(direntry, base_name):
             yield entry
         return
 
-    if dir_name != pattern and has_glob_magic(dir_name):
-        dirs = glob_ext(direntry, dir_name)
+    # If the pattern has more than one path part and these parts (dir_name) contain globs, we
+    # recursively go over all the path parts and match them (glob_ext).
+    # If these path parts have no globs, we get the path directly by name (glob_ext0).
+    if has_glob_magic(dir_name):
+        glob_in_dir = glob_ext
     else:
-        dirs = [dir_name]
+        glob_in_dir = glob_ext0
 
+    # If the pattern's last path part (base_name) has globs, we fnmatch it against the entries in
+    # direntry (glob_ext1), otherwise we get the part directly by name (glob_ext0).
     if has_glob_magic(base_name):
-        glob_in_dir = glob_ext1
+        glob_in_base = glob_ext1
     else:
-        glob_in_dir = glob_ext0
+        glob_in_base = glob_ext0
 
-    for direntry in dirs:
-        for entry in glob_in_dir(direntry, base_name):
+    for direntry in glob_in_dir(direntry, dir_name):
+        for entry in glob_in_base(direntry, base_name):
             yield entry
 
 
 # These 2 helper functions non-recursively glob inside a literal directory.
-# They return a list of basenames. `glob1` accepts a pattern while `glob0`
-# takes a literal base_name (so it only has to check for its existence).
+def glob_ext1(direntry: filesystem.FilesystemEntry, pattern: str) -> Iterator[filesystem.FilesystemEntry]:
+    """Match and return filesystem entries in a given filesystem entry based on pattern.
 
+    Args:
+        direntry: The filesystem entry relative to which to match the entries.
+        pattern: A glob pattern to match names of filesystem entries against.
 
-def glob_ext1(direntry: filesystem.FilesystemEntry, pattern: str) -> filesystem.FilesystemEntry:
+    Yields:
+        Matching filesystem entries (files and/or directories).
+    """
     if not direntry.is_dir():
         return
 
     entries = direntry.scandir()
 
     if pattern[0] != ".":
+        # Do not return dot-files, unless they are explicitly searched for.
         entries = filter(lambda x: x.name[0] != ".", entries)
 
-    for e in entries:
-        name = e.name if e.fs.case_sensitive else e.name.lower()
-        pattern = pattern if e.fs.case_sensitive else pattern.lower()
+    for entry in entries:
+        case_sensitive = entry.fs.case_sensitive
+        name = entry.name if case_sensitive else entry.name.lower()
+        pattern = pattern if case_sensitive else pattern.lower()
         if fnmatch.fnmatch(name, pattern):
-            yield e
+            yield entry
+
 
+def glob_ext0(direntry: filesystem.FilesystemEntry, path: str) -> Iterator[filesystem.FilesystemEntry]:
+    """Return the filesystem entry equal to the given path relative to direntry.
 
-def glob_ext0(direntry: filesystem.FilesystemEntry, base_name: str) -> list[filesystem.FilesystemEntry]:
-    if base_name == "":
-        # `os.path.split()` returns an empty base_name for paths ending with a
-        # directory separator.  'q*x/' should match only directories.
+    Args:
+        direntry: The filesystem entry relative to which to return the path.
+        path: The path to the filesystem entry to return (if present). If path
+              is an empty string (``''``) the ``direntry`` itself is returned.
+
+    Yields:
+        The matching filesystem entry (file or directory).
+    """
+    if path == "":
+        # os.path.split() returns an empty path for paths ending with a directory separator.
+        # E.g. 'q*x/' should match only directories.
         if direntry.is_dir():
-            return [direntry]
+            yield direntry
     elif direntry.is_dir():
         try:
-            return [direntry.get(base_name)]
+            yield direntry.get(path)
         except FileNotFoundError:
             pass
-    return []
 
 
 def has_glob_magic(s) -> bool: