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

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

@@ -5,6 +5,74 @@ 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.2] - 2026-08-16
+
+### Fixed
+- **`MemPath.open("w")` on an existing directory raised nothing and destroyed
+  the tree.** `_open()` assigned over whatever was already at the name, so
+  `MemPath("dir").write_text(...)` replaced a directory and everything under
+  it with a file — silently, in the class the docs present as the reference
+  exemplar for extending this library, and the class used as a mock
+  filesystem in tests. It now raises `IsADirectoryError`, as `pathlib` does.
+  The same guard covers the virtual root for every mode, which used to grow a
+  bogus `""` key in the backend on `"w"`/`"a"`.
+- **A `MemPath` routed *through* a file raised `TypeError`.**
+  `_parent_container()` walked ancestors with `path not in parent`, which on a
+  `bytearray` ancestor evaluates `"seg" not in bytearray`. That `TypeError`
+  sails past the `OSError` guard in `Stat._st_mode()`, so even
+  `MemPath("file.txt/sub").exists()` crashed instead of returning `False` —
+  a routine shape in glob/walk and in `mkdir(parents=True)`. It now raises
+  `NotADirectoryError` naming the offending ancestor.
+- **`Pathname` had no `__eq__`/`__hash__`, so subclasses compared by
+  identity.** Every pure subclass that didn't hand-write equality — including
+  `MemPath`, and any downstream class subclassing `Path` directly — was
+  unusable as a dict key or set member, and `is_relative_to()` (which decides
+  via `==` against freshly built parents) always returned `False` without
+  raising. There is now a default keyed on
+  `(type(self), tuple(self.segments))`. `LocalPath`, `PosixPathname` and
+  `WindowsPathname` are unaffected — `pathlib.PurePath` precedes `Pathname` in
+  their MRO and keeps its own equality — as is `Uri`, which defines one.
+- **`is_relative_to()` normalized a `str` argument by joining it onto
+  `self`.** `Pathname` used `cls(self, other)` and `Uri` used
+  `Uri(self, _ROOT, other)`, so `Uri("a/b").is_relative_to("a")` compared
+  against `"a/b/a"` / `"/a"` and answered `False` while
+  `Uri("a/b").is_relative_to(Uri("a"))` answered `True` — the str and object
+  forms of the same call disagreed. Both now parse `other` standalone, as
+  CPython does. The generic side uses `self.with_segments(other)` so a
+  subclass's per-instance state (`MemPath`'s backend) survives the
+  normalization. `Uri("http://h/a/b").is_relative_to("/a")` is still `True`.
+- **`LocalPath.chown()` leaked `AttributeError`/`LookupError` on Windows.**
+  `shutil.chown` exists there while `os.chown` does not, so an int id raised
+  `AttributeError` and a name raised a misleading `LookupError: no such user`
+  (with no `pwd` module, every name misses whether or not the user exists).
+  It now raises `NotImplementedError`, which `docs/divergences.md` already
+  promised and which every other unsupported capability here raises. The
+  all-unchanged no-op still succeeds.
+
+## [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 +778,19 @@ 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.2...HEAD
+[0.9.2]: https://github.com/jose-pr/pathlib-next/compare/v0.9.1...v0.9.2
+[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.2}/PKG-INFO

@@ -1,10 +1,10 @@
-Metadata-Version: 2.4
-Name: pathlib_next
-Version: 0.9.0
+Metadata-Version: 2.5
+Name: pathlib-next
+Version: 0.9.2
 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.2}/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.2}/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 -- including `LocalPath` on a platform without `os.chown` (Windows), where `shutil.chown` exists but cannot work. | Ownership was the one permission attribute `stat()` could report (`st_uid`/`st_gid`) that nothing could write back. The valuable part is centralizing the **"unchanged" sentinel** on `Path` (`utils.as_owner()`): `os.chown` spells it `-1`, SFTP omits the field, other middlewares use `None` -- normalizing per-scheme would be three chances to disagree. Backends implement `_chown()` and receive an already-canonical pair. SFTPv3 sends uid/gid as one paired attribute, so `SftpPath` reads the current owner for whichever field is unchanged rather than guessing a value. |
+| `Path.chmod(mode, ...)` accepting a `str` | `mode` must be an `int`; a `str` raises `TypeError` | Additionally accepts a `str`, parsed as **octal**: `"0755"`, `"755"` and `0o755` all mean the same thing. An optional `0o` prefix is allowed; any character outside `[0-7]` raises `ValueError` rather than being coerced. | The string form is how modes are written in `chmod(1)`, Ansible, Dockerfiles and shell scripts, so config-driven callers arrive holding one. Accepted only with an **explicit base 8** (`utils.as_mode()`), never a plain `int()`: `int("0755")` in decimal is 755 == `0o1363`, a different *and valid* mode, so a fallback to decimal would set plausible-but-wrong permissions with nothing raising -- which is exactly why stdlib refuses strings. Parsing in one shared helper is what makes the base non-negotiable across the five backends that implement `chmod` directly. |
 | `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.2}/docs/guides/extending.md

@@ -31,6 +31,16 @@ as_uri()        # a URI string identifying this path (can be a custom scheme)
 relative_to(other)          # or raise NotImplementedError if not meaningful
 ```
 
