pathlib-next 0.9.7__tar.gz → 0.9.9__tar.gz

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.9] - 2026-09-17
+
+### Changed
+- **CI gains a URI-only job** (`test.yml`): the package installed with just
+  the `uri` extra and no scheme client at all, running the modules that must
+  work without one plus an explicit check that a pure-path join imports
+  nothing. Every other job installs all extras, which is why a join that
+  built a backend -- and so needed paramiko to spell an `sftp:` path --
+  survived from 0.9.3 to 0.9.8 behind a green matrix.
+
+### Fixed
+- **`glob(bound_loops=True)` no longer drops a directory shared under two
+  names.** It bounded on every identity seen during the walk, so one
+  directory junctioned in as both `site-a` and `site-b` -- a deliberate
+  layout, and not a loop -- expanded under the first name only, silently. A
+  loop is a directory reachable BELOW ITSELF, so the bound is now the
+  current descent path rather than everything seen, which is the line
+  `find -L` draws. The loop case is unchanged: 128 matches become 2.
+  Reported by yaconfiglib against 0.9.7.
+
+### Documentation
+- **Corrected the 0.9.8 entry's provenance.** It says 0.9.7 introduced the
+  join-builds-a-backend defect; it did not. Measured against the published
+  wheels in a venv with only the `uri` extra: `UriPath("sftp://h/mnt") / "c"`
+  raises `ImportError` on **0.9.3 and 0.9.6** as well, so the defect predates
+  the 0.9.7 join rewrite, which preserved it rather than causing it. 0.9.8
+  fixes it for the first time. (A related and DELIBERATE behaviour, unchanged
+  throughout: constructing an `http:`/`s3:` path at all requires that
+  scheme's extra, because the scheme module imports its client -- see the
+  extras table in the shipped header.)
+
+## [0.9.8] - 2026-09-17
+
+### Fixed
+- **Joining a URI path no longer builds a backend.** 0.9.7 routed `/` and
+  `joinpath()` through the child builder a listing uses, which reads the
+  `backend` property -- and that property CREATES one, so spelling
+  `UriPath("sftp://h/x") / "y"` imported paramiko and raised `ImportError`
+  without the extra (`http:` wanted `requests`, `s3:` `botocore`). A join
+  is a pure-path operation and is lazy again; a child still shares its
+  parent's connection when one already exists, which is all the sharing was
+  ever for.
+
 ## [0.9.7] - 2026-09-17
 
 ### Added
@@ -1450,7 +1493,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Sync error handling.
 - Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
 
-[Unreleased]: https://github.com/jose-pr/pathlib-next/compare/v0.9.7...HEAD
+[Unreleased]: https://github.com/jose-pr/pathlib-next/compare/v0.9.9...HEAD
+[0.9.9]: https://github.com/jose-pr/pathlib-next/compare/v0.9.8...v0.9.9
+[0.9.8]: https://github.com/jose-pr/pathlib-next/compare/v0.9.7...v0.9.8
 [0.9.7]: https://github.com/jose-pr/pathlib-next/compare/v0.9.6...v0.9.7
 [0.9.6]: https://github.com/jose-pr/pathlib-next/compare/v0.9.5...v0.9.6
 [0.9.5]: https://github.com/jose-pr/pathlib-next/compare/v0.9.4...v0.9.5

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pathlib-next
-Version: 0.9.7
+Version: 0.9.9
 Summary: Generic Path Protocol based pathlib
 Project-URL: Homepage, https://github.com/jose-pr/pathlib-next/
 Project-URL: Documentation, https://jose-pr.github.io/pathlib-next/

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/docs/divergences.md

