pathapi 0.1.0__py3-none-any.whl

pathapi/glob/_entries.py

@@ -0,0 +1,103 @@
+"""Listing a directory for the glob engine, and telling a directory from a link."""
+
+from __future__ import annotations
+
+import os as _os
+import pathlib as _pathlib
+import typing as _ty
+
+if _ty.TYPE_CHECKING:
+    from ..protocols._bundles import Walkable as _Walkable
+
+    _Globable = _ty.TypeVar("_Globable", bound=_Walkable)
+else:
+
+    class _Globable(_ty.Protocol): ...
+
+
+def _report_unlistable(path: _Globable, on_error) -> None:
+    """Tell `on_error` why `path` has nothing to select from (a missing path,
+    a file), in the words listing it would use."""
+    if on_error is not None:
+        _scan(path, on_error)
+
+
+def _scan(directory: _Globable, on_error=None):
+    """(child, non-following stat or None) per entry; nothing if listing
+    fails. Materialized so a lazily-raising listing is still caught here.
+
+    `on_error`, when given, is called as `on_error(error)` with the failure
+    -- the same contract as `Path.walk(on_error=)` and `os.walk`. Raising
+    from it propagates, which is how a caller turns an unreadable directory
+    back into an error; returning treats it as "nothing here", which is what
+    happens with no hook at all. `error.filename` is filled in with the
+    directory when the backend left it empty, so one argument is enough to
+    say where.
+    """
+    scandir = getattr(directory, "_scandir", None)
+    try:
+        if scandir is None:
+            return [(child, None) for child in directory.iterdir()]
+        return [(_child(directory, name, stat), stat) for name, stat in scandir()]
+    except OSError as error:
+        if on_error is not None:
+            if not getattr(error, "filename", None):
+                try:
+                    error.filename = str(directory)
+                except Exception:
+                    pass
+            on_error(error)
+        return ()
+
+
+def _identity(path: _Globable) -> "tuple | None":
+    """`(st_dev, st_ino)` of what `path` resolves to, or None when the
+    backend cannot say. Follows links deliberately: a Windows junction
+    reports `is_symlink() == False`, so its own metadata is no help --
+    `stat()` returning the TARGET's identity is what makes a loop visible.
+    """
+    try:
+        st = path.stat()
+    except (OSError, NotImplementedError, ValueError):
+        return None
+    dev = getattr(st, "st_dev", None)
+    ino = getattr(st, "st_ino", None)
+    # `st_ino` is zero where the filesystem reports no file identity; every
+    # directory would then share one key and look like its own ancestor.
+    if dev is None or not ino:
+        return None
+    return (dev, ino)
+
+
+def _is_hidden(path: _Globable) -> bool:
+    """Whether the final component of `path` starts with a dot."""
+    return path.name.startswith(".")
+
+
+def _child(directory: _Globable, name: str, stat=None) -> _Globable:
+    """The child of `directory` called exactly `name`, a name its listing
+    returned. A caller that has not checked it with `providers.is_safe_child_name()`
+    must, since a URI path joined with `/` resolves `..` and splits at `/`."""
+    if getattr(directory, "_pop_stat_hint", None) is not None:
+        # A URI path: the name is attached as one segment, and seeding the
+        # listing's stat saves a round trip per entry.
+        return directory._make_child_relpath(name, stat_hint=stat)
+    return directory / name
+
+
+def _names_a_directory(path: _Globable, lexists: bool) -> bool:
+    """Whether the literal `path`, given with a trailing separator, is a
+    directory. `lexists` is pathlib 3.13+'s test (see
+    `_DIRONLY_LITERAL_IS_LEXISTS`), made on the file `path` is; any other path
+    is a directory when it follows to one."""
+    if lexists and isinstance(path, _pathlib.Path):
+        return _os.path.lexists(_os.fspath(path) + _os.sep)
+    return path.is_dir()
+
+
+def _entry_is_dir(path: _Globable, stat, *, follow_symlinks: bool) -> bool:
+    if stat is not None and not (follow_symlinks and stat.is_symlink()):
+        return stat.is_dir()
+    if follow_symlinks:
+        return path.is_dir()
+    return path.is_dir() and not path.is_symlink()

pathapi/glob/_patterns.py

