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

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

@@ -5,7 +5,137 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.9.0] - 2026-07-29
+
+### Added
+- **`UriPath.host_fspath()`**, and `__fspath__()` now succeeds for schemes
+  with `_host_filesystem_path = True` (currently `sftp:`) instead of
+  unconditionally raising `NotImplementedError` for any non-`file:`
+  scheme. `os.fspath()` has two consumers -- "open this locally" (where a
+  remote path would silently read the wrong file) and "build a command
+  line for a process that runs on the path's host" (`subprocess`, remote
+  executors) -- and only the second is safe for a scheme like `sftp:`.
+  `host_fspath()` is the unambiguous accessor for that second case: it
+  never falls back to local-path semantics the way `__fspath__` does for
+  the `file:` branch.
+- **`progress` callback for `Path.copy()`/`BinaryOpen.copy()`.** `BinaryOpen.copy(target, *, progress=None, chunk_size=shutil.COPY_BUFSIZE)`
+  now streams in caller-sized chunks and, when `progress` is given, calls
+  `progress(bytes_copied, total_size)` after each chunk (`total_size` is the
+  source's `stat().st_size` when available, else `None`). `Path.copy(target,
+  ..., progress=None)` wraps this with per-file identity:
+  `progress(path, bytes_copied, total_size)`, so a `recursive=True` copy
+  reports which file is being streamed alongside its byte progress, not just
+  an anonymous byte stream. `progress=None` (the default) is behaviorally
+  identical to before this change -- no per-chunk overhead, same
+  `shutil.copyfileobj` bytes-on-wire. `SftpPath`'s asyncssh concurrent
+  fan-out (`copy(recursive=True)`) does not invoke `progress` -- native/batch
+  transfer paths are out of scope for this first cut (see
+  `docs/divergences.md`'s "Deliberate extensions" section).
+- **`PathSyncer` can now create symlinks on `target` instead of always
+  rejecting a symlink source.** New constructor kwarg `symlink_mode`
+  (`"preserve"` default, `"reject"` opt-out), consulted only when
+  `follow_symlinks=False` and `source.is_symlink()` (with the default
+  `follow_symlinks=True`, symlinks are still resolved during traversal,
+  unchanged). `"preserve"` creates a matching symlink on `target` using the
+  exact raw, unresolved target string `readlink()` returned -- dangling
+  links and relative targets included, never validated or resolved against
+  `source`'s parent. If `target`'s implementation has no `symlink_to()` at
+  all (every backend except `LocalPath` and `SftpPath`), `"preserve"` mode
+  raises `NotImplementedError` through the existing `ignore_error`/`hook()`
+  flow, same as every other sync branch -- not a silent skip. New
+  `SyncEvent.Symlink` enum member.
+- **Optional backend-native checksum protocol**
+  (`pathlib_next.protocols.checksum.NativeChecksum`,
+  `checksum(algorithm="md5") -> str`). A `Path` subclass may implement it to
+  compute a file digest server-side instead of streaming the content
+  through `open("rb")` -- implemented on `SftpPath` against the OpenSSH
+  `check-file@openssh.com` SFTP protocol extension (paramiko backend only;
+  the asyncssh backend has no equivalent client-library support and
+  correctly falls back). Not part of the base `Path`/`Pathname` ABC -- a
+  plain `Path` has no `.checksum` attribute at all. Implementations MUST
+  raise `NotImplementedError` (never return a value) when they can't
+  produce a genuine digest under the requested algorithm -- this is what
+  keeps two checksums from ever being compared under a mismatched
+  algorithm, or trusting something hash-shaped but not a real content hash
+  (e.g. S3's ETag for a multipart upload, deliberately not implemented here
+  for exactly that reason -- see `docs/divergences.md`). Also adds a
+  companion `supported_checksums() -> frozenset[str]` advisory query
+  (default `frozenset()`, never raises); `SftpPath.supported_checksums()`
+  is a real per-connection probe against the server (paramiko exposes no
+  cheaper way to know), cached per connection.
+- **`PathSyncer`'s default checksum policy now prefers native digests on
+  both sides when available**, falling back to streaming
+  (`utils.checksum.md5`/the new generic `utils.checksum.stream`) when
+  either side can't produce one under the same algorithm -- never a
+  native-vs-streamed comparison under a mismatched algorithm. A
+  caller-supplied `checksum` callable is unaffected (invoked exactly as
+  before). New `utils.checksum.native(path, algorithm) -> str | None`
+  helper: tries the protocol, returns `None` (never raises) if unsupported.
+- **`PathSyncer(..., quick_check=True)`** (new constructor kwarg, default
+  `True`): for a sync pair where at least one side is non-local, a
+  metadata-only pre-check (`st_size` + `st_mtime`, already-cached, no extra
+  round trip) skips the checksum call entirely when both match; a mismatch
+  always falls through to a real checksum rather than being treated as
+  "changed" on its own. Local-to-local pairs never engage this pre-check.
+  `quick_check=False` restores always-checksum behavior for non-local pairs.
+
+### Changed
+- **`PathSyncer` default behavior change**: `PathSyncer(follow_symlinks=
+  False).sync()` on a symlink source previously always raised
+  `NotImplementedError`. It now creates a matching symlink on `target` by
+  default (`symlink_mode="preserve"`); pass `symlink_mode="reject"` to
+  restore the old unconditional-raise behavior exactly.
+- **The `uri` extra now requires `netimps>=0.2.0`** (alongside `uritools`).
+  `Source.is_local()` (`uri.source`) delegates its "is this address mine"
+  check to `netimps.is_local_address()`, which enumerates real network
+  interfaces (`netimps.get_interfaces()`) instead of the previous
+  `socket.getaddrinfo(socket.gethostname(), None)`-based approach, which
+  missed addresses not tied to the resolvable hostname (VMs, containers,
+  VPN interfaces, additional NICs on a multi-homed host). The
+  hostname->address step now uses `netimps.resolve()` (both `"a"`/`"aaaa"`
+  record types; `host` is local if ANY resolved address is) instead of
+  `socket.gethostbyname()` -- `resolve()`'s default backend chain
+  (dnspython, then the OS resolver via `getaddrinfo()`, then `nslookup`)
+  covers the same hosts-file/NSS/DNS resolution `gethostbyname()` did, and
+  additionally never raises for a name that simply doesn't resolve
+  (`resolve()`'s contract: always a list, empty on genuine failure) --
+  `gethostbyname()` raised `socket.gaierror` for that case. `utils.
+  get_machine_ips()` (the old implementation's helper, unused elsewhere in
+  this library) is removed. `SftpPath`'s two backends and `FtpPath` now
+  resolve their default ports (22, 21) via `netimps.get_default_port()`
+  instead of three separately hardcoded literals.
+
+### Fixed
+- **`Source.is_local()` crashed on a bare IPv6-literal `host` string.**
+  `Source(scheme, userinfo, "::1", port)` (a supported direct-construction
+  pattern -- `Source`'s fields are public `NamedTuple` fields) raised
+  `socket.gaierror` instead of returning a result, because
+  `socket.gethostbyname()` (this method's original hostname-resolution
+  step) is IPv4-only. `host` bracket-literals arriving via the normal
+  `Source.from_str()`/`Uri()` construction path were unaffected
+  (`_decode_host()` already parses those into a real `IPv6Address` before
+  `is_local()` ever sees a string). `is_local()` now tries
+  `netimps.try_parse()` first (handles any IP literal directly, string or
+  not) before falling through to hostname resolution.
+- **`uri.source.Source` leaked the password in `str()`/`repr()`.**
+  `Source.__str__()` called `uricompose()` with the raw `userinfo`
+  (password included) -- a genuinely valid, connectable URI string, not
+  just a debug rendering -- and `Source` had no custom `__repr__` at all,
+  so the `NamedTuple` default rendered every field verbatim too. `repr()`
+  is what a traceback frame renders, so a `Source` anywhere on a failing
+  call stack leaked the credential into logs, even though `Uri.__str__()`
+  already redacted. Both now redact the password from `userinfo` the same
+  way `Uri.__str__()` does; the actual data (`.userinfo`,
+  `.parsed_userinfo()`, `["userinfo"]`) is unaffected, only display is
+  sanitized. **This is a behavior change, not purely additive**:
+  `str(source)` (or `f"{source}"`) no longer reconstructs an authenticated
+  URI -- verified nothing in this codebase relied on that (every real
+  connection site reads individual `Source` fields, never whole-object
+  `str()`), but a downstream caller that did would need the new
+  **`Source.as_str(sanitize=True)`** method instead: `sanitize=True` (the
+  default, matching `__str__`) redacts the password; `sanitize=False` is
+  the full, credentialed round trip -- same name/kwarg as
+  `Uri.as_uri(sanitize=)`, so both classes work the same way.
 
 ## [0.8.6] - 2026-07-26
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathlib_next
-Version: 0.8.6
+Version: 0.9.0
 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/
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.9
 Provides-Extra: az
 Requires-Dist: azure-storage-blob; extra == 'az'
+Requires-Dist: netimps>=0.2.0; extra == 'az'
 Requires-Dist: uritools; extra == 'az'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
@@ -31,21 +32,27 @@ Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
 Provides-Extra: gs
 Requires-Dist: google-cloud-storage; extra == 'gs'
+Requires-Dist: netimps>=0.2.0; extra == 'gs'
 Requires-Dist: uritools; extra == 'gs'
 Provides-Extra: http
+Requires-Dist: netimps>=0.2.0; extra == 'http'
 Requires-Dist: requests; extra == 'http'
 Requires-Dist: uritools; extra == 'http'
 Provides-Extra: s3
 Requires-Dist: boto3; extra == 's3'
+Requires-Dist: netimps>=0.2.0; extra == 's3'
 Requires-Dist: uritools; extra == 's3'
 Provides-Extra: sftp
+Requires-Dist: netimps>=0.2.0; extra == 'sftp'
 Requires-Dist: paramiko; extra == 'sftp'
 Requires-Dist: uritools; extra == 'sftp'
 Provides-Extra: sftp-async
 Requires-Dist: asyncssh; (python_version >= '3.10') and extra == 'sftp-async'
 Requires-Dist: asyncssh<2.22; (python_version < '3.10') and extra == 'sftp-async'
+Requires-Dist: netimps>=0.2.0; extra == 'sftp-async'
 Requires-Dist: uritools; extra == 'sftp-async'
 Provides-Extra: uri
+Requires-Dist: netimps>=0.2.0; extra == 'uri'
 Requires-Dist: uritools; extra == 'uri'
 Description-Content-Type: text/markdown
 
@@ -105,7 +112,7 @@ Optional features/extras:
 
 | Extra/flag | Adds | Needed for |
 | --- | --- | --- |
-| `uri` | `uritools` | URI parsing (any `UriPath` scheme) |
+| `uri` | `uritools`, `netimps` | URI parsing (any `UriPath` scheme) |
 | `http` | `requests` | `http(s):` and `dav(s):` (WebDAV) paths |
 | `sftp` | `paramiko` | `sftp:` path operations and transfers (sync backend) |
 | `sftp-async` | `asyncssh` | `sftp:` path operations via the asyncssh backend instead (see `guides/schemes.md`'s `sftp:` row for selection precedence) |

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/README.md

@@ -54,7 +54,7 @@ Optional features/extras:
 
 | Extra/flag | Adds | Needed for |
 | --- | --- | --- |
-| `uri` | `uritools` | URI parsing (any `UriPath` scheme) |
+| `uri` | `uritools`, `netimps` | URI parsing (any `UriPath` scheme) |
 | `http` | `requests` | `http(s):` and `dav(s):` (WebDAV) paths |
 | `sftp` | `paramiko` | `sftp:` path operations and transfers (sync backend) |
 | `sftp-async` | `asyncssh` | `sftp:` path operations via the asyncssh backend instead (see `guides/schemes.md`'s `sftp:` row for selection precedence) |

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/docs/benchmarks.md

@@ -202,6 +202,30 @@ Legend: `p` = `paramiko`, `a` = `asyncssh`.
 - The broad SFTP benchmark is useful for backend comparison even when the
   operation itself is exposed synchronously, because backend internals still
   affect overall throughput.
+- **Native checksum protocol (this release): not benchmarked with a live
+  timing run.** The bytes-transferred claim for this feature is structural,
+  not something wall-clock benchmarking would usefully confirm: when
+  `PathSyncer`'s default policy can use both sides' native digest (e.g.
+  `SftpPath` against an OpenSSH server's `check-file@openssh.com`
+  extension), a file comparison transfers **zero content bytes** for a
+  match-or-mismatch verdict, versus the streaming fallback's full read on
+  *both* sides (`2 * file_size` for an unchanged file that still needs
+  comparing). This project's own SFTP test server (asyncssh's `SFTPServer`,
+  used by `tests/conftest.py::sftp_server`) has no `check-file@openssh.com`
+  support at all, so a live before/after run against it can only exercise
+  the streaming-fallback path, not the native one -- a real OpenSSH server
+  would be needed for genuine native-path timing, which is out of scope for
+  this environment's benchmark harness. `tests/test_sftp.py`'s
+  wire-level-fake tests (`test_paramiko_checksum_*`) are the correctness
+  proof for this release instead.
+- **`PathSyncer(quick_check=True)` (this release):** also structural, same
+  reasoning. For an unchanged non-local file with matching `st_size`/
+  `st_mtime`, the pre-check skips the checksum step (native or streaming)
+  entirely -- **zero content bytes AND zero extension round trips**, versus
+  even the native-checksum path's still-nonzero per-file request. Only
+  applies when metadata already agrees; any mismatch (including a
+  genuinely unchanged file whose mtime wasn't preserved by a prior copy)
+  still pays for a real checksum, same cost as before this release.
 
 ## Caveats
 

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/docs/divergences.md

@@ -61,6 +61,7 @@ these operations itself always keeps its own implementation.
 | `Path.move(target, ...)` | Not in `pathlib` at all | Our own extension: tries `rename()`, falls back to copy+unlink | N/A -- pure extension, no pathlib method to diverge from. |
 | `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 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. |
 | `PathSyncer` / `Query` / `Source` | N/A | Our own extensions | N/A -- pure extensions, no pathlib equivalent. |
