pathlib-next 0.9.6__tar.gz → 0.9.8__tar.gz

{pathlib_next-0.9.6 → pathlib_next-0.9.8}/CHANGELOG.md

@@ -7,6 +7,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+- **`rm(follow_symlinks=, follow_binds=)`**: what a recursive removal does
+  with a symlink, and with a binding (a Windows junction, a mount point).
+  Each takes `False` (the default -- remove the entry itself, never its
+  contents, as `rm -r` does), `True` (remove what is behind it), `None`
+  (leave it in place, so the enclosing directory is not empty and reports
+  it), or a callable `policy(path) -> bool | None` asked per entry, so one
+  tree can keep one mount and follow another. Named for the keyword
+  `stat()`, `walk()` and `copy()` already use for the same idea, rather
+  than a second vocabulary.
+- **`Path.is_junction()`, `Path.is_mount()` and `Path.is_dir_binding()`**:
+  a directory that is another tree's second NAME -- a Windows junction, or
+  a mount point such as a Linux bind mount -- is now a first-class concept
+  rather than a private hook used by one call site. Neither is a symlink
+  (`is_symlink()` is False, a non-following stat reports a plain
+  directory), which is precisely why a symlink check cannot protect a walk
+  from one. `is_junction()` matches pathlib 3.12's; both are False by
+  default and answered for real by `LocalPath`/`FileUri`.
+
+- **`Path.glob(on_error=)` / `rglob(on_error=)`**: a hook called as
+  `on_error(error)` when a directory cannot be listed, the same contract as
+  `walk()` and `os.walk`. Raising from it makes an unreadable directory
+  fatal; returning treats it as empty. Without the hook the listing is
+  skipped silently, as pathlib does and as before -- which left a caller
+  unable to tell an unreadable layer from an absent one. `error.filename`
+  names the directory even when the backend left it unset.
+- **`Path.glob(bound_loops=)` / `rglob(bound_loops=)`**: with `True`, a
+  directory is descended at most once per `**`, keyed on
+  `(st_dev, st_ino)` and seeded with the starting directory. This bounds a
+  Windows junction loop -- a junction reports `is_symlink() == False`, so
+  `recurse_symlinks=False` cannot see it, and one file in a looping tree
+  matched 64 times (pathlib walks it the same way). Default `False` keeps
+  pathlib's behaviour; a backend whose stat carries no identity is walked
+  unbounded. Both reported by yaconfiglib against 0.9.6.
+
+### Fixed
+- **An SFTP listing is untrusted input.** The server chooses the names, and
+  they were turned into child paths unchecked, so a crafted `../victim.txt`
+  made `rm(recursive=True)` delete outside the tree it was given and a
+  recursive copy read from outside it (measured on both backends). Names
+  that are not a single component inside the directory are now skipped, as
+  `dav:` and `http:` already did. The asyncssh fan-out walkers, which bypass
+  `_scandir()`, filter for themselves.
+- **`unpack_archive()` split a backslash on every platform**, so a POSIX
+  member whose name contains one was extracted as two path components and
+  one carrying `..` was silently dropped -- both legal single filenames
+  there. A backslash now separates only for a Windows destination, which is
+  the rule the function already documented.
+- **`has_glob_pattern()` was True for every Windows extended-length path.**
+  The `?` in a `\\?\C:\...` anchor (and the `\\?\UNC\...` form) is a prefix,
+  not a wildcard, so a caller using it to tell a pattern from a plain path
+  got the wrong answer for all of them. The anchor is no longer scanned.
+  Reported by yaconfiglib against 0.9.6.
+- **Writing over an archive member spelled `./f.txt` appended a second
+  entry instead of rewriting it**, and `unlink()` then deleted that second
+  entry and reported success while the original content came back. 0.9.5
+  handed the normalized name to a backend keyed on the raw one; writes now
+  address the entry the archive really holds.
+- **Renaming a directory in such an archive silently did nothing**, or
+  split it in two when its members were spelled inconsistently, while
+  `rename()` returned the new path as though it had worked. The backend now
+  receives the exact raw-name mapping instead of a normalized prefix.
+- **Every archive operation rebuilt the member index**, so a listing, stat,
+  read or write on a 20k-member archive scanned all 20k names: measured
+  10x-224x slower than 0.9.4. The index is cached per open handle and
+  dropped whenever the handle is, which every mutation and every external
+  change already go through.
+- **`glob(None)` ignored `native=`, never auto-detected `**`, and answered
+  differently from `rglob(None)`** for the same path, because that branch
+  bypassed the pattern parser: `LocalPath("/x/**/*.py").glob(None)` returned
+  a shallow subset with no error. `native=False` also left the trailing-`**`
+  rule following the interpreter, so it did not deliver the one-answer
+  promise it documents; it now pins that rule too.
+- **`/` mangled a `data:` payload** (`data:,a/../b` joined to `data:b/x`,
+  not a data URI at all), dropped a scheme's own child handling (`gitlab:`'s
+  reserved `-`), still parsed a `bytes` name as URI syntax, and lost
+  per-instance scheme state such as `SftpPath`'s `ssh_config`. Joins now
+  walk segments through the same builder a listing uses.
+- **A relative `str` destination whose first segment merely contained a
+  colon** (`notes:draft`, `Fedora-42:latest.tar`) was read as a URI scheme
+  by `copy()`/`move()`; the scheme must now be one a class registers, as
+  the `uripath` CLI already required. A Windows drive path (`C:/Temp/x`)
+  restarts the join for a `file:` path, as `PureWindowsPath` does.
+- **`rename()` and `copy()`/`move()` resolved a relative `str` differently**
+  (`rename("../b")` sent a literal `sub/../b`, a different key on an object
+  store); both now resolve it the same way. A same-endpoint URI destination
+  reuses the configured connection instead of opening a second, bare one.
+
+### Changed
+- **`rm(recursive=True)` no longer descends into a mount point.** It
+  already removed a Windows junction as a binding rather than walking into
+  it; a POSIX bind mount is the same thing and was walked, so deleting a
+  tree containing one deleted the mounted filesystem's contents. It is now
+  `rmdir()`'d like a junction, which fails loudly on a live mount instead.
+- **`UriPath / "name"` and `joinpath()` read a `str` as a decoded path**,
+  not as URI syntax. `base / "cache?v=2"` is now the file `cache?v=2`
+  instead of `base/cache` with a query; `"note#2.txt"`, `"a%20b.txt"` and
+  `"C:/Temp"` join verbatim too. This is what `iterdir()` always did, so
+  listing a directory and naming the same child by hand finally agree. Pass
+  a `Uri`/`UriPath` argument for a scheme-aware join
+  (`base / UriPath("s3://bucket/key")`); that stays the only form that can
+  cross endpoints, and it still drops a credential-bearing backend on the
+  way. Dot segments are removed from the result as before.
+- **`copy()`/`move()` accept a plain-path `str` destination.** A string with
+  a scheme is a URI, as before, so `copy("s3://bucket/key")` keeps working;
+  one without is a decoded path on the same endpoint (absolute replaces the
+  path, relative is a sibling, as `rename()` resolves it) and reuses this
+  path's source and backend. `move("b.txt")` previously built a sourceless
+  path and failed on its first `exists()` call, and a same-host URI
+  destination opened a second connection. A one-letter scheme is treated as
+  a Windows drive, so `C:/Temp/x` is a path.
+
 ## [0.9.6] - 2026-09-16
 
 ### Added