@@ -0,0 +1,164 @@
+"""Glob patterns: splitting a pattern into components and matching field by field."""
+
+from __future__ import annotations
+
+import fnmatch as _fnmatch
+import functools as _func
+import re as _re
+import sys as _sys
+import typing as _ty
+
+from ..exceptions import NonRelativePatternError
+
+RECURSIVE = "**"
+ANY_PATTERN = _re.compile(_fnmatch.translate("*"))
+WILDCARD_PATTERN = _re.compile("([*?[])")
+WILCARD_PATTERN = WILDCARD_PATTERN  # misspelled alias, kept for importers
+
+# Rules the running interpreter changed mid-series: honoured when `native=True`
+# (the default), smoothed over when it is False.
+#: A trailing "/" selects directories only from 3.11; before, pathlib ignores it.
+_TRAILING_SLASH_SELECTS_DIRS = _sys.version_info >= (3, 11)
+#: "**" recurses only as the WHOLE component; "a**" raises before 3.13 and is a
+#: plain wildcard from 3.13.
+_PARTIAL_DOUBLESTAR_ALLOWED = _sys.version_info >= (3, 13)
+
+
+@_func.lru_cache(maxsize=256, typed=True)
+def compile_pattern(pat: str, case_sensitive: bool):
+    # re.NOFLAG is 3.11+
+    flags = 0 if case_sensitive else _re.IGNORECASE
+    return _re.compile(_fnmatch.translate(pat), flags)
+
+
+def _collapse_recursive(parts: _ty.Iterable[str]) -> _ty.List[str]:
+    """Drop repeated consecutive "**" (they select the same paths)."""
+    collapsed: _ty.List[str] = []
+    for part in parts:
+        if part == RECURSIVE and collapsed and collapsed[-1] == RECURSIVE:
+            continue
+        collapsed.append(part)
+    return collapsed
+
+
+def _fields(segments: _ty.Sequence[str]) -> _ty.List[str]:
+    """`segments` as the fields of the path's "/"-joined text: the root is a
+    leading empty field (`["", ""]` for the root alone), the empty path has
+    none. Empty and "." segments are not names."""
+    rooted = bool(segments) and segments[0] == ""
+    names = [s for s in (segments[1:] if rooted else segments) if s and s != "."]
+    if rooted:
+        return ["", *names] if names else ["", ""]
+    return names
+
+
+def full_match(segments: _ty.Sequence[str], pattern: str, case_sensitive: bool) -> bool:
+    """Match `segments` against a glob pattern that may contain "**"
+    components (pathlib 3.13's PurePath.full_match semantics): a "**" matches
+    zero or more segments, except a trailing "**" after other components,
+    which needs at least one ("a/**" does not match "a").
+
+    The root is a field of its own, as in the path's text: a rooted pattern
+    names it with its leading "/", a lone "*" never matches it (a lone "*"
+    matches one or more characters), and a "**" followed by more components
+    reaches it only together with a name after it ("**/x" matches "/a/x",
+    not "/x"). Empty and "." components are dropped from the pattern. A
+    bracket expression never matches a separator (pathlib's regex lets a
+    negated one).
+
+    Runs as a set-of-states automaton, O(len(segments) * len(pattern)), so
+    repeated "**" cannot backtrack exponentially.
+    """
+    fields = _fields(segments)
+    parts = [part for part in pattern.split("/") if part and part != "."]
+    if pattern.startswith("/"):
+        parts = ["", *parts] if parts else ["", ""]
+    pats = _collapse_recursive(parts)
+    end = len(pats)
+    last = end - 1
+
+    # A state is (index, stage). Stage 0: about to match pats[index]. Stage 1 is a "**"
+    # that has taken one empty field (the root), which does not count yet; stage 2 has
+    # taken enough and may take more or hand over to the next component.
+    def closure(states: _ty.Set[_ty.Tuple[int, int]]) -> _ty.Set[_ty.Tuple[int, int]]:
+        pending = list(states)
+        while pending:
+            i, stage = pending.pop()
+            if stage == 2 or (
+                stage == 0
+                and i < end
+                and pats[i] == RECURSIVE
+                # A non-trailing (or sole) "**" may match no field at all.
+                and (i < last or end == 1)
+            ):
+                following = (i + 1, 0)
+                if following not in states:
+                    states.add(following)
+                    pending.append(following)
+        return states
+
+    states = closure({(0, 0)})
+    for field in fields:
+        advanced: _ty.Set[_ty.Tuple[int, int]] = set()
+        for i, stage in states:
+            if stage:
+                advanced.add((i, 2))
+            elif i == end:
+                continue
+            elif pats[i] == RECURSIVE:
+                advanced.add((i, 1 if field == "" and i < last else 2))
+            elif pats[i] == "*":
+                if field:
+                    advanced.add((i + 1, 0))
+            elif compile_pattern(pats[i], case_sensitive).match(field):
+                advanced.add((i + 1, 0))
+        if not advanced:
+            return False
+        states = closure(advanced)
+    return (end, 0) in states
+
+
+def parse_pattern(
+    pattern: "str | _ty.Any", *, native: bool = True
+) -> _ty.Tuple[_ty.List[str], bool]:
+    """Split a relative glob `pattern` (a `/`-separated string or a
+    `Pathname`) into its components, and report whether it ended with a
+    separator (directories only).
+
+    Raises `ValueError` for an empty pattern and `NonRelativePatternError`
+    for an absolute one, as `pathlib.Path.glob()` does. Empty and "."
+    components are dropped.
+
+    `native=True` (the default) follows the running interpreter on the two
+    rules pathlib changed mid-series: a trailing "/" is ignored before 3.11
+    (it selects directories only from 3.11), and a component that merely
+    CONTAINS "**" ("a**") raises `ValueError` before 3.13. `native=False`
+    applies one rule on every version instead -- a trailing "/" always
+    selects directories only, "a**" is always a plain wildcard -- so a
+    pattern gives the same answer on every interpreter and every backend.
+    """
+    if isinstance(pattern, str):
+        rooted = pattern.startswith("/")
+        segments = pattern.split("/")
+    else:
+        segments = list(pattern.segments)
+        rooted = bool(getattr(pattern, "anchor", "")) or bool(
+            getattr(pattern, "source", None)
+        )
+    if rooted:
+        raise NonRelativePatternError("Non-relative patterns are unsupported")
+    parts = [part for part in segments if part not in ("", ".")]
+    if not parts:
+        raise ValueError(f"Unacceptable pattern: {str(pattern)!r}")
+    if native and not _PARTIAL_DOUBLESTAR_ALLOWED:
+        for part in parts:
+            if RECURSIVE in part and part != RECURSIVE:
+                # pathlib's own message, so an `except ValueError` that reads
+                # it sees the same text it does on this interpreter.
+                raise ValueError(
+                    "Invalid pattern: '**' can only be an entire path component"
+                )
+    trailing_sep = bool(segments) and segments[-1] == ""
+    if native and not _TRAILING_SLASH_SELECTS_DIRS:
+        trailing_sep = False
+    return parts, trailing_sep