+| `PathSyncer(follow_symlinks=False).sync()` on a symlink source | N/A (no pathlib equivalent) | Previously always raised `NotImplementedError`. Now controlled by the new `symlink_mode` constructor kwarg (`"preserve"` default, `"reject"` opt-out): `"preserve"` creates a matching symlink on `target` with the same raw, unresolved target string `readlink()` returned (dangling links and relative targets included, never validated/resolved); `"reject"` restores the exact old unconditional-raise behavior. If `target` can't create symlinks at all (every backend except `LocalPath` and `SftpPath`), `"preserve"` also raises `NotImplementedError`, through the same `ignore_error`/`hook()` machinery as every other sync branch, not a silent skip. **This is a default-behavior change, not a pure extension** -- flagged here because existing callers relying on the old unconditional raise (e.g. to detect and skip symlinks) must now pass `symlink_mode="reject"` explicitly. | Faithful one-way tree mirroring needs symlinks preserved as symlinks by default, not silently dropped/erroring -- discovered via a real cross-host sync use case (hostctl). `follow_symlinks=True` (unchanged default) still resolves through symlinks during traversal, so this only affects callers who already opted into `follow_symlinks=False`. **User decision, 2026-07-28.** |
 | `S3Path` directories | N/A (pathlib directories are real filesystem entries) | `is_dir()` is prefix emulation (any object key under `"<path>/"`); `mkdir()` creates a zero-byte `"<path>/"` marker object; `rmdir()` requires no other keys under that prefix (pathlib-parity "must be empty"). If an exact object key and a `"<path>/"` prefix both exist, exact object operations such as `stat()` and `rm(recursive=True)` treat the path as the object first. | S3 has no native directory concept -- this is the same prefix convention the AWS console itself uses for an empty "folder". Exact-object precedence avoids deleting a prefix tree when the addressed path is a real object. |
 | `GsPath`/`AzPath` directories | N/A (pathlib directories are real filesystem entries) | `is_dir()` is prefix emulation (any blob under `"<path>/"`); `mkdir()` creates a zero-byte `"<path>/"` marker blob; `rmdir()` requires no other blobs under that prefix (pathlib-parity "must be empty"). If an exact object/blob key and a `"<path>/"` prefix both exist, exact object operations such as `stat()` and `rm(recursive=True)` treat the path as the object first. | GCS and Azure Blob have no native directory concept -- same prefix emulation as `S3Path`. Exact-object precedence avoids deleting a prefix tree when the addressed path is a real object. |
 | `GsPath`/`AzPath` `stat().st_mtime` | Real filesystem mtime | Always `0` | Querying just the mtime alone would require separate API calls beyond what the listing/get operations already provide. |
