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

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

@@ -5,6 +5,28 @@ 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/).
 
+## [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
@@ -710,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.9.0 → pathlib_next-0.9.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
-Name: pathlib_next
-Version: 0.9.0
+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
@@ -16,6 +16,7 @@ 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'
@@ -58,11 +59,11 @@ 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
@@ -70,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
 
@@ -88,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.
@@ -100,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
 
@@ -186,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.9.0 → 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
 
@@ -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.9.0 → pathlib_next-0.9.1}/docs/divergences.md

@@ -60,6 +60,9 @@ 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. |

{pathlib_next-0.9.0 → 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.9.0 → pathlib_next-0.9.1}/pyproject.toml

@@ -3,8 +3,16 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
-name = "pathlib_next"
-version = "0.9.0"
+# 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"
@@ -27,7 +35,7 @@ sftp-async = ["asyncssh<2.22; python_version<'3.10'", "asyncssh; python_version>
 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"]

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

@@ -4,7 +4,7 @@ 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
+<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.
 
@@ -63,6 +63,17 @@ pathlib_next`.
     `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.
+  - `_symlink_to(target, target_is_directory=False)` (not implemented by
+    default) / `symlink_to(target, target_is_directory=False, *,
+    force=False)` — same primitive/wrapper split as `_mkdir`/`mkdir`: a
+    backend implements only `_symlink_to()` and receives an already
+    normalized path object (a `str` target is turned into one by the
+    wrapper, as `copy()`/`move()` do), then reads the raw target string the
+    way its transport needs (`Uri.path` on the wire, `os.fspath()`
+    locally). `force=` is this library's extension: `False` is
+    stdlib-exact, `True` unlinks an existing **non-directory** entry at the
+    link path first (never a directory) and is **not** atomic. Listed in
+    `_OPERATION_NAMES`, since no stdlib version accepts `force=`.
   - `copy(target, *, overwrite=False, follow_symlinks=True,
     preserve_metadata=True, recursive=False, ignore_error=None,
     progress=None)` — `follow_symlinks`/`preserve_metadata` names match
@@ -130,7 +141,20 @@ pathlib_next`.
   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)`.
+  implemented by default); derives `lchmod(mode)`. `mode` may be a `str`,
+  parsed as **octal** (`"0755"` == `"755"` == `0o755`); a non-octal digit
+  raises `ValueError`. Each backend overrides `chmod()` directly (each has
+  real per-scheme logic), so all of them normalize through
+  `utils.as_mode()` — the shared helper is what keeps the base from
+  drifting between them.
+  Also `chown(uid=None, gid=None, *, follow_symlinks=True)` over a
+  `_chown(uid, gid, *, follow_symlinks=True)` backend primitive (not
+  implemented by default). Extension: `pathlib` has `owner()`/`group()`
+  readers but no writer. `None` leaves a field unchanged and `-1` is an
+  alias for it; an `int` is an id, a `str` is a name. `chown()` normalizes
+  via `utils.as_owner()` and short-circuits when nothing would change, so
+  `_chown()` always receives a canonical pair and only converts to its own
+  wire spelling (`-1` for `os.chown`, an omitted attr for SFTP).
 - **`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,
@@ -249,7 +273,7 @@ extra that depends on it).
   `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"` /
+<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

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

@@ -6,11 +6,13 @@ import os as _os
 import pathlib as _path
 import posixpath as _posixpath
 import re as _re
+import shutil as _shutil
 import sys as _sys
 import types as _types
 import typing as _ty
 
 from . import path as _proto
+from . import utils as _utils
 from .utils.stat import FileStat as _FileStat
 
 # pathlib.Path.stat()/chmod() only accept follow_symlinks= on 3.10+; below