pathapi/glob/_recursion.py

@@ -0,0 +1,180 @@
+"""The recursive walk behind "**": loop and symlink guards."""
+
+from __future__ import annotations
+
+import typing as _ty
+
+from ._entries import _Globable, _entry_is_dir, _identity, _is_hidden, _scan
+
+#: Symlinks one descent may pass through when `recurse_symlinks=True` and the
+#: backend's stat carries no identity to tell a loop by: what the operating
+#: system allows in resolving one path.
+_MAX_LINK_TRAVERSALS = 40
+
+
+def _recurse(
+    top: _Globable,
+    include_hidden: bool,
+    with_files: bool,
+    on_error=None,
+    bound_loops: bool = False,
+    recurse_symlinks: bool = False,
+) -> _ty.Iterator[_Globable]:
+    """Yield `top` and every directory below it (plus every other entry when
+    `with_files`), never descending through a directory symlink unless
+    `recurse_symlinks` (see `_follow_guard()`).
+
+    With `bound_loops`, a directory whose identity (`st_dev`, `st_ino`) is
+    already on the CURRENT DESCENT PATH is skipped: that is what a loop is
+    -- a directory reachable below itself -- and it bounds a Windows
+    junction loop, which no symlink check can see (a junction reports
+    `is_symlink() == False`).
+
+    The ancestor chain is the whole rule, not a set of everything seen. One
+    directory deliberately reachable under two SIBLING names (a shared
+    config layer junctioned in as `site-a` and `site-b`) is not a loop: the
+    walk terminates, and both names must expand. A `visited` set spanning
+    the traversal dropped the second one silently. `find -L` draws the line
+    in the same place.
+
+    A backend whose stat has no identity cannot be bounded this way and is
+    walked unbounded.
+    """
+    yield top
+    top_key = _identity(top) if bound_loops else None
+    # Each stack entry carries the identities of the directories the walk is
+    # currently inside -- pushed on descent, dropped with the branch -- and,
+    # for `recurse_symlinks`, the directories themselves and the links passed.
+    stack = [(top, (top_key,) if top_key is not None else (), (top,), 0)]
+    while stack:
+        directory, ancestors, chain, links = stack.pop()
+        for child, stat in _scan(directory, on_error):
+            if not include_hidden and _is_hidden(child):
+                continue
+            is_dir = _entry_is_dir(child, stat, follow_symlinks=recurse_symlinks)
+            child_ancestors, child_chain, child_links = ancestors, chain, links
+            enter = is_dir
+            if is_dir:
+                if recurse_symlinks:
+                    # A link that would loop is still an entry, but not entered.
+                    enter, child_chain, child_links = _follow_guard(
+                        child, stat, chain, links
+                    )
+                if enter:
+                    descend, child_ancestors = _loop_guard(
+                        child, ancestors, bound_loops
+                    )
+                    if not descend:
+                        continue
+            if is_dir or with_files:
+                yield child
+            if enter:
+                stack.append((child, child_ancestors, child_chain, child_links))
+
+
+def _recurse_dirs(
+    top: _Globable,
+    include_hidden: bool,
+    on_error=None,
+    bound_loops: bool = False,
+    recurse_symlinks: bool = False,
+) -> _ty.Iterator[_ty.Tuple[_Globable, _ty.Sequence]]:
+    """`_recurse()` over directories only, as `(directory, its listing)`: the
+    caller lists each one next, and gets the listing that found the
+    directories below it instead of asking the backend again. Same order,
+    same loop rule. A directory waiting its turn keeps its subdirectories,
+    not its whole listing."""
+    entries = _scan(top, on_error)
+    yield top, entries
+    top_key = _identity(top) if bound_loops else None
+    stack = [
+        (
+            _subdirectories(entries, include_hidden, recurse_symlinks),
+            (top_key,) if top_key is not None else (),
+            (top,),
+            0,
+        )
+    ]
+    while stack:
+        children, ancestors, chain, links = stack.pop()
+        for child, stat in children:
+            child_chain, child_links = chain, links
+            if recurse_symlinks:
+                descend, child_chain, child_links = _follow_guard(
+                    child, stat, chain, links
+                )
+                if not descend:
+                    continue
+            descend, child_ancestors = _loop_guard(child, ancestors, bound_loops)
+            if not descend:
+                continue
+            entries = _scan(child, on_error)
+            yield child, entries
+            stack.append(
+                (
+                    _subdirectories(entries, include_hidden, recurse_symlinks),
+                    child_ancestors,
+                    child_chain,
+                    child_links,
+                )
+            )
+
+
+def _subdirectories(
+    entries, include_hidden: bool, recurse_symlinks: bool = False
+) -> "list[tuple[_Globable, _ty.Any]]":
+    """`(child, its listing stat)` for each directory among `entries`; through
+    a symlink to a directory only when `recurse_symlinks`."""
+    return [
+        (child, stat)
+        for child, stat in entries
+        if (include_hidden or not _is_hidden(child))
+        and _entry_is_dir(child, stat, follow_symlinks=recurse_symlinks)
+    ]
+
+
+def _follow_guard(child: _Globable, stat, chain: tuple, links: int):
+    """`(descend, chain, links)` for a directory `child` of the last
+    directory of `chain` (the directories the descent is inside, the top
+    first), `links` of which were entered through a symlink.
+
+    A directory reached through a symlink is not entered when it is one of
+    the directories already in `chain` -- a loop, which would match everything
+    under it again and again. Where the stat has no identity (most remote
+    backends) a link is not entered after 40 of them. A directory reached
+    without a link cannot close a loop by itself and costs no stat."""
+    if not _is_link(child, stat):
+        return True, chain + (child,), links
+    key = _identity(child)
+    if key is not None:
+        if any(_identity(directory) == key for directory in chain):
+            return False, chain, links
+    elif links >= _MAX_LINK_TRAVERSALS:
+        return False, chain, links
+    return True, chain + (child,), links + 1
+
+
+def _is_link(path: _Globable, stat) -> bool:
+    """Whether `path` is a symlink, by the listing's non-following stat when
+    there is one."""
+    if stat is not None:
+        return stat.is_symlink()
+    try:
+        return path.is_symlink()
+    except (OSError, NotImplementedError, ValueError):
+        return False
+
+
+def _loop_guard(child: _Globable, ancestors: tuple, bound_loops: bool):
+    """`(descend, identities of the directories child is inside)`. A child
+    that is one of its own ancestors is neither descended into nor yielded:
+    the next pattern component would match everything under it a second
+    time, through the loop."""
+    if not bound_loops:
+        return True, ancestors
+    key = _identity(child)
+    if key is None:
+        return True, ancestors
+    if key in ancestors:
+        return False, ancestors
+    return True, ancestors + (key,)