@@ -69,6 +70,9 @@ these operations itself always keeps its own implementation.
 | `GitHubPath` `symlink`/`submodule` tree entries | pathlib exposes `is_symlink()` | Surfaced as a plain file, no distinction | No portable meaning for a submodule (a pointer to another repo, not file content) or a symlink (git stores the link target as the blob content) without extra API calls; not implemented. |
 | `empty_dir/` in a `github:`/`gitlab:` tree | pathlib directories can be empty | Requires a placeholder blob inside (e.g. `.gitkeep`) to exist at all | Git itself has no empty-directory concept -- neither API can return a tree entry for a path with zero blobs under it, so this isn't a library limitation, it's inherent to git. |
 | `HttpPath` `open("a")` default append mode | POSIX `O_APPEND` is atomic (all appends serialized) | Default "rewrite" mode is non-atomic (GET existing + append in client memory + PUT full body) -- concurrent appenders can race | HTTP has no native append primitive; rewrite mode trades atomicity for universality (works on any server that supports PUT). Opt-in "patch" mode using `Content-Range` PATCH is atomic on servers that support it (use `with_session(..., append_mode="patch")`), but raises `PermissionError` if the server rejects it. |
+| `Uri`/`UriPath.__str__()` | `str(pathlib.Path)` round-trips the full path | Drops the password from userinfo (`sftp://u:pw@h/p` -> `"sftp://u@h/p"` via `as_uri(sanitize=True)`) -- reparsing the result gives a *different*, unauthenticated URI | `str()` is what logging/printing reach for; a credentialed URI landing in a log line is worse than a `str()` that doesn't round-trip. Use `as_uri(sanitize=False)` for the full URI including credentials. |
+| `Uri`/`UriPath.__fspath__()` | `os.fspath(pathlib.Path)` always succeeds with a locally-openable path | Raises `NotImplementedError` for any non-`file` scheme, **except** schemes with `_host_filesystem_path = True` (currently `sftp:`), which return `.path` -- a path meaningful on the URI's *own* host, not the local machine | `os.fspath()` has two consumers: "open this locally" (where returning a remote path would silently read the wrong file) and "build a command line for a process that runs on the path's host" (`subprocess`, remote executors) -- correct for the second consumer, wrong for the first. Schemes opt in via `_host_filesystem_path` only when `.path` genuinely is a host filesystem path. `host_fspath()` is the unambiguous accessor for the second use case: it never falls back to treating a path as local. **User decision, 2026-07-28.** |
+| `uri.source.Source.__str__()`/`__repr__()` | `str()` previously called `uricompose()` with the raw `userinfo` -- a genuinely valid, connectable URI including the password; `repr()` used `NamedTuple`'s default, which also renders every field, including `userinfo`, verbatim | Both now redact the password from `userinfo` the same way `Uri.__str__()` does (`root:secret` -> `root`) -- `.userinfo`/`.parsed_userinfo()`/`["userinfo"]` (the actual data-access API) still return the real password; only display is sanitized. `str(source)` no longer reconstructs an authenticated URI -- use the new `Source.as_str(sanitize=False)` for the full round trip (mirrors `Uri.as_uri(sanitize=False)` exactly, same name/kwarg) | `repr()` is what a traceback frame renders, so a `Source` anywhere on a failing call stack used to put the password in the log even though `Uri.__str__()` already redacted -- a caller who saw `Uri` redact reasonably assumed the layer beneath it did too. Same rationale as the `Uri.__str__()` row above. **User decision, 2026-07-29.** |
 
 ## Explicitly out of scope (not implemented on `Pathname`/`Path`)
 
