pathlib-next 0.8.4__tar.gz → 0.8.6__tar.gz

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/.gitignore

@@ -4,8 +4,8 @@ build/
 site/
 
 # Agent/harness tooling
-AGENTS.md
-.agents/
+.agents
+*.local.md
 CLAUDE.md
 CLAUDE.local.md
 .claude/

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.6] - 2026-07-26
+
+### Fixed
+- **`PathSyncer.sync()` raised `TypeError` instead of honoring
+  `ignore_error`.** `sync()`'s `ignore_error` parameter defaulted to the bool
+  `False` and the symlink branch *called* it directly, so
+  `PathSyncer(ignore_error=True).sync(src, dst)` on a symlink source raised
+  `TypeError: 'bool' object is not callable` rather than the intended
+  `NotImplementedError`. The parameter now defaults to `None`, meaning "use
+  the policy given to `__init__`" -- it no longer silently shadows a
+  constructor-supplied policy -- and every branch consults one resolved
+  callable. Passing a callable explicitly behaves exactly as before.
+- **`Path.copy()` now accepts a bool for `ignore_error`**, matching
+  `Path.rm()`'s bool-or-callable contract. Previously only a callable or
+  `None` was handled, so `copy(recursive=True, ignore_error=True)` broke as
+  soon as a child copy failed. `None` keeps its documented meaning (fail on
+  the first error), and a callable remains a notification hook whose return
+  value is not consulted, so existing handlers such as `errors.append` are
+  unaffected.
+- **Downstream `Path` subclasses resolved stdlib `pathlib` operations
+  instead of pathlib_next's.** Concrete path classes mix a `pathlib` class
+  with `pathlib_next.Path`, so the MRO decided which library implemented a
+  method -- and which one won changed with the interpreter version. On
+  Python 3.14 the new stdlib `copy()`/`move()` displaced ours, crashing with
+  `AttributeError: ... has no attribute '_copy_from'` on non-local backends
+  and *silently* applying stdlib's different timestamp semantics on local
+  ones (making mtime-based syncs converge on 3.14 but never on <=3.13). In
+  the opposite direction, older stdlib lacked keywords this library's
+  protocols promise: `exists(follow_symlinks=)` (3.12+),
+  `read_text`/`write_text`'s `newline=` (3.13+), and `rglob`'s
+  `include_hidden=`/`recursive=`/`dironly=` extensions (never in stdlib), all
+  raising `TypeError` on the 3.9 floor. `Path.__init_subclass__` now
+  re-asserts the pathlib_next implementation of `copy`, `move`, `exists`,
+  `rglob`, `read_text` and `write_text` for any subclass that would otherwise
+  inherit stdlib's, so downstream implementers get correct behavior without
+  hand-written forwarding methods. A subclass or mixin that defines one of
+  these operations itself is never displaced.
+
+### Changed
+- `utils.as_error_handler()` centralizes `ignore_error` bool-to-callable
+  normalization. Callable **arities remain deliberately different per call
+  site** (`rm` -> `(error, path)`, `copy` -> `(error)`, `PathSyncer` ->
+  `(error, source, target, event)`); only the bool case is normalized, so no
+  public signature changed.
+
+## [0.8.5] - 2026-07-26
+
+### Fixed
+- **`LocalPath.copy()` and `LocalPath.move()` resolved to the incompatible
+  stdlib implementations on Python 3.14.** Python 3.14 added methods with
+  those names ahead of `pathlib_next.Path` in `LocalPath`'s MRO, so calls using
+  pathlib_next extensions such as `overwrite=` or `recursive=` failed with
+  `TypeError`. `LocalPath` now routes both methods explicitly through the
+  pathlib_next implementations on every supported Python version.
+- Generic paths now follow Python 3.14's updated `PurePath.with_suffix(".")`
+  behavior while retaining the earlier `ValueError` behavior on older Python
+  versions.
+
+### Changed
+- Documented that stdlib inheritance is deliberately local-only:
+  `LocalPath` is a real `pathlib.Path`, while URI, in-memory, and other virtual
+  implementations inherit the generic pathlib_next contracts without claiming
+  local-filesystem semantics.
+
 ## [0.8.4] - 2026-07-18
 
 ### Changed
@@ -516,7 +580,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.8.4...HEAD
+[Unreleased]: https://github.com/jose-pr/pathlib_next/compare/v0.8.6...HEAD
+[0.8.6]: https://github.com/jose-pr/pathlib_next/compare/v0.8.5...v0.8.6
+[0.8.5]: https://github.com/jose-pr/pathlib_next/compare/v0.8.4...v0.8.5
 [0.8.4]: https://github.com/jose-pr/pathlib_next/compare/v0.8.3...v0.8.4
 [0.8.3]: https://github.com/jose-pr/pathlib_next/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/jose-pr/pathlib_next/compare/v0.8.1...v0.8.2

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathlib_next
-Version: 0.8.4
+Version: 0.8.6
 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.8.4 → pathlib_next-0.8.6}/docs/divergences.md