+Equality is **not** on that list: `Pathname` supplies a default `__eq__`/
+`__hash__` keyed on `(type(self), tuple(self.segments))`, so your class is
+usable as a dict key or set member, and the equality-based helpers
+(`is_relative_to()`, `parents` membership) work, without you writing
+anything. Override both together if your type needs a different identity
+-- e.g. case-insensitive segments, or one that also distinguishes the
+backing store two otherwise-identical paths point at. (`LocalPath` and the
+`*Pathname` classes don't use this default: `pathlib.PurePath` precedes
+`Pathname` in their MRO and keeps its own equality.)
+
 Optional I/O, implement whichever your resource actually supports -- leave
 the rest as the inherited `@notimplemented` stubs (derived helpers either
 fall back, e.g. `move()` falls back to copy+unlink when `rename()` isn't

{pathlib_next-0.9.0 → pathlib_next-0.9.2}/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.2}/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.2"
 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.2}/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.
 
@@ -26,6 +26,17 @@ pathlib_next`.
   (abstract), `match(pattern, *, case_sensitive=None)`,
   `full_match(pattern, *, case_sensitive=None)`, `as_posix()`,
   `has_glob_pattern()`. `as_uri()` is abstract on `Pathname` itself.
+  - `__eq__`/`__hash__` are supplied by default, keyed on
+    `(type(self), tuple(self.segments))` — exact type, so a subclass never
+    compares equal to its base. Classes mixing in `pathlib.PurePath`
+    (`PosixPathname`, `WindowsPathname`, `LocalPath`) keep stdlib's
+    equality instead, since `PurePath` precedes `Pathname` in their MRO;
+    `Uri` defines its own over `as_uri()`. Override both together if your
+    subclass needs a different identity.
+  - `is_relative_to(other)` parses a `str` `other` standalone, via
+    `self.with_segments(other)` — the same rule as CPython's
+    `self.with_segments(other)`, and it preserves per-instance state such
+    as `MemPath`'s backend.
 - **`Path(Pathname, Chmod, Stat, BinaryOpen)`** — base class for I/O paths.
   `Path(*args)` (the bare class, not a subclass) always constructs a
   `LocalPath` (`fspath.py`) — the real local filesystem. Adds:
@@ -63,6 +74,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 +152,23 @@ 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). On a
+  platform without `os.chown` (Windows) `LocalPath.chown()` raises
+  `NotImplementedError` for any real change; the all-unchanged no-op still
+  succeeds because it never reaches the backend.
 - **`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,
@@ -180,7 +218,10 @@ extra that depends on it).
   `suffix`, `stem`, `parent`. Methods: `as_uri(sanitize=False)` (sanitize
   strips password from userinfo before formatting), `with_source(source)`,
   `with_segments(*segments)`, `with_path(path)`, `with_query(query)`,
-  `with_fragment(fragment)`, `is_absolute()`, `is_relative_to(other)`,
+  `with_fragment(fragment)`, `is_absolute()`, `is_relative_to(other)`
+  (a `str` `other` is parsed standalone as `Uri(other)`, matching
+  `relative_to()`; an `other` with no authority is compatible with any
+  `self.source`, so `Uri("http://h/a/b").is_relative_to("/a")` is `True`),
   `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
@@ -249,7 +290,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.2}/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,51 @@ 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 hasattr(_os, "chown"):
+            # shutil.chown() *exists* on Windows while os.chown does not, so
+            # without this the int form leaked `AttributeError: module 'os'
+            # has no attribute 'chown'` and the name form leaked
+            # `LookupError: no such user` -- actively misleading, since
+            # there is no `pwd` module for shutil._get_uid to consult, so
+            # every name "misses" whether or not the user exists.
+            # docs/divergences.md promises NotImplementedError here.
+            raise NotImplementedError("chown()")
+        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.2}/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
@@ -123,11 +121,19 @@ class MemPath(Path):
     def _parent_container(self) -> tuple[dict[str, bytearray], str]:
         parent = self.backend
         *ancestors, name = self.normalized
-        for path in ancestors:
+        for index, path in enumerate(ancestors):
             if path not in parent:
                 raise FileNotFoundError(self.parent)
-            else:
-                parent = parent[path]
+            parent = parent[path]
+            if not isinstance(parent, dict):
+                # An ancestor segment names a file. Without this the next
+                # iteration evaluates `"seg" not in bytearray` and raises
+                # TypeError, which sails past the OSError guards in
+                # stat()/exists()/is_dir() -- so even exists() crashed on a
+                # path merely routed through a file. NotADirectoryError is
+                # an OSError, which is what stdlib raises and what those
+                # guards already swallow.
+                raise NotADirectoryError(self.with_segments(*ancestors[: index + 1]))
 
         return parent, name
 
@@ -194,6 +200,11 @@ class MemPath(Path):
         # mode contract: "r"/"w" are required; "x"/"a" are supported here
         # as an extension. Anything else raises NotImplementedError.
         parent, name = self._parent_container()
+        if not name:
+            # An empty name is the virtual root, which stat() reports as a
+            # directory. Without this guard "w"/"a" created a bogus ""
+            # entry in the backend and "r" claimed FileNotFoundError.
+            raise IsADirectoryError(self)
         if mode == "r":
             if name not in parent:
                 raise FileNotFoundError(self)
@@ -202,6 +213,10 @@ class MemPath(Path):
                 raise IsADirectoryError(self)
             return io.BytesIO(content)
         elif mode == "w":
+            if isinstance(parent.get(name), dict):
+                # Truncating over a directory silently replaced the whole
+                # subtree with a file; stdlib raises IsADirectoryError.
+                raise IsADirectoryError(self)
             content = bytearray()
             parent[name] = content
             return MemBytesIO(content)