@@ -148,6 +150,20 @@ class LocalPath(
         # available on every supported Python version.
         return _proto.Path.move(self, target, overwrite=overwrite)
 
+    def _symlink_to(
+        self, target: _proto.Path | str, target_is_directory: bool = False
+    ) -> None:
+        # `symlink_to` is in _OPERATION_NAMES, so the generic
+        # `Path.symlink_to()` (which owns `force=`) is what resolves on
+        # LocalPath -- it delegates the actual link creation here, and
+        # stdlib's own implementation is reached explicitly via super().
+        # Unlike every remote scheme, target_is_directory is meaningful
+        # here: it is the Windows-only flag pathlib forwards to
+        # os.symlink(). stdlib accepts any os.PathLike, so the normalized
+        # path object goes straight through -- and a relative target stays
+        # relative, exactly as before.
+        return super().symlink_to(target, target_is_directory)
+
     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
@@ -156,14 +172,42 @@ class LocalPath(
             return super().stat(follow_symlinks=follow_symlinks)
         return super().stat() if follow_symlinks else super().lstat()
 
-    def chmod(self, mode, *, follow_symlinks=True):
+    def chmod(self, mode: int | str, *, follow_symlinks: bool = True):
         # Same follow_symlinks= 3.10+ gap as stat() above; lchmod() is the
         # pre-existing equivalent (raises NotImplementedError itself on
         # platforms without os.lchmod, e.g. Windows).
+        mode = _utils.as_mode(mode)
         if _HAS_FOLLOW_SYMLINKS:
             return super().chmod(mode, follow_symlinks=follow_symlinks)
         return super().chmod(mode) if follow_symlinks else super().lchmod(mode)
 
+    def _chown(
+        self,
+        uid: int | str | None,
+        gid: int | str | None,
+        *,
+        follow_symlinks: bool = True,
+    ) -> None:
+        # shutil.chown() is the stdlib spelling that accepts names as well
+        # as ids, and it takes None for "leave unchanged" -- the same
+        # canonical form Chmod.chown() already normalized to, so the pair
+        # passes straight through. os.chown's -1 sentinel never appears
+        # here.
+        if not follow_symlinks:
+            if not hasattr(_os, "lchown"):
+                raise NotImplementedError("chown(follow_symlinks=False)")
+            if isinstance(uid, str) or isinstance(gid, str):
+                # os.lchown takes numeric ids only; resolving a name would
+                # mean duplicating shutil's lookup, and guessing wrong here
+                # writes the wrong owner silently.
+                raise NotImplementedError(
+                    "chown(follow_symlinks=False) requires numeric uid/gid"
+                )
+            return _os.lchown(
+                self, -1 if uid is None else uid, -1 if gid is None else gid
+            )
+        return _shutil.chown(self, uid, gid)
+
     def glob(
         self,
         pattern: str | _proto.FsPathLike,

{pathlib_next-0.9.0 → pathlib_next-0.9.1}/src/pathlib_next/mempath.py

@@ -91,9 +91,7 @@ class MemPath(Path):
             # implementation-defined root) and doesn't collapse it, which
             # broke MemPath("/") (as_posix() == "/") into a bogus "//".
             posix = self.as_posix().lstrip("/")
-            self._normalized = (
-                _posix.normpath("/" + posix).removeprefix("/").split("/")
-            )
+            self._normalized = _posix.normpath("/" + posix).removeprefix("/").split("/")
         return self._normalized
 
     @property

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

@@ -288,7 +288,10 @@ PurePathLike = _ty.Union[str, Pathname]
 #     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.
+#     keywords this library's protocols promise. `symlink_to`'s `force=`
+#     is the same shape: no stdlib version has ever accepted it, so
+#     without this guard `LocalPath().symlink_to(t, force=True)` raises
+#     TypeError while every other backend honors it.
 #
 # `glob`/`walk`/`_scandir` are deliberately absent: `LocalPath` overrides
 # them itself (with local-specific behavior that must be kept), so they are
@@ -300,6 +303,7 @@ _OPERATION_NAMES = (
     "rglob",
     "read_text",
     "write_text",
+    "symlink_to",
 )
 
 
@@ -683,6 +687,68 @@ class Path(Pathname, Chmod, Stat, BinaryOpen):
         """Rename this file or directory to the given target."""
         ...
 
+    @_utils.notimplemented
+    def _symlink_to(
+        self, target: "_ty.Self", target_is_directory: bool = False
+    ) -> None:
+        """Create a symlink at this path pointing at `target`.
+
+        The backend primitive behind `symlink_to()`, in the same shape as
+        `_mkdir`/`_open`: implement only this, and the generic conveniences
+        (`force=`) come for free. `target` has already been normalized to a
+        path object of this class by `symlink_to()` -- accepting `str` and
+        turning it into a path is the wrapper's job, not the primitive's.
+
+        Implementations take the raw target string from the path object the
+        way their own backend needs it (`Uri.path` for wire protocols,
+        `os.fspath()`/`as_posix()` locally); it never carries a scheme or
+        host prefix, and a relative target stays relative.
+        """
+        ...
+
+    def symlink_to(
+        self,
+        target: "_ty.Self | str",
+        target_is_directory: bool = False,
+        *,
+        force: bool = False,
+    ) -> None:
+        """Make this path a symlink pointing to `target`.
+
+        Signature-compatible with `pathlib.Path.symlink_to()`; `force` is a
+        pathlib_next extension (see `docs/divergences.md`).
+
+        With `force=True`, an existing entry at *this* path is removed
+        first. No filesystem or transport offers an atomic "replace a
+        symlink" operation, so this is an unlink-then-symlink sequence and
+        is therefore **not** atomic: between the two steps the path does not
+        exist, and a concurrent writer can win the race. It is a
+        convenience, not a locking primitive.
+
+        Only a non-directory entry is removed -- an existing *directory* at
+        the link path is left alone and the underlying `FileExistsError`
+        (or the backend's equivalent) propagates. Silently deleting a
+        directory tree is never what `force=` on a symlink call is asking
+        for.
+        """
+        # Normalize a str target to a path object, so the primitive only
+        # ever handles one type -- same `type(self)(target)` form as
+        # copy()/move() use for their destination, for consistency.
+        if isinstance(target, str):
+            target = type(self)(target)
+        if force:
+            try:
+                self.unlink(missing_ok=True)
+            except (IsADirectoryError, PermissionError, OSError) as error:
+                # A directory at the link path (POSIX: IsADirectoryError;
+                # Windows and several remote backends: PermissionError or a
+                # plain OSError) is not something force= should remove.
+                # Let the symlink attempt below raise the error that
+                # actually describes the conflict.
+                if not self.is_dir():
+                    raise error
+        return self._symlink_to(target, target_is_directory)
+
     def copy(
         self,
         target: "Path | str",

{pathlib_next-0.9.0 → pathlib_next-0.9.1}/src/pathlib_next/protocols/fs.py

@@ -110,15 +110,75 @@ class Chmod(_ty.Protocol):
     __slots__ = ()
 
     @_utils.notimplemented
-    def chmod(self, mode: int, *, follow_symlinks=True):
+    def chmod(self, mode: int | str, *, follow_symlinks: bool = True):
         """
         Change the permissions of the path, like os.chmod().
+
+        Extension: `mode` may be a `str`, which is parsed as **octal**
+        (`"0755"`, `"755"` and `0o755` all mean the same thing) -- see
+        `utils.as_mode()` for why the base is never left implicit.
+
+        Every implementation normalizes its argument through
+        `utils.as_mode()` on entry. Unlike `symlink_to`/`chown`, `chmod` is
+        overridden directly by each backend (each has real per-scheme logic
+        -- version shims, capability gates, a `SITE CHMOD` command), so
+        there is no single wrapper to hang the conversion on; the shared
+        helper is what keeps the base from drifting between them.
         """
         ...
 
-    def lchmod(self, mode: int):
+    def lchmod(self, mode: int | str):
         """
         Like chmod(), except if the path points to a symlink, the symlink's
         permissions are changed, rather than its target's.
         """
         self.chmod(mode, follow_symlinks=False)
+
+    @_utils.notimplemented
+    def _chown(
+        self,
+        uid: int | str | None,
+        gid: int | str | None,
+        *,
+        follow_symlinks: bool = True,
+    ) -> None:
+        """Backend primitive behind `chown()`.
+
+        Receives an already-canonical `(uid, gid)` pair: `int` to set, or
+        `None` for "leave unchanged" (a `str` is a user/group *name*).
+        Convert only to this backend's own wire spelling -- `-1` for
+        `os.chown`, an omitted attr field for SFTP `setstat`. Normalizing
+        the caller's input is `chown()`'s job, not the primitive's.
+        """
+        ...
+
+    def chown(
+        self,
+        uid: int | str | None = None,
+        gid: int | str | None = None,
+        *,
+        follow_symlinks: bool = True,
+    ) -> None:
+        """Change the owner and/or group of the path.
+
+        Extension: `pathlib.Path` has `owner()`/`group()` **readers** but no
+        writer (the stdlib equivalent is `shutil.chown`/`os.chown`), so
+        ownership was the one attribute `stat()` could report -- via
+        `st_uid`/`st_gid` -- and nothing could write back.
+
+        `None` (the default) leaves a field unchanged, which is what lets a
+        caller set the group without knowing the owner. `-1` is accepted as
+        an alias for `None`, matching `os.chown`'s own sentinel. An `int` is
+        a uid/gid; a `str` is a user/group name, passed through for backends
+        that can resolve one.
+
+        Backends implement `_chown()` and receive an already-canonical pair
+        (see `utils.as_owner()`), so the "unchanged" semantics cannot drift
+        between schemes.
+        """
+        uid, gid = _utils.as_owner(uid, gid)
+        if uid is None and gid is None:
+            # Nothing to change -- don't spend a round trip (or make a
+            # backend decide what an all-sentinel call means).
+            return
+        return self._chown(uid, gid, follow_symlinks=follow_symlinks)

{pathlib_next-0.9.0 → pathlib_next-0.9.1}/src/pathlib_next/testing.py

@@ -11,6 +11,7 @@ which is a test-only dependency. Import it explicitly:
         def root(self, tmp_path):
             return MyPath(tmp_path)
 """
+
 import pytest
 
 
@@ -22,7 +23,7 @@ class PurePathContract:
         assert p.name == "file.txt"
         assert p.suffix == ".txt"
         assert p.stem == "file"
-        
+
         # parent and parents
         assert p.parent.name == "dir"
         assert len(p.parents) >= 2
@@ -55,7 +56,7 @@ class ReadPathContract(PurePathContract):
     def test_exists_and_types(self, root):
         assert root.exists()
         assert root.is_dir()
-        
+
         a = root / "a.txt"
         assert a.exists()
         assert a.is_file()
@@ -94,7 +95,7 @@ class PathContract(ReadPathContract):
 
     Subclasses must provide a `root` fixture pointing to a writable directory
     pre-populated with the standard `fixture_tree` (see conftest.py).
-    
+
     Note: ftp/dav/s3 stay mock-unit-only because their hand-rolled fakes
     aren't faithful enough for a generic contract.
     """