@@ -11,6 +11,47 @@ in via MRO, so unless noted otherwise it behaves exactly like `pathlib.Path`
 (it inherits the real implementation for anything not explicitly overridden).
 The divergences below apply to `Uri`/`UriPath` and `MemPath`.
 
+## Type relationships
+
+Stdlib inheritance is deliberately limited to local filesystem paths:
+
+- `LocalPath` subclasses both `pathlib.Path` and `pathlib_next.Path`.
+- `PosixPathname` and `WindowsPathname` subclass the matching stdlib
+  `PurePath` classes and `pathlib_next.Pathname`.
+- `MemPath`, `Uri`, `UriPath`, and custom virtual or remote implementations
+  subclass the generic pathlib_next bases, not `pathlib.Path`/`PurePath`.
+- A plain stdlib `pathlib.Path` is not a `pathlib_next.Path`.
+
+The generic classes cannot safely inherit the stdlib classes: pathlib parses
+OS-specific path syntax and supplies operations whose semantics assume a local
+filesystem, neither of which applies to a URI, archive member, object-store key,
+or in-memory path. Registering stdlib paths as virtual `pathlib_next.Path`
+subclasses would likewise promise pathlib_next's extended operation contract on
+Python versions where stdlib paths do not implement it. Code accepting every
+implementation should type against `pathlib_next.Path` or its documented
+protocols; code requiring an OS path should type against `pathlib.Path`.
+
+### Operation precedence in `Path` subclasses
+
+Because concrete classes mix a `pathlib` class with `pathlib_next.Path`, the
+MRO alone would decide which library implements a given method -- and *which
+one wins changes with the interpreter version*, since stdlib `pathlib` keeps
+gaining and changing methods. That produced version-dependent behavior in
+both directions: CPython 3.14's new `copy()`/`move()` displaced ours (loudly
+on non-local backends, silently and with different timestamp semantics on
+local ones), while pre-3.12/3.13 stdlib lacked keywords our protocols
+promise (`exists(follow_symlinks=)`, `read_text`/`write_text`'s `newline=`).
+
+`pathlib_next.Path.__init_subclass__` therefore re-asserts the pathlib_next
+implementation of `copy`, `move`, `exists`, `rglob`, `read_text` and
+`write_text` for any subclass that would otherwise inherit stdlib's. This
+applies automatically to downstream classes built with the documented
+composition pattern (`class X(PosixPathname, Path)`), so implementers do not
+have to hand-write forwarding methods.
+
+Only stdlib `pathlib` is displaced: a subclass or mixin that defines one of
+these operations itself always keeps its own implementation.
+
 | Method | pathlib behavior | Our behavior | Why |
 | --- | --- | --- | --- |
 | `Uri("a").parent` | `PurePosixPath("a").parent == PurePosixPath(".")` | `Uri("a").parent` has path `""` (`Uri("")`, which round-trips) | `Uri` has no cwd-relative concept of `"."` -- an empty path is the URI-natural "no path" representation. Changing this would make `Uri("")` non-idempotent under `.parent`. |

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pathlib_next"
-version = "0.8.4"
+version = "0.8.6"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"
@@ -58,6 +58,15 @@ Homepage = "https://github.com/jose-pr/pathlib_next/"
 Documentation = "https://jose-pr.github.io/pathlib_next/"
 Issues = "https://github.com/jose-pr/pathlib_next/issues"
 
+
+# Ship the consumer-facing docs inside the installed package, so they are
+# readable from site-packages via importlib.resources without the repo.
+# src/pathlib_next/AGENTS.md is included automatically by living in the package
+# dir; the repo-root AGENTS.md is development-only and deliberately not
+# shipped.
+[tool.hatch.build.targets.wheel.force-include]
+"README.md" = "pathlib_next/README.md"
+
 [tool.hatch.build.targets.sdist]
 exclude = ["/.*", "/benchmarks"]
 

pathlib_next-0.8.6/src/pathlib_next/AGENTS.md

@@ -0,0 +1,270 @@
+# `pathlib_next` — public API header
+
+Header-file-style reference for the `pathlib_next` package: every public
+export with its signature, arguments, contract, and gotchas, so this module
+can be consumed without reading its source. Kept current with the public
+API. For the project overview, install extras, and code layout, see the
+<https://github.com/jose-pr/pathlib_next>. Any behavioral divergence from `pathlib.Path` is
+recorded in `docs/divergences.md` — this file documents the *contract*, not
+every internal deviation.
+
+`import pathlib_next` re-exports `path`, `fspath`, `utils.glob`,
+`utils.sync`, and (if `uritools` is importable) `uri.Uri`/`uri.UriPath`; a
+missing `uritools` degrades that last import silently (`try`/`except
+ImportError: pass`), so `pathlib_next.uri` may need an explicit
+`from pathlib_next.uri import UriPath` even after a plain `import
+pathlib_next`.
+
+## Pure-path / I/O base (`pathlib_next.path`)
+
+- **`Pathname`** — ABC for a pure (no I/O) path: `name`, `suffix`,
+  `suffixes`, `stem`, `segments` (abstract), `parts` (abstract),
+  `with_segments(*segments)` (abstract), `with_name`/`with_stem`/
+  `with_suffix`, `relative_to(other)`, `is_relative_to(other)`,
+  `__truediv__`/`joinpath`, `root`/`drive`/`anchor` (all `""` unless
+  overridden), `parent`/`parents` (abstract `parent`), `is_absolute()`
+  (abstract), `match(pattern, *, case_sensitive=None)`,
+  `full_match(pattern, *, case_sensitive=None)`, `as_posix()`,
+  `has_glob_pattern()`. `as_uri()` is abstract on `Pathname` itself.
+- **`Path(Pathname, Chmod, Stat, BinaryOpen)`** — base class for I/O paths.
+  `Path(*args)` (the bare class, not a subclass) always constructs a
+  `LocalPath` (`fspath.py`) — the real local filesystem. Adds:
+  - `is_hidden()` — name starts with `"."`.
+  - `samefile(other_path)` — compares `(st_dev, st_ino)` from `stat()`;
+    raises `NotImplementedError` if either isn't available (`LocalPath` gets
+    a real implementation from `pathlib.Path` via MRO instead).
+  - `iterdir() -> Iterator[Self]` — **not implemented** by default (raises
+    `NotImplementedError`); every concrete `Path` overrides it.
+  - `_scandir() -> Iterator[tuple[str, FileStat | None]]` — default falls
+    back to `iterdir()` + one `stat()` per child; override directly when the
+    listing call already returns metadata (used by `walk()`/`glob()` so
+    remote schemes avoid a stat round trip per entry).
+  - `glob(pattern, *, case_sensitive=None, include_hidden=False,
+    recursive=None, dironly=None)` — a `"**"` pattern component
+    auto-enables recursion (pathlib parity); pass `recursive=False`
+    explicitly to disable it even with `"**"` present, or `True` to force it
+    without `"**"`. A recursive glob on a remote scheme walks the whole
+    subtree, one round trip per directory.
+  - `rglob(pattern, ...)` — `glob(f"**/{pattern}", recursive=True)`.
+  - `walk(top_down=True, on_error=None, follow_symlinks=False)` — drives
+    `_scandir()`, not `iterdir()`; the pre-seeded stat from `_scandir()` is
+    trusted only when `follow_symlinks=False` (its own default) — an
+    explicit `follow_symlinks=True` always re-`stat()`s each entry.
+  - `touch(mode=0o666, exist_ok=True)` — raises `FileExistsError` (not a
+    silent truncate) when `exist_ok=False` and the file exists.
+  - `_mkdir(mode)` (not implemented by default) / `mkdir(mode=0o777,
+    parents=False, exist_ok=False)` — `mkdir()` retries through
+    `_mkdir()`, creating parents on `FileNotFoundError` when `parents=True`.
+  - `unlink(missing_ok=False)` / `rmdir()` — not implemented by default;
+    every concrete `Path` overrides them.
+  - `rm(recursive=False, missing_ok=False, ignore_error=False |
+    Callable[[Exception, Self], bool])` — extension, no direct pathlib
+    equivalent. Removes a file or (with `recursive=True`) a directory tree;
+    `ignore_error` (bool or predicate) controls whether an error during the
+    walk is swallowed (predicate return `True`) or re-raised.
+  - `rename(target)` — not implemented by default.
+  - `copy(target, *, overwrite=False, follow_symlinks=True,
+    preserve_metadata=True, recursive=False, ignore_error=None)` —
+    `follow_symlinks`/`preserve_metadata` names match CPython 3.14's
+    `Path.copy()`; `overwrite` is this library's own extension (3.14 always
+    raises if the destination exists). `preserve_metadata` defaults `True`
+    here (3.14 defaults `False`) and only preserves `st_mode`, not
+    timestamps/xattrs. `ignore_error`, when given, receives exceptions
+    instead of raising (same contract as `rm()`'s callable form); `None`
+    (default) fails on the first error.
+  - `move(target, *, overwrite=False)` — tries `rename()` first, falls back
+    to `copy(recursive=True)` + `rm(recursive=True)`/`unlink()` when
+    `rename()` raises `NotImplementedError`.
+- **`PathLike`** — `Union[str, Path]`. **`PurePathLike`** — `Union[str,
+  Pathname]`. **`FsPathLike`** — `Protocol` requiring `__fspath__() -> str`.
+
+## Local filesystem (`pathlib_next.fspath`)
+
+- **`LocalPath`** — `pathlib.WindowsPath`/`PosixPath` (by `os.name`) with
+  this library's `Path` mixed in via MRO. Behaves exactly like
+  `pathlib.Path` for anything not explicitly overridden (see
+  `docs/divergences.md`); overrides `_scandir()`, `walk()`, `copy()`,
+  `move()`, `stat()`, `chmod()`, and `glob()` to keep this project's
+  contracts (tuple-yielding `_scandir`, extended copy/move kwargs,
+  `follow_symlinks=` support pre-3.10) regardless of what a given Python
+  version's own `pathlib.Path` does at the same MRO position.
+  Stdlib inheritance is intentionally local-only: `MemPath`, `Uri`, and
+  `UriPath` implement the pathlib_next bases but are not stdlib
+  `PurePath`/`Path` instances because stdlib construction and operations
+  assume OS path syntax and a local filesystem. Conversely, a plain stdlib
+  `pathlib.Path` is not a `pathlib_next.Path`.
+- **`PosixPathname`** / **`WindowsPathname`** — pure (no I/O) path classes
+  implementing `Pathname` on top of `pathlib.PurePosixPath`/
+  `PureWindowsPath`.
+
+## In-memory filesystem (`pathlib_next.mempath`)
+
+- **`MemPath(Path)`** — `MemPath(*segments, backend=None, **kwargs)`.
+  In-memory path over nested dicts; a `dict` value is a directory, a
+  `bytearray` value is a file's content. Reference exemplar for subclassing
+  `Path` directly. `relative_to()` is not implemented. `as_uri()` returns
+  `mempath:<url-quoted posix path>`. Supports `_open()` modes `"r"`, `"w"`,
+  `"x"`, `"a"` (the `"a"` extension isn't part of the base `BinaryOpen`
+  contract). `rename()` is not implemented (see the scheme feature matrix in
+  the README).
+- **`MemPathBackend(dict)`** — the nested-dict storage. Share one instance
+  across `MemPath`s via `backend=` to give them the same virtual filesystem;
+  omitted, each root `MemPath()` gets its own.
+
+## Protocols (`pathlib_next.protocols`)
+
+- **`fs.FileStatLike`** — `Protocol`: `st_mode`, `st_size`, `st_mtime`
+  (all abstract properties).
+- **`fs.Stat`** — `Protocol`. `stat(*, follow_symlinks=True) ->
+  FileStatLike` (not implemented by default). Derives `lstat()`,
+  `exists()`, `is_dir()`, `is_file()`, `is_symlink()`, `is_block_device()`,
+  `is_char_device()`, `is_fifo()`, `is_socket()` — all methods, not
+  properties. `exists()`/the `is_*` methods swallow `OSError`/`ValueError`
+  from `stat()` and report `False` rather than propagating (pathlib parity).
+- **`fs.Chmod`** — `Protocol`. `chmod(mode, *, follow_symlinks=True)` (not
+  implemented by default); derives `lchmod(mode)`.
+- **`io.BinaryOpen`** — `Protocol`. `_open(mode="r", buffering=-1) ->
+  io.IOBase` (not implemented by default; must yield a **binary** stream).
+  Derives `open(mode="r", buffering=-1, encoding=None, errors=None,
+  newline=None)`, `read_bytes()`, `read_text(encoding=None, errors=None,
+  newline=None)`, `write_bytes(data)`, `write_text(data, encoding=None,
+  errors=None, newline=None)`, `copy(target)` (streams this object's binary
+  content into another `BinaryOpen`).
+
+## URIs (`pathlib_next.uri`)
+
+Only importable if `uritools` is installed (the `uri` extra or any scheme
+extra that depends on it).
+
+- **`Uri(Pathname)`** — a pure (no I/O), RFC 3986 URI, lazily parsed into
+  `source`/`path`/`query`/`fragment` on first access. `Uri(*uris,
+  **options)` — multiple constructor args are joined pathlib-`joinpath`-style
+  (right to left, stopping at the first absolute segment) — this is **not**
+  RFC 3986 reference resolution, and `..` is never resolved during join (see
+  `docs/divergences.md`). Properties: `source -> Source`, `path -> str`,
+  `query -> str`, `fragment -> str`, `parts -> (source, path, query,
+  fragment)`, `normalized_path` (posixpath-normalized `path`), `segments`,
+  `suffix`, `stem`, `parent`. Methods: `as_uri(sanitize=False)` (sanitize
+  strips password from userinfo before formatting), `with_source(source)`,
+  `with_segments(*segments)`, `with_path(path)`, `with_query(query)`,
+  `with_fragment(fragment)`, `is_absolute()`, `is_relative_to(other)`,
+  `relative_to(other, *, walk_up=False)`, `is_local()` (delegates to
+  `Source.is_local()` — does a DNS lookup, cached per `Source`),
+  `as_posix()` (`user@host:path` / `host:path` form when a source is
+  present). `__fspath__()` only succeeds for a `file:`-scheme URI pointing
+  at this machine; otherwise raises `NotImplementedError`.
+- **`UriPath(Uri, Path)`** — `Uri` + `Path` (I/O) + scheme dispatch.
+  `UriPath(*uris, **options)` (the bare class) parses the URI and returns an
+  instance of the concrete subclass registered for its scheme via
+  `__SCHEMES` (name-mangled per class — declare `__SCHEMES = ("http",
+  "https")` in the subclass body, not as a module-level or dynamically
+  assigned attribute, and never give a `__SCHEMES`-registered class a
+  leading underscore in its name, or the name-mangled lookup silently
+  misses). If the scheme isn't loaded yet, resolution tries a
+  `pathlib_next.schemes` entry point first, then imports the matching
+  builtin `uri/schemes/*` module — importing any module that defines a
+  `UriPath` subclass registers it. `backend` property — per-instance
+  connection/session state, lazily created via `_initbackend()` (override
+  in a scheme subclass; base returns `None`); `with_backend(backend)`
+  returns a new instance sharing the given backend. `_listdir() ->
+  Iterator[str]` (not implemented by default) / `_scandir()` (derives from
+  `_listdir()` + one `stat()` per child unless overridden directly — prefer
+  overriding `_scandir()` when the listing call already returns
+  type/size/mtime metadata, e.g. WebDAV PROPFIND, FTP MLSD, SFTP
+  `listdir_attr`, an S3 list page). `iterdir()` is provided (drives
+  `_scandir()`); implement `_listdir()` or `_scandir()`, not `iterdir()`
+  itself.
+- **`Source`** (`uri.source`, re-exported at `uri.Source` via `uri/__init__`
+  imports) — `NamedTuple(scheme, userinfo, host, port)`; falsy when every
+  field is empty/`None`. `Source.from_str(source, strict=True) -> Source`
+  (`strict=True` raises `ValueError` if `source` carries a path/query/
+  fragment). `parsed_userinfo() -> (user, password)`. `get_scheme_cls(
+  schemesmap=None) -> type[UriPath]` — resolves (and lazily loads) the
+  scheme class. `is_local()` — DNS lookup, `lru_cache(maxsize=256)`d per
+  `Source` value; never call on a hot path uncached.
+- **`Query(str)`** (`uri.query`) — a URI query string, buildable from a
+  `str`, a sequence of `(key, value)` pairs, or a mapping (`value` may be a
+  sequence to repeat the key). `Query(query, *, encoding="utf-8",
+  separator="&")`. `decode() -> list[tuple[str, str | None]]`,
+  `__iter__()` (iterates decoded pairs), `to_dict(*, single=False) ->
+  dict[str, list[str | None]]` (or `dict[str, str | None]` when
+  `single=True`, last value wins).
+
+Built-in scheme modules live under `uri/schemes/` — see the table in the
+<https://github.com/jose-pr/pathlib_next>. `PATHLIB_NEXT_SFTP_BACKEND` env var (`"paramiko"` /
+`"asyncssh"` / `"auto"`, default `"auto"`) selects the `sftp:` backend;
+precedence is an explicit class attribute > this env var > auto-detect
+(prefers asyncssh if importable). `gs:` honors `STORAGE_EMULATOR_HOST` (set
+into `os.environ` for the `google-cloud-storage` client, e.g. for a local
+emulator) when configured on the path/backend.
+
+## Testing helpers (`pathlib_next.testing`)
+
+Not imported by `pathlib_next/__init__.py` (needs `pytest`, a test-only
+dependency) — import explicitly: `from pathlib_next.testing import
+PathContract`.
+
+- **`PurePathContract`** — pure-path tests (name/suffix/stem, parent/
+  parents, joinpath/`/`, match). Requires only a `root` fixture.
+- **`ReadPathContract(PurePathContract)`** — read-only I/O tests (exists/
+  is_dir/is_file, read_text/read_bytes, iterdir, stat). `root` fixture must
+  point at a directory pre-populated with the standard fixture tree
+  (`a.txt`, `b.py`, `.hidden.txt`, `sub/c.py`, `sub/nested/d.py`,
+  `empty_dir/`).
+- **`PathContract(ReadPathContract)`** — full read/write contract (mkdir,
+  write_text/write_bytes, unlink, rmdir, rm(recursive=True), copy, move,
+  touch(exist_ok=False), mkdir(parents=True)). `root` fixture must be
+  writable.
+
+Subclass one of these with your own `root` fixture to verify a custom
+`Path`/`UriPath` implementation against the shared contract.
+
+## Utilities (`pathlib_next.utils`)
+
+- **`glob.glob(path, *, dironly=False, root_dir=None, recursive=False,
+  include_hidden=False, case_sensitive=None) -> Iterable[path-like]`** — the
+  engine behind `Path.glob()`/`rglob()`; works over anything exposing
+  `iterdir()`/`is_dir()`/`name`/`parents`/`has_glob_pattern()`. Dotfiles are
+  excluded from `*`/`?` matches unless `include_hidden=True`.
+  **`glob.full_match(segments, pattern, case_sensitive) -> bool`** —
+  pathlib 3.13 `full_match()` semantics, `"**"` matches zero or more
+  segments. **`glob.RECURSIVE`** = `"**"`.
+- **`sync.PathSyncer(checksum=None, /, remove_missing=False,
+  follow_symlinks=True, hook=None, ignore_error=False)`** — one-way
+  checksum-driven tree sync between any two `Path` implementations.
+  `checksum` defaults to `utils.checksum.md5`. `.sync(source, target, /,
+  dry_run=False, ignore_error=False)` copies/creates in `target` whatever
+  differs from `source`; `remove_missing=True` also removes `target`
+  entries absent from `source`. `hook`/`.log()`/subclassing `.log()` are the
+  progress/logging seams; `SyncEvent` enum names the events fired.
+  **`sync.PathAndStat`** — a `Path` + cached `stat()` (`None` if missing);
+  `is_*` attribute access delegates to the cached stat, returning a
+  false-returning callable when the path doesn't exist.
+- **`stat.FileStat(FileStatLike)`** — `FileStat(st_mode=None, st_size=0,
+  st_mtime=0, is_dir=False)`, slotted, for backends without a real
+  `os.stat_result` (`MemPath`, `HttpPath`, ...). `FileStat.from_stat(stat)`
+  copies recognized fields from any stat-like object (passes an existing
+  `FileStat` through unchanged). `FileStat.from_path(path, *,
+  follow_symlink=True) -> FileStat | None` (`None` on `FileNotFoundError`).
+  `is_dir()`/`is_file()`/etc. are **methods**, not properties — `if
+  st.is_dir` (no parens) is always truthy.
+- **`checksum.md5(path, chunk_size=65536) -> str`** /
+  **`checksum.sha256(path, chunk_size=65536) -> str`** — streaming file
+  checksums over any `Path`.
+- **`archive.make_archive(src, format, target)`** (`format` is `"zip"` or
+  `"tar"`) / **`archive.unpack_archive(archive, dest)`** (format
+  auto-detected from `archive.name`, falling back to magic-byte sniffing) —
+  stream-first, so `src`/`target`/`archive`/`dest` can be any `Path`
+  implementation, not just local files.
+- **`LRU(func, maxsize=128)`** — thread-safe memoizing cache wrapping
+  `func`, itself callable; `.invalidate(*args)` evicts and recomputes one
+  entry; `.maxsize` is a settable property that evicts down to the new size.
+- **`notimplemented(method)`** — decorator marking a protocol method;
+  raises `NotImplementedError` naming the method when called. Callers that
+  want a graceful fallback catch `NotImplementedError` (e.g. `move()` falls
+  back to copy+unlink when `rename` isn't implemented).
+- **`sizeof_fmt(num) -> str`** — human-readable byte size (`"1.5K"`, ...).
+  **`parsedate(date) -> float`** — epoch seconds from a `str`/
+  `time.struct_time`/`tuple`/`float`; unparseable or `None` input returns
+  `0`, not "now". **`get_machine_ips() -> list[IPv4Address | IPv6Address]`**
+  — `lru_cache(maxsize=1)`d.

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/src/pathlib_next/fspath.py

@@ -115,6 +115,36 @@ class LocalPath(
             self, top_down=top_down, on_error=on_error, follow_symlinks=follow_symlinks
         )
 
+    def copy(
+        self,
+        target,
+        *,
+        overwrite=False,
+        follow_symlinks=True,
+        preserve_metadata=True,
+        recursive=False,
+        ignore_error=None,
+    ):
+        # Python 3.14 added pathlib.Path.copy(), which sits ahead of our
+        # generic implementation in the MRO and does not accept pathlib_next's
+        # overwrite=/recursive=/ignore_error= extensions. Keep LocalPath's
+        # cross-version contract stable by routing explicitly to our method.
+        return _proto.Path.copy(
+            self,
+            target,
+            overwrite=overwrite,
+            follow_symlinks=follow_symlinks,
+            preserve_metadata=preserve_metadata,
+            recursive=recursive,
+            ignore_error=ignore_error,
+        )
+
+    def move(self, target, *, overwrite=False):
+        # Python 3.14 added pathlib.Path.move() alongside copy(); route around
+        # the same MRO collision so overwrite= and the generic fallback remain
+        # available on every supported Python version.
+        return _proto.Path.move(self, target, overwrite=overwrite)
+
     def stat(self, *, follow_symlinks=True):
         # pathlib.Path.stat() (next in MRO via WindowsPath/PosixPath) only
         # accepts follow_symlinks= on 3.10+; below that, lstat() is the
@@ -129,9 +159,7 @@ class LocalPath(
         # platforms without os.lchmod, e.g. Windows).
         if _HAS_FOLLOW_SYMLINKS:
             return super().chmod(mode, follow_symlinks=follow_symlinks)
-        return (
-            super().chmod(mode) if follow_symlinks else super().lchmod(mode)
-        )
+        return super().chmod(mode) if follow_symlinks else super().lchmod(mode)
 
     def glob(
         self,

{pathlib_next-0.8.4 → pathlib_next-0.8.6}/src/pathlib_next/path.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import abc as _abc
 import os as _os
 import re as _re
+import sys as _sys
 import typing as _ty
 
 from . import utils as _utils
@@ -160,7 +161,11 @@ class Pathname(FsPathLike, _ty.Generic[_P]):
     def with_suffix(self, suffix: str) -> _ty.Self:
         """Return a new path with the suffix changed or added."""
         name = self.name
-        if suffix and not suffix.startswith(".") or suffix == ".":
+        if (
+            suffix
+            and not suffix.startswith(".")
+            or (suffix == "." and _sys.version_info < (3, 14))
+        ):
             raise ValueError("Invalid suffix %r" % (suffix))
         if not name:
             raise ValueError("%r has an empty name" % (self,))
@@ -265,11 +270,90 @@ class Pathname(FsPathLike, _ty.Generic[_P]):
 PurePathLike = _ty.Union[str, Pathname]
 
 
+# Operations whose implementation must come from pathlib_next even when a
+# concrete `pathlib` class sits ahead of us in a subclass's MRO. See
+# `Path.__init_subclass__` for why this is needed and how it is applied.
+#
+# Two different, opposite failure modes motivate this list:
+#   * NEW stdlib overriding us: `copy`/`move` landed in CPython 3.14 and
+#     expect the private `_copy_from` protocol, so a downstream
+#     `class X(PosixPathname, Path)` (or any class mixing a concrete
+#     `pathlib` path) either crashes with
+#     `AttributeError: ... has no attribute '_copy_from'` on non-local
+#     backends, or -- worse -- SILENTLY succeeds on local-backed classes
+#     with stdlib's different metadata semantics (it preserves timestamps,
+#     ours preserves st_mode only). That makes mtime-based syncs converge
+#     on 3.14 and never converge on <=3.13.
+#   * OLD stdlib lacking our keywords: `exists(follow_symlinks=)` is 3.12+
+#     and `read_text`/`write_text`'s `newline=` is 3.13+ in CPython, and
+#     `rglob`'s `include_hidden=`/`recursive=`/`dironly=` extensions never
+#     existed there, so on the 3.9 floor the stdlib implementation rejects
+#     keywords this library's protocols promise.
+#
+# `glob`/`walk`/`_scandir` are deliberately absent: `LocalPath` overrides
+# them itself (with local-specific behavior that must be kept), so they are
+# already pathlib_next-owned wherever it matters.
+_OPERATION_NAMES = (
+    "copy",
+    "move",
+    "exists",
+    "rglob",
+    "read_text",
+    "write_text",
+)
+
+
 class Path(Pathname, Chmod, Stat, BinaryOpen):
     """Base class for manipulating paths with I/O."""
 
     __slots__ = ()
 
+    def __init_subclass__(cls, **kwargs):
+        """Guarantee pathlib_next operation precedence in every subclass.
+
+        Concrete path classes are routinely built by mixing a `pathlib`
+        class with this one -- our own `LocalPath` does it, and the
+        documented downstream recipe (`class X(PosixPathname, Path)`) does
+        it transitively. Python's MRO then resolves a name to whichever
+        base declares it first, which for those classes can be `pathlib`
+        rather than `pathlib_next` -- and which one wins changes with the
+        interpreter version, because stdlib `pathlib` keeps gaining and
+        changing methods (see `_OPERATION_NAMES`).
+
+        Rather than making every downstream implementer rediscover this and
+        hand-write forwarding methods, re-assert our implementations here
+        for any subclass that would otherwise inherit a non-pathlib_next
+        one. A subclass (or an intermediate mixin) that defines the method
+        *itself* is always left alone -- this only displaces implementations
+        coming from outside this library.
+        """
+        super().__init_subclass__(**kwargs)
+        for name in _OPERATION_NAMES:
+            # A class that defines the operation in its OWN body is always
+            # authoritative -- never displace a deliberate override (this
+            # also covers `LocalPath.copy`/`move`'s explicit routing).
+            if name in vars(cls):
+                continue
+            # Find which class in the MRO actually supplies the inherited
+            # implementation. Checking the resolved function's `__module__`
+            # is not enough: a downstream mixin may legitimately define the
+            # method in its own module, and that must be honored too.
+            owner = next((base for base in cls.__mro__[1:] if name in vars(base)), None)
+            if owner is None:
+                continue
+            # Only stdlib `pathlib` is displaced. Anything else -- a
+            # downstream mixin, a user base class, or pathlib_next itself --
+            # is a deliberate implementation and is left alone. Matching on
+            # stdlib specifically (rather than "not pathlib_next") is what
+            # keeps this guard from hijacking third-party code.
+            owner_module = getattr(owner, "__module__", "") or ""
+            if owner_module != "pathlib" and not owner_module.startswith("pathlib."):
+                continue
+            ours = getattr(Path, name, None)
+            if ours is None:
+                continue
+            setattr(cls, name, ours)
+
     def __new__(cls, *args, **kwargs):
         if cls is Path:
             from .fspath import LocalPath
@@ -528,9 +612,10 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
         ignore_error: bool | _ty.Callable[[Exception, _ty.Self], bool] = False,
     ):
         """Remove this file or directory, optionally recursively and ignoring errors."""
-        _onerror = lambda _err, _path: (
-            ignore_error(_err, _path) if callable(ignore_error) else bool(ignore_error)
-        )
+        # Same bool-or-callable normalization as copy()/PathSyncer, via the
+        # shared helper. A supplied callable keeps rm()'s own `(error, path)`
+        # arity -- arities differ per call site by design, see the helper.
+        _onerror = _utils.as_error_handler(ignore_error)
 
         def _handle(error, path):
             if not _onerror(error, path):
@@ -617,9 +702,14 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
         (unlike 3.14's False) to match this method's pre-existing behavior
         of always propagating st_mode; only st_mode is preserved, not
         timestamps/xattrs -- full metadata preservation is not implemented.
-        `ignore_error` is a callable matching `Path.rm()`'s contract: when
-        provided, exceptions are passed to it instead of raised; when None
-        (default), fail on the first error.
+        `ignore_error` accepts a bool or a callable, matching `Path.rm()`'s
+        bool-or-callable contract. `True` ignores every error; `False` and
+        `None` (the default) fail on the first error. A callable is invoked
+        as `ignore_error(error)` -- this call site's own arity -- and, as it
+        always has here, is a *notification* hook: the error is suppressed
+        regardless of what it returns, so handlers like `errors.append`
+        (returning None) keep working. Only errors from *child* copies
+        during a `recursive=True` copy are routed here.
         """
         if isinstance(target, str):
             target = type(self)(target)
@@ -644,9 +734,15 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
                         ignore_error=ignore_error,
                     )
                 except Exception as e:
-                    if ignore_error is None:
+                    # A callable stays a notify-and-suppress hook (its return
+                    # value was never consulted here, and callers such as
+                    # `errors.append` rely on that). Bools are new: True
+                    # suppresses, False/None raise -- matching rm()'s bool
+                    # semantics without changing the callable contract.
+                    if callable(ignore_error):
+                        ignore_error(e)
+                    elif not ignore_error:
                         raise
-                    ignore_error(e)
             return
 
         if target.exists():
@@ -693,4 +789,3 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
 
 
 PathLike = _ty.Union[str, Path]
-