@@ -113,3 +117,50 @@ because a behavioral decision needed documenting:
   **User decision, 2026-07-11.** `include_hidden=`/`dironly=` are documented
   extensions beyond pathlib's `glob()` signature. **Caution:** on remote
   schemes (http/sftp), a recursive glob walks the whole remote subtree.
+- `BinaryOpen.copy(target, *, progress=None, chunk_size=shutil.COPY_BUFSIZE)`
+  / `Path.copy(target, ..., progress=None)`: optional progress-reporting
+  hook, no pathlib equivalent. `BinaryOpen.copy()`'s `progress(bytes_copied,
+  total_size)` fires after each chunk (`total_size` is `None` when the
+  source doesn't implement `Stat` or `stat()` fails); `Path.copy()`'s
+  `progress(path, bytes_copied, total_size)` adds the source `Path` being
+  streamed, so a `recursive=True` copy can report per-file identity
+  alongside byte progress. `chunk_size` is now caller-visible (previously
+  hardcoded to `shutil.copyfileobj`'s default). `progress=None` (the
+  default) is byte-for-byte identical to the prior `shutil.copyfileobj`
+  behavior -- no per-chunk overhead when unused. **Known limitation:**
+  native/batch transfer paths that bypass the generic streaming copy --
+  currently only `SftpPath`'s asyncssh concurrent fan-out
+  (`copy(recursive=True)` on a directory) -- do not invoke `progress`; this
+  was a deliberate scope decision for the first cut (generic-stream-only),
+  not an oversight. **2026-07-28.**
+- `protocols.checksum.NativeChecksum` (`checksum(algorithm="md5") -> str`) --
+  an entirely new, optional protocol with no pathlib equivalent. A `Path`
+  subclass may implement it to compute a file digest server-side (e.g.
+  `SftpPath` against an OpenSSH server's `check-file@openssh.com` SFTP
+  extension) instead of streaming the content through `open("rb")`. Not
+  mixed into the base `Path`/`Pathname` ABC -- most backends never
+  implement it, and a plain `Path` has no `.checksum` attribute at all.
+  **Hard contract, not a style choice:** an implementation MUST raise
+  `NotImplementedError` (never return a value) when it cannot produce a
+  genuine content digest under the requested `algorithm` -- this is what
+  keeps `PathSyncer` (see its class docstring, `utils/sync.py`) from ever
+  comparing a native digest to a streamed one under a mismatched algorithm,
+  or trusting something hash-shaped but not actually a content hash (e.g.
+  S3's ETag for a multipart upload, deliberately NOT implemented here for
+  exactly that reason). `utils.checksum.md5`/`sha256`/`stream` (the
+  pre-existing streaming helpers) are unaffected and keep working for
+  direct callers that don't go through the protocol or `PathSyncer`.
+  `supported_checksums() -> frozenset[str]` (default `frozenset()`) is a
+  companion advisory capability query -- never raises, lets a caller pick a
+  shared algorithm across two paths before calling anything expensive, but
+  is advisory only: `checksum()`'s own `NotImplementedError` contract
+  remains authoritative regardless of what this advertises.
+- `PathSyncer(..., quick_check=True)` -- a new constructor kwarg, no
+  pathlib equivalent. For any sync pair where at least one side is
+  non-local, a metadata-only pre-check (`st_size` + `st_mtime`, from
+  already-cached listing metadata, no extra round trip) skips the checksum
+  call entirely when both already match; a mismatch always falls through
+  to a real checksum rather than being treated as "changed" on its own.
+  Local-to-local pairs never engage this pre-check. `quick_check=False`
+  restores always-checksum behavior for non-local pairs too. **User
+  decision, 2026-07-28.**

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/docs/index.md

@@ -17,7 +17,7 @@ pip install pathlib_next
 
 | Extra | Adds | Needed for |
 | --- | --- | --- |
-| `uri` | `uritools` | `Uri`/`UriPath` parsing (any URI scheme) |
+| `uri` | `uritools`, `netimps` | `Uri`/`UriPath` parsing (any URI scheme) |
 | `http` | `requests` | `http(s)://` and `dav(s)://` (WebDAV) paths |
 | `sftp` | `paramiko` | `sftp://` paths (sync backend) |
 | `sftp-async` | `asyncssh` | `sftp://` paths via the asyncssh backend instead |

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pathlib_next"
-version = "0.8.6"
+version = "0.9.0"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"
@@ -20,7 +20,7 @@ dependencies = []
 uripath = "pathlib_next.tools.uripath:main"
 
 [project.optional-dependencies]