@@ -1336,7 +1462,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.6...HEAD
+[Unreleased]: https://github.com/jose-pr/pathlib-next/compare/v0.9.8...HEAD
+[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
 [0.9.4]: https://github.com/jose-pr/pathlib-next/compare/v0.9.3...v0.9.4

{pathlib_next-0.9.6 → pathlib_next-0.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pathlib-next
-Version: 0.9.6
+Version: 0.9.8
 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.6 → pathlib_next-0.9.8}/docs/divergences.md

@@ -56,6 +56,8 @@ 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(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. |
@@ -71,7 +73,8 @@ these operations itself always keeps its own implementation.
 | `Path.__iter__` | `pathlib.Path` is not iterable (no `__iter__`) | `iter(path)` is `path.iterdir()` | Deliberate extension for ergonomic `for child in path:` loops. **Caution:** on remote schemes (http/sftp) this is a network call. **User decision, 2026-07-11.** |
 | `Path.copy(target, ...)` | CPython 3.14 `Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)`: overwrites an existing file, copies a directory tree without being asked, returns the new path | Ours predates 3.14. Signature: `copy(target, *, overwrite=False, follow_symlinks=True, preserve_metadata=True, recursive=False, ignore_error=None, progress=None)`; returns `None`. An existing target raises `FileExistsError` unless `overwrite=True`; a directory needs `recursive=True`. `overwrite=True` unlinks an existing non-directory target, but only once the source is open (a missing or unreadable source never destroys or creates the target; a copy that fails mid-stream removes its partial target); copying onto the same file raises `OSError(EINVAL)`; `preserve_metadata` defaults to **True** (opposite of 3.14) and only propagates `st_mode`, not timestamps/xattrs | Argument names aligned with 3.14 where cheap; `preserve_metadata=True` default kept for backward compat with this method's pre-existing (pre-3.14-alignment) behavior of always copying the mode bits. Full metadata preservation (timestamps, xattrs) is not implemented. |
 | `Path.move(target, ...)` | CPython 3.14 `Path.move(target)`: `os.replace` semantics (replaces an existing file), falls back to copy + delete across filesystems, returns the new path | Ours predates 3.14 and keeps `overwrite=False`: an existing target raises `FileExistsError`. Returns whatever `rename()` returns (`None` on the copy fallback). Our own extension: tries `rename()`, falls back to copy+unlink. Validates before touching the target: a missing source raises `FileNotFoundError`, a file onto a directory raises `IsADirectoryError`, and the same file under another spelling (a case-only rename) is renamed in place. `overwrite=True` replaces a local file target atomically (`os.replace`); on other backends it unlinks the target immediately before `rename()`, so a failing rename can still lose it. | N/A -- pure extension, no pathlib method to diverge from. Removing the target before checking the source deleted it on a typo or a locked source. |
-| `Path.rm(recursive=, missing_ok=, ignore_error=)` | Not in `pathlib` (closest: `shutil.rmtree`) | Our own extension. Recursive removal deletes bottom-up and uses non-following stat/listing metadata, so a symlink to a directory -- or a Windows junction, which a non-following stat still reports as a directory -- is unlinked rather than traversed. | N/A -- pure extension. Non-following recursive deletion avoids deleting through symlinked directory targets and lets backends with metadata-rich listings remove trees without a stat round trip per child. |
+| `Path.is_junction()` / `is_mount()` / `is_dir_binding()` | `pathlib` has `is_junction()` (3.12+) and `is_mount()`, but only for local paths and with no shared concept | Both are part of the `Path` contract (False by default, answered by `LocalPath`/`FileUri`), and `is_dir_binding()` is their union: a directory that is another tree's second NAME rather than part of this one. A junction is the Windows spelling of a bind mount, and neither is a symlink -- `is_symlink()` is False and a non-following stat reports a plain directory. | Walking code needs the distinction: a symlink announces itself and every walker here already declines to follow one, while a binding looks exactly like an ordinary directory and its contents belong to whoever mounted or junctioned it. |
+| `Path.rm(recursive=, missing_ok=, ignore_error=)` | Not in `pathlib` (closest: `shutil.rmtree`) | Our own extension. Recursive removal deletes bottom-up and uses non-following stat/listing metadata, so a symlink to a directory -- or a binding (`is_dir_binding()`: a Windows junction, a mount point), which a non-following stat still reports as a directory -- is unlinked or `rmdir()`'d rather than traversed -- `rm -r` semantics. `follow_symlinks=`/`follow_binds=` select that per call: `False` (default), `True` (remove what is behind it), `None` (leave it), or a callable asked per entry -- the same keyword `stat()`/`walk()`/`copy()` use for the same idea. `rmdir()` on a live mount fails, which is the intended answer. | N/A -- pure extension. Non-following recursive deletion avoids deleting through symlinked directory targets and lets backends with metadata-rich listings remove trees without a stat round trip per child. |
 | `Path.symlink_to(target, target_is_directory=False, *, force=False)` | `pathlib.Path.symlink_to(target, target_is_directory=False)` -- raises `FileExistsError` if anything already exists at the link path | Adds a keyword-only `force=`. `force=False` (the default) is stdlib-exact. `force=True` unlinks an existing **non-directory** entry at the link path first, then creates the symlink; an existing *directory* is never removed and the underlying error propagates. Not atomic: no filesystem or transport offers "replace a symlink" as one operation, so the path briefly does not exist between the unlink and the symlink. | Additive extension (an extra optional kwarg, per the parity contract). No backend can offer this atomically, so every consumer was re-implementing the same unlink-then-symlink dance -- it is path semantics, not transport semantics, so it belongs at the `Path` layer where one implementation serves every backend. Backends implement only the `_symlink_to()` primitive (same `_mkdir`/`_open` shape) and get `force=` for free. Because no stdlib version accepts the keyword, `symlink_to` is in `_OPERATION_NAMES` so `LocalPath` honors it too. |
 | `Path.chown(uid=None, gid=None, *, follow_symlinks=True)` | Not in `pathlib` at all -- it has `owner()`/`group()` **readers** but no writer (the stdlib writers are `os.chown`/`shutil.chown`, which are functions over a path, not path methods) | Our own extension. `None` (default) leaves a field unchanged; `-1` is accepted as an alias for `None` (`os.chown`'s own sentinel); an `int` is a uid/gid and a `str` is a user/group name. A call where both fields are unchanged short-circuits without touching the backend. Implemented for `LocalPath`/`FileUri` (via `shutil.chown`, or `os.lchown` for `follow_symlinks=False`) and `SftpPath` (`setstat`); `NotImplementedError` elsewhere -- including `LocalPath` on a platform without `os.chown` (Windows), where `shutil.chown` exists but cannot work. | Ownership was the one permission attribute `stat()` could report (`st_uid`/`st_gid`) that nothing could write back. The valuable part is centralizing the **"unchanged" sentinel** on `Path` (`utils.as_owner()`): `os.chown` spells it `-1`, SFTP omits the field, other middlewares use `None` -- normalizing per-scheme would be three chances to disagree. Backends implement `_chown()` and receive an already-canonical pair. SFTPv3 sends uid/gid as one paired attribute, so `SftpPath` reads the current owner for whichever field is unchanged rather than guessing a value. |
 | `Path.chmod(mode, ...)` accepting a `str` | `mode` must be an `int`; a `str` raises `TypeError` | Additionally accepts a `str`, parsed as **octal**: `"0755"`, `"755"` and `0o755` all mean the same thing. An optional `0o` prefix is allowed; any character outside `[0-7]` raises `ValueError` rather than being coerced. | The string form is how modes are written in `chmod(1)`, Ansible, Dockerfiles and shell scripts, so config-driven callers arrive holding one. Accepted only with an **explicit base 8** (`utils.as_mode()`), never a plain `int()`: `int("0755")` in decimal is 755 == `0o1363`, a different *and valid* mode, so a fallback to decimal would set plausible-but-wrong permissions with nothing raising -- which is exactly why stdlib refuses strings. Parsing in one shared helper is what makes the base non-negotiable across the five backends that implement `chmod` directly. |
@@ -84,6 +87,8 @@ these operations itself always keeps its own implementation.
 | `Path.copy(recursive=True)` child names | `shutil.copytree` joins whatever the listing yields | A child name that would not stay inside `target` is refused with `ValueError` through `ignore_error`: `..`, and `\`/`:`/a trailing dot when the target reads names with Windows rules. | The names come from listings the destination does not control (an archive, an HTTP index, an object-store key); on a Windows target `"C:x"` joins to a drive-relative path outside the destination entirely. `PathSyncer` and `utils.unpack_archive()` already applied this per destination. |
 | Archive member names | N/A (`zipfile`/`tarfile` expose the raw name as written) | Normalized as POSIX relative paths for every format: a leading `./`, empty segments and interior `.`/`..` resolve, so one member has one name and listings and lookups agree; the raw spelling still addresses it, and the later of two members that normalize alike wins. A name that escapes the root (`../x`, `/abs`) has no name inside the archive at all, while a drive- or backslash-shaped name is a normal member (an ordinary POSIX filename) that only a Windows destination refuses to receive. | The same file was reachable or not depending on how the writer spelled it: a zip written by `shutil.make_archive`-style `./` prefixes listed as empty, and zip and tar disagreed about identical archives. |
 | The POSIX `//` root | `PurePosixPath("//")` keeps `//` as a root distinct from `/` (POSIX leaves exactly two leading slashes implementation-defined; three or more collapse) | The generic classes do not model it: `MemPath("//")` collapses to `/`, and `Uri("//")` reads `//` as the start of an authority (RFC 3986), giving an empty authority and an empty path -- so `Uri("//a/b")` has host `a` and path `/b`. `match()` therefore disagrees with `pathlib` on that one path. `LocalPath`/`WindowsPathname` are unaffected (they inherit pathlib's parsing, where `//server/share` is a UNC drive). | A distinct double-slash root has no meaning for an in-memory tree or a URI, and for a `Uri` it cannot: `//a/b` must read `a` as a host. Modelling it would change segment normalization everywhere (`parents`, `relative_to`, `is_absolute`, every scheme) to serve a spelling no backend can use. |
+| `Uri / "name"`, `joinpath("name")` | `pathlib` joins the string as path segments | Same: a `str` is an already-decoded path, so `?`, `#`, `%` and a leading `C:` are ordinary filename characters (`base / "cache?v=2"` is the file `cache?v=2`, not a query). Pass a `Uri`/`UriPath` argument for a scheme-aware join (`base / UriPath("s3://bucket/key")` crosses to S3, and drops a credential-bearing backend on the way). Dot segments in the result are still removed. | A join names a child, and `iterdir()` already named it literally -- listing a directory holding `cache?v=2` gave a working path while typing the same name by hand gave `/mnt/cache`. Only the explicit `Uri` form can now reach another host, so a `str` can no longer carry a session or token off the endpoint it belongs to. |
+| `copy(str)` / `move(str)` destination | `shutil` resolves a relative destination against the process cwd | Read by shape: with a scheme (`s3://bucket/key`, `data:,abc`) it is a URI, so a cross-scheme copy works; without one it is a decoded path on the SAME endpoint -- absolute replaces the path, relative is a sibling, as `rename()` resolves it -- keeping this path's source and backend. A one-letter scheme is a Windows drive (`C:/Temp/x` is a path). | A URI has no cwd, and the previous URI-only parse turned `move("b.txt")` into a sourceless path that could not do I/O at all, while a same-host URI destination opened a second connection. |
 | `Uri` path dot segments | `pathlib` keeps `..` lexically (`PurePosixPath("a/../b")` is `a/../b`) | `Uri` removes dot segments as RFC 3986 requires of a URI reference, in the constructor and in `/`-joins: `Uri("a/../b")` is `b`, `Uri("http://h/x") / "a/../b"` is `http://h/x/b`, and `Uri("a/b/..")` is `a/`. A leading `..` that would pass the root is kept, not resolved. `MemPath` follows `pathlib` instead. | A URI is resolved, not spelled: `..` in a URI reference has a defined meaning that servers, caches and proxies already apply, so keeping it lexically would address a different resource than the same string typed into a browser. |
 | Nested archive URIs | N/A | Each leading archive scheme in `<archive-uri>` consumes one `!/` (`zip:zip:file:///outer.zip!/inner.zip!/x.txt`); a member name containing `!/` is written `%21/`. Nested archives are read-only. | The first `!/` was always taken as the separator, so an archive inside an archive could not be addressed. |
 | Object-store key that is both an object and a prefix | N/A (a filesystem entry has one type) | `iterdir()`/`walk()`/`copy(recursive=True)` on `s3:`/`gs:`/`az:` show only the object (`x`), matching `stat()`'s exact-object precedence; the subtree under `x/` is not listed. | Listings used to keep the directory and drop the object, contradicting `stat()`. |

{pathlib_next-0.9.6 → pathlib_next-0.9.8}/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.6"
+version = "0.9.8"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"

{pathlib_next-0.9.6 → pathlib_next-0.9.8}/src/pathlib_next/AGENTS.md

@@ -62,6 +62,16 @@ silently absent and `from pathlib_next.uri import UriPath` raises
     a concrete stdlib path without `LocalPath`). A method defined in the
     subclass itself always wins.
   - `is_hidden()` — name starts with `"."`. `__iter__()` is `iterdir()`.
+  - **A binding is not a symlink.** `is_junction()` (pathlib 3.12 parity:
+    a Windows junction) and `is_mount()` (a mount point, bind mounts
+    included) report a directory that is another tree's second NAME.
+    Neither is a symlink: `is_symlink()` is False, `readlink()` says
+    nothing, and a non-following stat calls it an ordinary directory — which
+    is why a symlink check cannot protect a walk from one. `is_dir_binding()`
+    is the pair, and is what `rm(recursive=True)` consults: it removes the
+    binding itself rather than the contents behind it (`rmdir()` on a live
+    mount fails loudly, which beats emptying the mounted filesystem).
+    Default False everywhere; `LocalPath`/`FileUri` answer for real.
   - `samefile(other_path)` — compares `(st_dev, st_ino)`; `NotImplementedError`
     when `stat()` lacks them (`LocalPath` uses pathlib's).
   - `iterdir() -> Iterator[Self]` — **stub** (`NotImplementedError`); a
@@ -73,7 +83,8 @@ silently absent and `from pathlib_next.uri import UriPath` raises
     `PathSyncer`; override it when the listing call already returns metadata.
     `None` means "unknown", never "missing".
   - `glob(pattern, *, case_sensitive=None, include_hidden=True,
-    recursive=None, dironly=None, recurse_symlinks=False, native=True)` —
+    recursive=None, dironly=None, recurse_symlinks=False, native=True,
+    on_error=None, bound_loops=False)` —
     pathlib semantics: hidden entries included, `**` never descends into
     directory symlinks (`recurse_symlinks=True` → `NotImplementedError`), a
     trailing `**` selects files too on 3.13+, a missing or non-directory base
@@ -86,6 +97,20 @@ silently absent and `from pathlib_next.uri import UriPath` raises
       (`LocalPath("/etc/*.conf").glob(None)`), splitting at the first
       wildcard — the supported form for a path that is itself a pattern.
       `""` still raises.
+    - **`on_error(error)`** is called when a directory cannot be listed,
+      the same contract as `walk()`/`os.walk`: raising from it propagates,
+      returning treats that directory as empty. Without it the listing is
+      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.
     - **`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`
@@ -105,11 +130,21 @@ silently absent and `from pathlib_next.uri import UriPath` raises
     `LocalPath`/`FileUri` use pathlib's `touch()`.
   - `_mkdir(mode)` (stub) / `mkdir(mode=0o777, parents=False, exist_ok=False)`.
   - `unlink(missing_ok=False)`, `rmdir()` — stubs.
-  - `rm(recursive=False, missing_ok=False, ignore_error=False)` — extension.
+  - `rm(recursive=False, missing_ok=False, ignore_error=False, *,
+    follow_symlinks=False, follow_binds=False)` — extension.
     `ignore_error` is a bool or `callable(error, path) -> bool` (True
     swallows); each error is offered once. Recursive removal is bottom-up and
-    never descends through a directory symlink or a Windows junction (the
-    link itself is removed).
+    never descends through a directory symlink or a binding (a Windows
+    junction, a mount point — `is_dir_binding()`): the entry itself is
+    removed, never what is behind it, which is what `rm -r` does.
+    `follow_symlinks=` (symlinks) and `follow_binds=` (bindings) choose per
+    call: `False` (default, remove the entry), `True` (remove the contents
+    behind it too), `None` (leave it in place — the enclosing directory is
+    then not empty and says so), or a callable `policy(path) -> bool | None`
+    asked per entry, so one tree can keep one mount and follow another. The
+    name matches `stat()`/`walk()`/`copy()`'s `follow_symlinks=` rather than
+    a second vocabulary for the same idea. Path components before the final
+    one are followed as usual.
   - `rename(target)` — stub. Implementations return the new path.
   - `_symlink_to(target, target_is_directory=False)` (stub; receives a path
     object) / `symlink_to(target, target_is_directory=False, *, force=False)`
@@ -233,6 +268,12 @@ silently absent and `from pathlib_next.uri import UriPath` raises
   3986 reference resolution and `..` is not resolved during a join. An
   absolute local path becomes `file:`; a relative one joins like a
   `PurePath`.
+  - `/` and `joinpath()` take a `str` as an **already-decoded path**: `?`,
+    `#`, `%` and a leading `C:` are ordinary filename characters
+    (`base / "cache?v=2"` names that file), which is what `iterdir()` builds.
+    A `Uri`/`UriPath` argument keeps URI semantics and is the only form that
+    can cross to another endpoint -- where a credential-bearing backend is
+    dropped. Dot segments are removed from the joined result either way.
   - Properties: `source -> Source`, `path -> str` (percent-decoded),
     `query -> Query` (**percent-encoded as received**, sent unchanged),
     `fragment -> str`, `parts -> (source, path, query, fragment)` (not path
@@ -280,7 +321,14 @@ silently absent and `from pathlib_next.uri import UriPath` raises
     `#`, `%`, `:` are filename characters); a relative `rename()` target is a
     sibling of `self`. A target on another endpoint (or another archive or
     Azure container) raises `NotImplementedError`, so `move()` copies and
-    deletes. `copy()`/`move()` parse a `str` target as a URI.
+    deletes.
+  - `copy()`/`move()` read a `str` destination **by its shape**: with a
+    scheme (`s3://bucket/key`, `data:,abc`) it is a URI, so a cross-scheme
+    copy works; without one it is a decoded path on this endpoint — absolute
+    replaces the path, relative is a sibling, as `rename()` resolves it — and
+    keeps this path's source and backend rather than opening a second
+    connection. A one-letter scheme is a Windows drive, so `C:/Temp/x` is a
+    path.
 - **`Source(scheme, userinfo, host, port)`** (`uri.source`) — `NamedTuple`,
   falsy when all fields are empty. `as_str(sanitize=True)`; `str()`/`repr()`
   redact the password (the fields keep it). `Source.from_str(source,

{pathlib_next-0.9.6 → pathlib_next-0.9.8}/src/pathlib_next/fspath.py

@@ -241,13 +241,23 @@ class LocalPath(
         except Exception:
             return False
 
-    def _is_junction_link(self) -> bool:
-        # lstat() reports a junction (IO_REPARSE_TAG_MOUNT_POINT) as a plain
-        # directory -- CPython only rewrites the mode to S_IFLNK for real
-        # symlinks -- so rm(recursive=True) used to walk into it and delete
-        # the junction target's files. shutil.rmtree guards the same case.
+    def is_junction(self) -> bool:
+        """Whether this is a Windows junction. `os.path.isjunction()` on
+        3.12+, the reparse tag directly before that.
+
+        lstat() reports a junction (IO_REPARSE_TAG_MOUNT_POINT) as a plain
+        directory -- CPython only rewrites the mode to S_IFLNK for real
+        symlinks -- so `rm(recursive=True)` used to walk into one and delete
+        the target's files. `shutil.rmtree` guards the same case.
+        """
         if _os.name != "nt":
             return False
+        isjunction = getattr(_os.path, "isjunction", None)
+        if isjunction is not None:
+            try:
+                return bool(isjunction(self))
+            except (OSError, ValueError):
+                return False
         try:
             st = _os.lstat(self)
         except OSError:
@@ -256,6 +266,14 @@ class LocalPath(
             _stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003
         )
 
+    def is_mount(self) -> bool:
+        """Whether this is a mount point -- a bind mount included, which is
+        how POSIX spells what a junction does on Windows."""
+        try:
+            return bool(_os.path.ismount(self))
+        except (OSError, ValueError):
+            return False
+
     def walk(self, top_down=True, on_error=None, follow_symlinks=False):
         # 3.12+ stdlib `pathlib.Path.walk()` sits ahead of ours in the MRO
         # and would otherwise win here. Its implementation calls
@@ -402,6 +420,8 @@ class LocalPath(
         dironly: bool = None,
         recurse_symlinks: bool = False,
         native: bool = True,
+        on_error: "_ty.Callable[[OSError], None]" = None,
+        bound_loops: bool = False,
     ):
         """Iterate over this subtree and yield all existing files (of any
         kind, including directories) matching the given relative pattern.
@@ -422,6 +442,8 @@ class LocalPath(
                 dironly=dironly,
                 recurse_symlinks=recurse_symlinks,
                 native=native,
+                on_error=on_error,
+                bound_loops=bound_loops,
             )
         pattern = _os.fspath(pattern)
         if pattern:
@@ -445,4 +467,6 @@ class LocalPath(
             dironly=dironly,
             recurse_symlinks=recurse_symlinks,
             native=native,
+            on_error=on_error,
+            bound_loops=bound_loops,
         )