@@ -57,7 +57,7 @@ these operations itself always keeps its own implementation.
 | `Uri("http://h/d/").name` (trailing `/`) | `PurePosixPath("d/").name == "d"` | A trailing `/` is kept: `name` is `""` and `parent` is `http://h/d`. | For HTTP/WebDAV a trailing slash is how a directory URL is spelled; normalizing it away changes which URL is requested. |
 | `Path.glob()` / `rglob()` edge cases | Version-dependent pathlib rules | Hidden entries are included by default (pathlib parity; `include_hidden=False` filters them). `recurse_symlinks=True` raises `NotImplementedError`: `**` never descends into directory symlinks. A trailing `**` follows the running interpreter (files too on 3.13+). The two rules pathlib changed mid-series follow the running interpreter by default (`native=True`): a trailing `/` is ignored before 3.11 and selects directories only from 3.11, and `a**` raises `ValueError` before 3.13 and is a plain wildcard from 3.13. `native=False` applies one rule on every version instead -- trailing `/` always selects directories only, `a**` is always a plain wildcard. | Loop-safe recursion without `st_dev`/`st_ino` (most backends' stats lack them) rules out following links. The `native` default keeps `LocalPath` answering exactly what the `pathlib` beside it answers; `native=False` is for a caller that wants one answer across backends and interpreters, which is what the contract suite asserts. |
 | `Path.glob(on_error=)` / `rglob(on_error=)` | `pathlib` skips an unreadable directory silently, with no hook | Same default, plus a hook: `on_error(error)` is called per failed listing (the contract `walk()` and `os.walk` use), so a caller can log it or raise it. `error.filename` names the directory. | "Silently nothing" is the worst answer for a caller assembling something from a tree -- a configuration layer, a source list -- because the result is incomplete and nothing says so. The default stays pathlib's. |
-| `Path.glob(bound_loops=)` / `rglob(bound_loops=)` | `pathlib` walks a directory loop until the recursion limit (and on Windows/3.9 eventually raises `WinError 1921` on the over-long path) | `bound_loops=True` descends a directory at most once per `**`, keyed on `(st_dev, st_ino)` and seeded with the starting directory; a directory reached a second way is skipped. Default `False` keeps pathlib's behaviour. | A Windows junction reports `is_symlink() == False`, so `recurse_symlinks=False` cannot see it and an ordinary config tree with a junction back into itself matched one file 64 times. Identity is the only signal that works; backends whose stats lack it are unaffected. |
+| `Path.glob(bound_loops=)` / `rglob(bound_loops=)` | `pathlib` walks a directory loop until the recursion limit (and on Windows/3.9 eventually raises `WinError 1921` on the over-long path) | `bound_loops=True` skips a directory whose `(st_dev, st_ino)` is already on the current descent path -- reachable below itself, which is what a loop is. A directory deliberately reachable under two sibling names still expands under both. Default `False` keeps pathlib's behaviour. | A Windows junction reports `is_symlink() == False`, so `recurse_symlinks=False` cannot see it and an ordinary config tree with a junction back into itself matched one file 128 times (and failed outright at `WinError 1921` on the path length). Identity is the only signal that works, and the ancestor chain is the part of it that means "loop" -- keying on everything seen also dropped a shared layer junctioned in twice. Backends whose stats lack identity are unaffected. |
 | `Path.glob(None)` / `rglob(None)` | `pathlib` has no such form (its pattern is always applied to a directory) | `None` expands the pattern THIS PATH CARRIES: `LocalPath("/etc/*.conf").glob(None)` splits at the first wildcard and globs from there (`utils.glob.glob()`). `glob("")` still raises `ValueError`, as pathlib does. | An extension: a path that is itself a pattern is a common shape for config and CLI inputs, and before 0.9.4 `glob("")` was the accidental spelling for it. `None` cannot collide with a real pattern, so parity is untouched. |
 | `Uri.query` | N/A (pathlib has no query) | The query is kept exactly as received (percent-encoded) and sent unchanged; `Query(...).decode()`/`to_dict()` decode. `Uri.parts` is `(source, path, query, fragment)`, not path segments (`segments` is). A `%2F` in a path decodes to `/` and is not distinguishable from a separator. | Decoding at parse time and re-encoding changed what reached the server (a signed URL's `%2B` became `+`, an escaped `&` split a value). The decoded-path model cannot keep `%2F` distinct. |
 | `Path.copy(follow_symlinks=False)` on a symlink | CPython 3.14: copies the link as a link | Same: the link is recreated (not its metadata). Where the source cannot `readlink()` or the target cannot create links, raises `NotImplementedError` instead of copying content. `copy(recursive=True)` into its own subtree raises `OSError(EINVAL)` before creating anything. | Copying the link target's content under the link's permissions produced a 0o777 regular file. |

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "hatchling.build"
 # `import pathlib_next`) -- a hyphen is not legal in a Python identifier.
 # Distribution name and import name differing is ordinary and intended.
 name = "pathlib-next"
-version = "0.9.7"
+version = "0.9.9"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/src/pathlib_next/AGENTS.md

@@ -103,14 +103,16 @@ silently absent and `from pathlib_next.uri import UriPath` raises
       skipped in silence (pathlib's behaviour), so a caller could not tell
       an unreadable directory from an absent one. `error.filename` names the
       directory even when the backend left it unset.
-    - **`bound_loops=True`** descends a directory at most once per `**`,
-      keyed on `(st_dev, st_ino)` and seeded with the starting directory. It
-      bounds a Windows junction loop, which `recurse_symlinks=False` cannot
-      (a junction reports `is_symlink() == False`) and which `pathlib`
-      itself walks until the recursion limit. A directory reached a second
-      way is skipped entirely, not just not descended. A backend whose stat
-      carries no identity (`MemPath`, most remote schemes) is walked
-      unbounded, as before.
+    - **`bound_loops=True`** skips a directory whose `(st_dev, st_ino)` is
+      already on the CURRENT DESCENT PATH — a directory reachable below
+      itself, which is what a loop is. It bounds a Windows junction loop,
+      which `recurse_symlinks=False` cannot (a junction reports
+      `is_symlink() == False`) and which `pathlib` itself walks until the
+      recursion limit. One directory deliberately reachable under two
+      SIBLING names (a shared layer junctioned in twice) is not a loop and
+      both names expand — the rule is the ancestor chain, not everything
+      seen, the same line `find -L` draws. A backend whose stat carries no
+      identity (`MemPath`, most remote schemes) is walked unbounded.
     - **`native=True`** (default) follows the running interpreter on the two
       rules pathlib changed mid-series: a trailing `/` is ignored before 3.11
       and selects directories only from 3.11; `a**` raises `ValueError`

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/src/pathlib_next/uri/__init__.py

@@ -1149,7 +1149,13 @@ class UriPath(Uri, Path):
     def _make_child_relpath(
         self, name: str, stat_hint: "FileStat" = None, **kwargs
     ) -> _ty.Self:
-        inst = super()._make_child_relpath(name, backend=self.backend, **kwargs)
+        # The backend ALREADY BUILT, never `self.backend` -- that property
+        # creates one, and naming a child is a pure-path operation: since
+        # `/` walks segments through here, reading the property made
+        # `UriPath("sftp://h/x") / "y"` import paramiko (and `http:` import
+        # requests) just to spell a path. A listing has one by the time it
+        # gets here, so its children still share the instance.
+        inst = super()._make_child_relpath(name, backend=self._backend, **kwargs)
         inst._stat_hint = stat_hint
         return inst
 

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/src/pathlib_next/utils/glob.py

@@ -337,39 +337,49 @@ def _recurse(
     """Yield `top` and every directory below it (plus every other entry when
     `with_files`), never descending through a directory symlink.
 
-    With `bound_loops`, a directory is descended at most once per `**`,
-    keyed on `(st_dev, st_ino)` and seeded with `top`: that bounds a Windows
+    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 entry itself is still yielded -- it exists
-    -- only the descent is skipped. A backend whose stat has no identity
-    cannot be bounded this way and is walked as before.
+    `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 as before.
     """
     yield top
-    visited = set()
-    if bound_loops:
-        key = _identity(top)
-        if key is not None:
-            visited.add(key)
-    stack = [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.
+    stack = [(top, (top_key,) if top_key is not None else ())]
     while stack:
-        directory = stack.pop()
+        directory, ancestors = stack.pop()
         for child, stat in _scan(directory, on_error):
             if not include_hidden and child.is_hidden():
                 continue
             is_dir = _entry_is_dir(child, stat, follow_symlinks=False)
+            child_ancestors = ancestors
             if is_dir and bound_loops:
                 key = _identity(child)
                 if key is not None:
-                    if key in visited:
-                        # Already walked under another name: a junction back
-                        # into the tree, or a second link to one directory.
-                        # Yielding it too would repeat everything under it.
+                    if key in ancestors:
+                        # The child IS one of its own ancestors: descending
+                        # would walk the same tree again, without end.
+                        # Skipped entirely -- yielding it would let the next
+                        # pattern component match everything under it a
+                        # second time, through the loop.
                         continue
-                    visited.add(key)
+                    child_ancestors = ancestors + (key,)
             if is_dir or with_files:
                 yield child
             if is_dir:
-                stack.append(child)
+                stack.append((child, child_ancestors))
 
 
 def _scan(directory: _Globable, on_error=None):

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/tests/test_glob_parity.py

@@ -479,3 +479,62 @@ def test_bound_loops_is_accepted_where_stats_have_no_identity():
     (mem / "s").mkdir()
     (mem / "s" / "x.py").write_text("x")
     assert [str(p) for p in mem.glob("**/*.py", bound_loops=True)] == ["/m/s/x.py"]
+
+
+def _junction(link, target):
+    """`mklink /J` returns 0 without elevation, unlike `os.symlink`."""
+    import subprocess
+
+    subprocess.run(
+        ["cmd", "/d", "/c", "mklink", "/J", str(link), str(target)],
+        check=True,
+        capture_output=True,
+    )
+
+
+@pytest.mark.skipif(os.name != "nt", reason="junctions are Windows")
+def test_bound_loops_keeps_a_directory_shared_under_two_names(tmp_path):
+    """A loop is a directory reachable BELOW ITSELF -- not one reachable
+    twice. Two sibling junctions onto one shared directory (a common config
+    layer linked in as `site-a` and `site-b`) is a deliberate layout that
+    terminates on its own, and both names must expand. Keying the bound on
+    everything seen dropped the second one silently."""
+    conf = tmp_path / "conf"
+    conf.mkdir()
+    (conf / "own.yaml").write_text("own")
+    shared = tmp_path / "shared"
+    shared.mkdir()
+    (shared / "common.yaml").write_text("common")
+    _junction(conf / "site-a", shared)
+    _junction(conf / "site-b", shared)
+
+    base = pathlib_next.LocalPath(tmp_path)
+    expected = sorted(
+        str(q.relative_to(tmp_path)).replace("\\", "/")
+        for q in base.glob("conf/**/*.yaml")
+    )
+    bounded = sorted(
+        str(q.relative_to(tmp_path)).replace("\\", "/")
+        for q in base.glob("conf/**/*.yaml", bound_loops=True)
+    )
+    assert "conf/site-b/common.yaml" in expected  # the default finds both
+    assert bounded == expected  # and so does the bounded walk
+
+
+@pytest.mark.skipif(os.name != "nt", reason="junctions are Windows")
+def test_bound_loops_still_bounds_a_loop_back_to_an_ancestor(tmp_path):
+    """The case the flag exists for: unbounded, the two real files are
+    matched 128 times (and a deeper walk fails outright on the path
+    length)."""
+    conf = tmp_path / "conf"
+    (conf / "deep").mkdir(parents=True)
+    (conf / "10-base.yaml").write_text("a")
+    (conf / "deep" / "20-extra.yaml").write_text("b")
+    _junction(conf / "deep" / "loop", conf)
+
+    base = pathlib_next.LocalPath(tmp_path)
+    assert len(list(base.glob("conf/**/*.yaml"))) > 2
+    assert sorted(q.name for q in base.glob("conf/**/*.yaml", bound_loops=True)) == [
+        "10-base.yaml",
+        "20-extra.yaml",
+    ]

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/tests/test_routing.py

@@ -74,7 +74,13 @@ def test_github_token_backend_does_not_follow_join_to_another_host():
     # A str join stays on the original host, so the token goes nowhere new.
     literal = root / "github://evil.invalid/x/y"
     assert literal.source.host == "github.com"
-    assert literal.backend is root.backend
+    assert literal.backend.token == "ghp_SECRET"
+    # Identity is only promised when the parent already HAS a backend: a
+    # join must not build one (it is a pure-path operation), so a child of a
+    # connectionless parent makes its own on first use.
+    assert root._backend is None
+    root.backend  # now it exists, and the next child shares it
+    assert (root / "docs").backend is root.backend
 
     # Crossing hosts needs a Uri argument, and that drops the token.
     evil = root / GitHubPath("github://evil.invalid/x/y")

{pathlib_next-0.9.7 → pathlib_next-0.9.9}/tests/test_uri_path.py

@@ -357,3 +357,35 @@ def test_a_same_endpoint_uri_destination_keeps_the_configured_backend():
         base._coerce_target("http://trusted.invalid/api/b.txt").backend is base.backend
     )
     assert base._coerce_target("http://other.invalid/b.txt").backend is not base.backend
+
+
+def test_joining_a_path_never_builds_a_backend():
+    """A join is a PURE-PATH operation. 0.9.7 routed `/` through
+    `_make_child_relpath()`, which read the `backend` property -- and that
+    property builds one, so spelling `UriPath("sftp://h/x") / "y"` imported
+    paramiko and raised ImportError without the extra. Every scheme, not
+    just the ones whose client happens to be installed."""
+    # Schemes whose class module does not import a client at import time.
+    # (`http:`/`s3:` cannot even be CONSTRUCTED without their extra -- that
+    # is deliberate and documented, and a separate matter from joining.)
+    # (`zip:`/`tar:` are left out on purpose: their "backend" is the shared
+    # archive handle from the registry, stdlib-only and opened lazily, so it
+    # is attached at construction and a join inherits it.)
+    for uri in ("sftp://h/mnt", "file:///tmp/x", "data:,abc"):
+        base = UriPath(uri)
+        child = base / "child"
+        assert child.path.endswith("/child")
+        assert child._backend is None, uri
+        assert base._backend is None, uri
+        assert base.joinpath("a", "b")._backend is None, uri
+
+
+def test_joining_shares_a_backend_that_already_exists():
+    """What the property read was there for: children of a listing share the
+    parent's live connection. That still holds -- by then it exists."""
+    base = UriPath("sftp://h/mnt")
+    sentinel = object()
+    base._backend = sentinel
+    assert (base / "c")._backend is sentinel
+    assert base.joinpath("c", "d")._backend is sentinel
+    assert base._make_child_relpath("c")._backend is sentinel