-uri = ["uritools"]
+uri = ["uritools", "netimps>=0.2.0"]
 http = ["requests", "pathlib_next[uri]"]
 sftp = ["paramiko", "pathlib_next[uri]"]
 sftp-async = ["asyncssh<2.22; python_version<'3.10'", "asyncssh; python_version>='3.10'", "pathlib_next[uri]"]

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/src/pathlib_next/AGENTS.md

@@ -64,14 +64,22 @@ pathlib_next`.
     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.
+    preserve_metadata=True, recursive=False, ignore_error=None,
+    progress=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.
+    `progress`, when given, is called as `progress(path, bytes_copied,
+    total_size)` per chunk written for each file streamed (`path` is the
+    source file; `total_size` is `None` if unknown); with `recursive=True`
+    this fires once per copied file, giving per-file identity alongside
+    byte progress. `progress=None` (default) has no per-chunk overhead and
+    is bytewise identical to before this kwarg existed. Not honored by
+    `SftpPath`'s asyncssh concurrent fan-out (native transfer, out of
+    scope) — see `docs/divergences.md`.
   - `move(target, *, overwrite=False)` — tries `rename()` first, falls back
     to `copy(recursive=True)` + `rm(recursive=True)`/`unlink()` when
     `rename()` raises `NotImplementedError`.
@@ -128,8 +136,33 @@ pathlib_next`.
   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`).
+  errors=None, newline=None)`, `copy(target, *, progress=None,
+  chunk_size=shutil.COPY_BUFSIZE)` (streams this object's binary content
+  into another `BinaryOpen`; `progress(bytes_copied, total_size)` fires
+  per chunk when given — `total_size` from `stat().st_size` if `self` also
+  implements `Stat` and it succeeds, else `None`; `progress=None` default
+  is unchanged `shutil.copyfileobj` behavior).
+- **`checksum.NativeChecksum`** — `Protocol`. `checksum(algorithm="md5") ->
+  str` (not implemented by default). Optional, backend-native file digest
+  (e.g. `SftpPath` against the OpenSSH `check-file@openssh.com` SFTP
+  extension) computed server-side instead of streaming content through
+  `open("rb")`. Not mixed into the base `Path`/`Pathname` ABC — a plain
+  `Path` has no `.checksum` attribute at all; a subclass opts in by mixing
+  this protocol in and implementing the method. MUST raise
+  `NotImplementedError` (never return a value) when it can't produce a
+  genuine digest under the requested `algorithm` — see
+  `docs/divergences.md` for why this is a hard contract, not a style
+  choice (the S3-ETag-for-multipart-uploads trap in particular).
+  `supported_checksums() -> frozenset[str]` (default: `frozenset()`) is a
+  companion *advisory* capability query — never raises, lets a caller pick
+  a shared algorithm across two paths (e.g. `source.supported_checksums()
+  & target.supported_checksums()`) without probing via trial-and-error.
+  Advisory only: `checksum()`'s own `NotImplementedError` remains the
+  authoritative per-call contract even if a caller skips this query.
+  `SftpPath.supported_checksums()` is a real per-connection probe (not a
+  static flag) — paramiko exposes no way to read the server's advertised
+  SFTP extension list, so the only reliable signal is an actual attempt,
+  cached per connection.
 
 ## URIs (`pathlib_next.uri`)
 
