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

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

@@ -5,7 +5,159 @@ 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.1] - 2026-08-04
+
+### Added
+- **`symlink_to(..., force=True)`** — replace an existing entry at the link
+  path instead of failing. SFTP has no atomic "replace symlink", so every
+  consumer was re-implementing the unlink-then-symlink dance. Implemented at
+  the `Path` layer over a new `_symlink_to()` backend primitive (the same
+  wrapper/primitive split as `_mkdir`/`mkdir`), so all backends inherit it.
+  Removes a **non-directory** entry only, and is documented as non-atomic.
+- **`chown(uid=None, gid=None)`** over a new `_chown()` backend primitive.
+  `chown` was the one POSIX permission attribute `stat()` could read but
+  nothing could write back. `None` means "leave unchanged"; the normalization
+  lives on `Path` so each backend receives an already-canonical pair rather
+  than re-deriving the mapping (`os.chown` wants `-1`, SFTP omits the field).
+- **`chmod()` accepts a string octal mode** (`"0755"`), normalized with an
+  explicit base-8 parse. A mode string outside `[0-7]` raises rather than
+  being coerced — `int("0755")` in *decimal* is a different mode, which is
+  exactly the wrong-but-plausible failure this guards.
+
+### Changed
+- Adopted `black`, pinned to the 3.9 floor; `src/` and `tests/` reformatted.
+
+## [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
 