@@ -151,8 +184,13 @@ extra that depends on it).
   `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`.
+  present). `__fspath__()` succeeds for a `file:`-scheme URI pointing at
+  this machine, and for any scheme with `_host_filesystem_path = True`
+  (currently `sftp:` — returns `.path`, meaningful on that URI's own host,
+  not the local one); otherwise raises `NotImplementedError`. `host_fspath()`
+  is the unambiguous accessor for "path on the URI's own host" — same
+  `_host_filesystem_path` gate, but never falls back to local-path
+  semantics. See `docs/divergences.md`.
 - **`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
@@ -176,12 +214,32 @@ extra that depends on it).
   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.
+  field is empty/`None`. `as_str(sanitize=True) -> str` composes an
+  authority string (`scheme://userinfo@host:port`); `sanitize=True` (the
+  default) drops the password from `userinfo`, `sanitize=False` is the
+  full, credentialed round trip — same name/kwarg as `Uri.as_uri()`, so
+  both classes work the same way. `__str__()` is `as_str(sanitize=True)`;
+  `__repr__()` redacts the same way (`NamedTuple`'s default would render
+  every field, including the password, verbatim — see
+  `docs/divergences.md`). The actual data (`.userinfo`, `parsed_userinfo()`,
+  `["userinfo"]`) is unaffected by any of this, only display is sanitized.
+  `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()` — IP-literal `host` (`str` or
+  `_IPAddress`) skips resolution via `netimps.try_parse()`; otherwise
+  `netimps.resolve(host, "a")` + `resolve(host, "aaaa")` (default backend
+  chain: dnspython, then the OS resolver via `getaddrinfo()` — hosts file,
+  NSS, DNS, OS cache — then `nslookup`; `host` is local if ANY resolved
+  address is; empty result -> not local, never an exception for a
+  genuinely non-resolving name). `netimps.is_local_address()` then decides
+  membership per address (real interface enumeration via
+  `netimps.get_interfaces()`, not DNS-based guessing). `lru_cache
+  (maxsize=256)`d per `Source` value; never call on a hot path uncached.
+  Requires `netimps>=0.2.0` (part of the `uri` extra; `resolve()`'s
+  OS-resolver-chain support landed in 0.2.0 — earlier versions were
+  dnspython-only).
 - **`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",
@@ -230,13 +288,45 @@ Subclass one of these with your own `root` fixture to verify a custom
   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.
+  follow_symlinks=True, symlink_mode="preserve", hook=None,
+  ignore_error=False, quick_check=True)`** — one-way checksum-driven tree
+  sync between any two `Path` implementations. `checksum=None` (the
+  default) resolves to a policy that prefers each side's
+  `protocols.checksum.NativeChecksum.checksum()` (no network transfer
+  needed just to decide whether a copy is needed) over streaming, but only
+  trusts a native digest from one side if the OTHER side can also produce a
+  digest under the same algorithm (native or streamed) — otherwise BOTH
+  sides fall back to streaming (`utils.checksum.md5`/`stream`), never a
+  native-vs-streamed comparison under a mismatched algorithm. A
+  caller-supplied `checksum` callable disables this entirely and is invoked
+  exactly as before (once per side, compared with `==`). `quick_check=True`
+  (default) adds a metadata-only pre-check (`st_size` + `st_mtime`, already
+  cached, no extra round trip) for any pair where at least one side is
+  non-local (`Uri.is_local()`/DNS-lookup-failure-safe; a side without
+  `is_local()` at all is treated as local) — both matching skips the
+  checksum call entirely; either differing always falls through to a real
+  checksum (never concludes "changed" from metadata alone). Local-to-local
+  pairs never engage this pre-check regardless of the flag's value.
+  `quick_check=False` disables the pre-check entirely.
+  `.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`.
+  `follow_symlinks=True` (default) resolves through a symlink source during
+  traversal exactly like content sync (unchanged). With
+  `follow_symlinks=False`, a symlink source is reported as such and
+  `symlink_mode` decides what happens: `"preserve"` (default) creates a
+  matching symlink on `target` using the exact raw, unresolved target
+  string `readlink()` returned — dangling links and relative targets
+  included, never validated or resolved against `source`'s parent;
+  `"reject"` raises `NotImplementedError` instead (the sole behavior before
+  this kwarg existed). If `target`'s implementation has no `symlink_to()`
+  at all (every backend except `LocalPath` and `SftpPath` — see
+  `docs/divergences.md`), `"preserve"` mode also raises
+  `NotImplementedError`, through the same `ignore_error`/`hook()` flow as
+  every other branch, not a silent skip. `hook`/`.log()`/subclassing
+  `.log()` are the progress/logging seams; `SyncEvent` enum names the
+  events fired (`SyncEvent.Symlink` covers symlink creation, replacement,
+  and the not-implemented/error path alike).
   **`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.
@@ -250,7 +340,13 @@ Subclass one of these with your own `root` fixture to verify a custom
   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`.
+  checksums over any `Path`. **`checksum.stream(path, algorithm="md5",
+  chunk_size=65536) -> str`** — the generic (runtime `algorithm`) form of
+  the above, used by `PathSyncer`'s streaming fallback. **`checksum.native(
+  path, algorithm="md5") -> str | None`** — tries `path.checksum(algorithm)`
+  (`protocols.checksum.NativeChecksum`); returns `None` (never raises) if
+  `path` doesn't implement the protocol at all, or raises
+  `NotImplementedError` for `algorithm`.
 - **`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) —

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

@@ -124,11 +124,13 @@ class LocalPath(
         preserve_metadata=True,
         recursive=False,
         ignore_error=None,
+        progress=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.
+        # overwrite=/recursive=/ignore_error=/progress= extensions. Keep
+        # LocalPath's cross-version contract stable by routing explicitly to
+        # our method.
         return _proto.Path.copy(
             self,
             target,
@@ -137,6 +139,7 @@ class LocalPath(
             preserve_metadata=preserve_metadata,
             recursive=recursive,
             ignore_error=ignore_error,
+            progress=progress,
         )
 
     def move(self, target, *, overwrite=False):

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

@@ -692,6 +692,7 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
         preserve_metadata=True,
         recursive=False,
         ignore_error=None,
+        progress: "_ty.Callable[[_ty.Self, int, _ty.Optional[int]], None]" = None,
     ):
         """Copy this file's content to `target`.
 
@@ -710,6 +711,19 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
         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.
+
+        `progress`, when given, is called as `progress(path, bytes_copied,
+        total_size)` for every chunk written during each *file* copy (`path`
+        is the source `Path` being streamed -- `self` for a single-file
+        copy, or the relevant child during a `recursive=True` copy).
+        `bytes_copied` increases monotonically per file and reaches
+        `total_size` (or `None` if the size couldn't be determined) at the
+        end of that file. Directories themselves don't get a progress call
+        (only the files inside them do). With `progress=None` (the
+        default), behavior is unchanged -- no per-chunk overhead. Native
+        backend transfers that bypass the generic streaming copy (e.g.
+        `SftpPath`'s asyncssh concurrent fan-out) do not invoke `progress`;
+        see `docs/divergences.md`'s "Deliberate extensions" section.
         """
         if isinstance(target, str):
             target = type(self)(target)
@@ -732,6 +746,7 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
                         preserve_metadata=preserve_metadata,
                         recursive=True,
                         ignore_error=ignore_error,
+                        progress=progress,
                     )
                 except Exception as e:
                     # A callable stays a notify-and-suppress hook (its return
@@ -752,7 +767,14 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
                 target.unlink()
             else:
                 raise FileExistsError(target)
-        BinaryOpen.copy(src, target)
+        if progress is None:
+            BinaryOpen.copy(src, target)
+        else:
+            BinaryOpen.copy(
+                src,
+                target,
+                progress=lambda copied, total: progress(src, copied, total),
+            )
 
         if preserve_metadata:
             try:

{pathlib_next-0.8.6 → pathlib_next-0.9.0}/src/pathlib_next/protocols/__init__.py

@@ -1,2 +1,3 @@
 from .fs import *
 from .io import *
+from .checksum import *