@@ -580,17 +732,18 @@ 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.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
-[0.8.1]: https://github.com/jose-pr/pathlib_next/compare/v0.8.0...v0.8.1
-[0.8.0]: https://github.com/jose-pr/pathlib_next/compare/v0.7.0...v0.8.0
-[0.7.0]: https://github.com/jose-pr/pathlib_next/compare/v0.6.0...v0.7.0
-[0.6.0]: https://github.com/jose-pr/pathlib_next/compare/v0.5.0...v0.6.0
-[0.5.0]: https://github.com/jose-pr/pathlib_next/compare/v0.4.1...v0.5.0
-[0.4.1]: https://github.com/jose-pr/pathlib_next/compare/v0.4.0...v0.4.1
-[0.4.0]: https://github.com/jose-pr/pathlib_next/releases/tag/v0.4.0
-[0.3.5]: https://github.com/jose-pr/pathlib_next/releases/tag/v0.3.5
+[Unreleased]: https://github.com/jose-pr/pathlib-next/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/jose-pr/pathlib-next/compare/v0.9.0...v0.9.1
+[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
+[0.8.1]: https://github.com/jose-pr/pathlib-next/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/jose-pr/pathlib-next/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/jose-pr/pathlib-next/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/jose-pr/pathlib-next/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/jose-pr/pathlib-next/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/jose-pr/pathlib-next/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/jose-pr/pathlib-next/releases/tag/v0.4.0
+[0.3.5]: https://github.com/jose-pr/pathlib-next/releases/tag/v0.3.5

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
-Name: pathlib_next
-Version: 0.8.6
+Name: pathlib-next
+Version: 0.9.1
 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/
-Project-URL: Issues, https://github.com/jose-pr/pathlib_next/issues
+Project-URL: Homepage, https://github.com/jose-pr/pathlib-next/
+Project-URL: Documentation, https://jose-pr.github.io/pathlib-next/
+Project-URL: Issues, https://github.com/jose-pr/pathlib-next/issues
 Author: Jose A
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -13,8 +13,10 @@ 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: black; extra == 'dev'
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: cheroot; extra == 'dev'
 Requires-Dist: hatchling; extra == 'dev'
@@ -31,31 +33,37 @@ 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
 
 # pathlib_next
 
-[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
-[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib-next/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib-next/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib_next/)
-[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib_next/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib-next/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib-next/actions/workflows/test.yml)
 
 A **robust, extensible pathlib-like base** for any resource addressable as a
 path or URI. Same method names, signatures, semantics, and exception types as
@@ -63,7 +71,7 @@ path or URI. Same method names, signatures, semantics, and exception types as
 against `Path`/`UriPath` and it works against your local disk, an in-memory
 tree, an HTTP index, or an SFTP server. Every intentional divergence from
 `pathlib`'s behavior is documented, not silent -- see
-[`docs/divergences.md`](https://jose-pr.github.io/pathlib_next/divergences/).
+[`docs/divergences.md`](https://jose-pr.github.io/pathlib-next/divergences/).
 
 ## Features
 
@@ -81,7 +89,7 @@ tree, an HTTP index, or an SFTP server. Every intentional divergence from
 
 Every scheme shares the same `glob()`, `walk()`, `copy()`/`move()`, `rm()`
 implementations -- see the full matrix and notes in
-[Schemes](https://jose-pr.github.io/pathlib_next/guides/schemes/).
+[Schemes](https://jose-pr.github.io/pathlib-next/guides/schemes/).
 
 - **Unified path interface** across local files, in-memory paths, archive
   members, and `file`/`data`/`ftp`/`http`/`dav`/`sftp`/`s3` URIs.
@@ -93,7 +101,7 @@ implementations -- see the full matrix and notes in
   authority components.
 - **Extensible two ways**: subclass `Path` directly for a custom
   non-URI resource, or subclass `UriPath` for a new URI scheme -- see
-  [Extending](https://jose-pr.github.io/pathlib_next/guides/extending/).
+  [Extending](https://jose-pr.github.io/pathlib-next/guides/extending/).
 
 ## Installation
 
@@ -105,7 +113,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) |
@@ -179,13 +187,13 @@ print(member.read_text())
 Also built in: `data:` (RFC 2397 inline payloads), `ftp(s):` (stdlib
 `ftplib`), `dav(s):` (WebDAV, full read/write over HTTP), and `s3:`
 (`boto3`) -- one example per scheme in
-[Schemes](https://jose-pr.github.io/pathlib_next/guides/schemes/).
+[Schemes](https://jose-pr.github.io/pathlib-next/guides/schemes/).
 
 ## Extending
 
 Two first-class ways to add a new path-addressable resource -- both covered
 in depth, with worked examples, in
-[Extending](https://jose-pr.github.io/pathlib_next/guides/extending/):
+[Extending](https://jose-pr.github.io/pathlib-next/guides/extending/):
 
 - Subclass `Path` directly for a custom, non-URI resource (`MemPath` is the
   reference exemplar).

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

@@ -1,10 +1,10 @@
 # pathlib_next
 
-[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
-[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib-next/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib-next/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib_next/)
-[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib_next/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib-next/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib-next/actions/workflows/test.yml)
 
 A **robust, extensible pathlib-like base** for any resource addressable as a
 path or URI. Same method names, signatures, semantics, and exception types as
@@ -12,7 +12,7 @@ path or URI. Same method names, signatures, semantics, and exception types as
 against `Path`/`UriPath` and it works against your local disk, an in-memory
 tree, an HTTP index, or an SFTP server. Every intentional divergence from
 `pathlib`'s behavior is documented, not silent -- see
-[`docs/divergences.md`](https://jose-pr.github.io/pathlib_next/divergences/).
+[`docs/divergences.md`](https://jose-pr.github.io/pathlib-next/divergences/).
 
 ## Features
 
@@ -30,7 +30,7 @@ tree, an HTTP index, or an SFTP server. Every intentional divergence from
 
 Every scheme shares the same `glob()`, `walk()`, `copy()`/`move()`, `rm()`
 implementations -- see the full matrix and notes in
-[Schemes](https://jose-pr.github.io/pathlib_next/guides/schemes/).
+[Schemes](https://jose-pr.github.io/pathlib-next/guides/schemes/).
 
 - **Unified path interface** across local files, in-memory paths, archive
   members, and `file`/`data`/`ftp`/`http`/`dav`/`sftp`/`s3` URIs.
@@ -42,7 +42,7 @@ implementations -- see the full matrix and notes in
   authority components.
 - **Extensible two ways**: subclass `Path` directly for a custom
   non-URI resource, or subclass `UriPath` for a new URI scheme -- see
-  [Extending](https://jose-pr.github.io/pathlib_next/guides/extending/).
+  [Extending](https://jose-pr.github.io/pathlib-next/guides/extending/).
 
 ## Installation
 
@@ -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) |
@@ -128,13 +128,13 @@ print(member.read_text())
 Also built in: `data:` (RFC 2397 inline payloads), `ftp(s):` (stdlib
 `ftplib`), `dav(s):` (WebDAV, full read/write over HTTP), and `s3:`
 (`boto3`) -- one example per scheme in
-[Schemes](https://jose-pr.github.io/pathlib_next/guides/schemes/).
+[Schemes](https://jose-pr.github.io/pathlib-next/guides/schemes/).
 
 ## Extending
 
 Two first-class ways to add a new path-addressable resource -- both covered
 in depth, with worked examples, in
-[Extending](https://jose-pr.github.io/pathlib_next/guides/extending/):
+[Extending](https://jose-pr.github.io/pathlib-next/guides/extending/):
 
 - Subclass `Path` directly for a custom, non-URI resource (`MemPath` is the
   reference exemplar).

{pathlib_next-0.8.6 → pathlib_next-0.9.1}/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.1}/docs/divergences.md

@@ -60,7 +60,11 @@ these operations itself always keeps its own implementation.
 | `Path.copy(target, ...)` | CPython 3.14 `Path.copy(target, *, follow_symlinks=True, dirs_exist_ok=False, preserve_metadata=False)`; always raises if `target` exists | Ours predates 3.14. Signature: `copy(target, *, overwrite=False, follow_symlinks=True, preserve_metadata=True)`. `overwrite=True` unlinks an existing non-directory target first; `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, ...)` | 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. |
+| `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. | 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. |
 | `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 +73,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 +120,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.1}/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.1}/mkdocs.yml

@@ -1,8 +1,8 @@
 site_name: pathlib_next
 site_description: Generic Path Protocol based pathlib
-site_url: https://jose-pr.github.io/pathlib_next/
-repo_url: https://github.com/jose-pr/pathlib_next
-repo_name: jose-pr/pathlib_next
+site_url: https://jose-pr.github.io/pathlib-next/
+repo_url: https://github.com/jose-pr/pathlib-next
+repo_name: jose-pr/pathlib-next
 edit_uri: edit/main/docs/
 
 theme:

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

@@ -3,8 +3,16 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
-name = "pathlib_next"
-version = "0.8.6"
+# The DISTRIBUTION name, hyphenated to match what PyPI displays and what
+# `pip install pathlib-next` takes. PEP 503 normalises `_` to `-`, so this
+# was already published as `pathlib-next`; spelling it that way here just
+# stops the repo, the docs and the index from disagreeing.
+#
+# The IMPORT name stays `pathlib_next` (`packages` below, and every
+# `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.1"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"
@@ -20,14 +28,14 @@ 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]"]
 s3 = ["boto3", "pathlib_next[uri]"]
 gs = ["google-cloud-storage", "pathlib_next[uri]"]
 az = ["azure-storage-blob", "pathlib_next[uri]"]
-dev = ['build', 'twine', 'hatchling', 'pytest', 'pytest-cov', 'pyftpdlib', 'wsgidav', 'cheroot', 'moto[s3]', 'hypothesis']
+dev = ['build', 'twine', 'hatchling', 'pytest', 'pytest-cov', 'pyftpdlib', 'wsgidav', 'cheroot', 'moto[s3]', 'hypothesis', 'black']
 docs = ['mkdocs', 'mkdocs-material', 'mkdocstrings[python]']
 
 [project.entry-points."pathlib_next.schemes"]
@@ -54,9 +62,9 @@ git = "pathlib_next.uri.schemes.git:GitPath"
 "git+gitlab" = "pathlib_next.uri.schemes.git:GitLabGitPath"
 
 [project.urls]
-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"
+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
@@ -74,6 +82,11 @@ exclude = ["/.*", "/benchmarks"]
 packages = ["src/pathlib_next"]
 
 
+[tool.black]
+# Pinned to the project's *minimum* supported Python so black never emits
+# syntax the 3.9 floor cannot parse.
+target-version = ["py39"]
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]