pathapi 0.1.0__tar.gz → 0.1.2__tar.gz

{pathapi-0.1.0 → pathapi-0.1.2}/CHANGELOG.md

@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-17
+
+### Added
+
+- **`max_workers` for recursive `copy()`, `rm()` and `PathSyncer`.** `copy()` (and
+  `copy_into()`), `rm()` and `PathSyncer(...)` take `max_workers=None`. `None`, the
+  default, is one thread, exactly as before. An int of 2 or more hands the files
+  and links of each directory to a pool of at most that many threads, which
+  helps a backend that pays a round trip per entry. It applies to a class that sets
+  the new class attribute `_threadsafe = True` (`LocalPath` and `FTPPath` do); any other
+  class, including every class of another distribution until it sets the attribute,
+  runs serially whatever was asked. Callbacks (`progress`, `on_error`, `ignore_error`,
+  the sync `hook`, follow policies) run one at a time but on pool threads, in no
+  fixed order, and the error that ends the operation is the first to happen. A value
+  below 1 is `ValueError`, one that is not an int is `TypeError`. `PathContract`
+  has a `supports_concurrent_use` switch for the matching test.
+- **`AsyncPath` and `AsyncFile`: a path for use from an event loop.** `AsyncPath(path)`
+  wraps any `Path`; the pure members (`name`, `parent`, `/`, `with_*()`, `match()`, ...)
+  are plain and give `AsyncPath`, every method that does I/O is a coroutine of the same
+  name and arguments, `iterdir()`, `glob()`, `rglob()` and `walk()` return async iterators,
+  and `open()` returns an object that is awaited or used with `async with` and gives an
+  `AsyncFile` (`read`, `readline`, `write`, `seek`, ..., `aclose()`). They are exported
+  from `pathapi` and `pathapi.path`. Each call runs the wrapped path's sync method on a
+  worker thread (`asyncio.to_thread()`), so every backend can be used from a loop and the
+  loop is not blocked; cancelling an `await` abandons the wait and the worker finishes the
+  call. Recursive `copy()`, `rm()` and `move()` are one such call, so `max_workers=` is the
+  sync fan-out. `supports()` and `capabilities()` of an `AsyncPath` answer for the wrapped
+  path. A subclass gets its own class for every path derived from it, built by the
+  classmethod `AsyncPath._adopt(path)` (`cls(path)`), which a subclass with another
+  constructor overrides.
+- **`AsyncHTTPClient`: the HTTP client for an event loop.** `pathapi.http.AsyncHTTPClient`
+  is the sibling of `HTTPClient`: the same constructor arguments, redirect and
+  `Authorization` rules, `timeout`, `deadline`, reply limit and errors, with `request()`
+  and `redirect()` as coroutines, `aclose()` and `async with`. It returns an
+  `AsyncHTTPResponse` (`await read()`, `iter_bytes()` as an async iterator, `await
+  aclose()`). It sends through an async transport, an object with `async send()` and
+  `async aclose()`. The default one, `ThreadedTransport`, runs the synchronous transport
+  `PATHAPI_HTTP_TRANSPORT` names on worker threads, so every synchronous transport works
+  from a loop; a native one is declared in the entry-point group
+  `pathapi.http_async_transports` and chosen by `PATHAPI_HTTP_ASYNC_TRANSPORT` (same
+  rules and messages as the synchronous registry; `async_transport_names()`,
+  `get_async_transport()` and `default_async_transport()`).
+- **The async half of the transport suite.** `python -m pathapi.http.testing
+  --http-async-transports NAME` holds an async transport to the promises of the
+  synchronous suite (`test_async_transport.py`, `test_async_client.py`). Without the
+  option the async tests run over `builtin` when `--http-transports` is left out too,
+  and are not collected when it names a transport: a distribution that runs
+  `--http-transports NAME` gets the tests it got before.
+- **`pathapi.testing.AsyncPathContract`.** The pytest contract of `AsyncPath` over a
+  backend: it takes the `root` fixture of `PathContract` and checks each coroutine
+  against the sync path's result, with `asyncio.run()` and no extra test dependency. Its
+  class attribute `async_path_class` (default `AsyncPath`) names the class under test, so a
+  subclass of `AsyncPath` is tested with the paths it derives.
+
+### Changed
+
+- **An unknown HTTP transport name is told where to look, not which package to
+  install.** `get_transport()` and `PATHAPI_HTTP_TRANSPORT` raise `ValueError` for a
+  name no installed distribution declares in the group `pathapi.http_transports`,
+  naming the group and suggesting `pathapi-NAME` as a name to look for. The error is
+  a `ValueError` that is also an `ImportError`, so code that caught either still
+  does. `requests` is no longer special: `transport_names()` lists it only when an
+  installed distribution declares it. The refusal of a proxy that is not `http://`
+  points at a transport of that group that supports it. Install the distribution
+  that provides the transport.
+
+### Fixed
+
+- **A `nan` or infinite HTTP timeout is refused with `ValueError`.** `timeout=float("nan")`
+  passed the check, and the built-in transport then failed in `socket.settimeout()` after
+  it had opened the connection, which leaked the socket. Pass a positive finite number of
+  seconds, or `None`.
+- **`move(overwrite=True)` no longer destroys the old target when the move fails.**
+  An existing target was removed before the source was renamed or copied over it, so
+  a failing rename or copy lost the target. The target now stays until the source
+  has taken its place: a local file is replaced atomically, `rename()` is tried
+  over a file elsewhere, a backend that refuses has the target renamed aside and put
+  back on failure, and a copy and delete finishes the new file or tree beside the
+  target first. A directory target is swapped in by rename where its class has one.
+  If you list the directory while a move runs, you may see a hidden
+  `.NAME.<hex>.pathapi-tmp` sibling.
+- **`copy(follow_symlinks=False, overwrite=True)` of a link no longer destroys the old
+  target when the new link cannot be made.** The existing target was unlinked before
+  `symlink_to()`, so a refused link lost it. Where the target's class can rename, the
+  link is now made in a hidden sibling and renamed over the target; a class that
+  cannot rename still unlinks first. A target class that cannot make links now raises
+  `NotImplementedError` before anything is removed.
+
+## [0.1.1] - 2026-10-16
+
+### Added
+
+- **`deadline` for a whole HTTP request.** `HTTPClient(deadline=...)` and the
+  `deadline=` keyword of `request()` and `redirect()` take the seconds a request may
+  take, redirects and the reading of the body included (`None`, the default, is no
+  limit). Each wait's timeout is held to the time that remains and `TimeoutError` is
+  raised once it has passed; `timeout` still bounds each wait. A read already blocked
+  can overrun the deadline by at most its timeout. A value that is not a number is
+  `TypeError`, one that is not positive `ValueError`. It works over every transport.
+
+### Fixed
+
+- **`copy(overwrite=True)` no longer destroys the old target when the copy fails.**
+  An existing file was removed before the new content was written, so a source that
+  failed half way left no file, or a partial one. The old file is kept until the
+  new content is complete: it is written to a hidden `.NAME.<hex>.pathapi-tmp`
+  sibling and renamed over it, and a class whose write stream commits on close is
+  written to directly. A class that cannot rename writes the sibling and then writes
+  it over the target. If you list the directory while a copy runs, you may see that
+  sibling.
+- **`pathlib.Path(src).copy(target)` (3.14) onto a `Path` of this library refuses
+  unsafe child names.** `_copy_from()` joined every listed name onto the target; a
+  name that is not one component (`..`, a separator, on a Windows target a drive or
+  a trailing dot) now raises `ValueError` before anything is written for it, as
+  `copy(recursive=True)` does. A source that lists such names needs a copy that
+  skips them.
+- **The shipped transport suite names the file of its tests wherever it is run
+  from.** `python -m pathapi.http.testing` (and `run()`) roots pytest at the suite's
+  own directory unless `--rootdir` is given, so node ids keep their file when the
+  checkout and the installed package are on different drives.
+
 ## [0.1.0] - 2026-10-15
 
 Published as `pathlib-next` up to 0.10.0; from 0.1.0 as `pathapi`. The released
@@ -3539,7 +3660,9 @@ behaviour with what to do about it.
 - 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/pathapi/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/jose-pr/pathapi/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/jose-pr/pathapi/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/jose-pr/pathapi/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/jose-pr/pathapi/compare/v0.10.0...v0.1.0
 [0.10.0]: https://github.com/jose-pr/pathlib-next/compare/v0.9.14...v0.10.0
 [0.9.14]: https://github.com/jose-pr/pathlib-next/compare/v0.9.13...v0.9.14

{pathapi-0.1.0 → pathapi-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pathapi
-Version: 0.1.0
+Version: 0.1.2
 Summary: Generic Path Protocol based pathlib
 Project-URL: Homepage, https://github.com/jose-pr/pathapi/
 Project-URL: Documentation, https://jose-pr.github.io/pathapi/
@@ -78,8 +78,10 @@ where the backend has a faster way.
 - **`pathapi.http`**: `HTTPClient` and a transport contract for HTTP
   requests on the standard library (redirects that never carry
   `Authorization` to another origin, TLS verified by default, a `proxies=`
-  provider); the `requests` library plugs in as a transport through the
-  `pathapi-requests` distribution.
+  provider); another HTTP library plugs in as a transport through the
+  `pathapi.http_transports` entry-point group. `AsyncHTTPClient` is the same
+  client for an event loop, over async transports registered in
+  `pathapi.http_async_transports`.
 - **`PathSyncer`**: one-way, content-compared tree sync between any two
   implementations, with dry runs and event hooks.
 - **Extensible**: subclass `Path` for any resource, and verify it with the
@@ -90,10 +92,6 @@ Paths for other places are separate distributions built on this one:
 | Distribution | Provides |
 | --- | --- |
 | [`uripath`](https://github.com/jose-pr/uripath) | `URIPath`: one class for any URI, with the schemes `file:`, `data:`, `ftp:`, `zip:`, `tar:`, `http:` and `dav:`, and the `uripath` command |
-| [`sftppath`](https://github.com/jose-pr/sftppath) | `SFTPPath` (paramiko or asyncssh) |
-| [`objpath`](https://github.com/jose-pr/objpath) | `S3Path`, `GSPath` and `AZPath` (Amazon S3, Google Cloud Storage, Azure Blob Storage) |
-| [`repopath`](https://github.com/jose-pr/repopath) | `RepoPath`, `GitHubPath` and `GitLabPath` (the REST APIs of the hosting services) |
-| [`pathapi-requests`](https://github.com/jose-pr/pathapi-requests) | `RequestsTransport`, the HTTP transport that sends through a `requests.Session` |
 
 ## Installation
 
@@ -178,7 +176,7 @@ print(sorted(p.name for p in Path("site-copy").iterdir()))
 | `pathapi.mempath` | `MemPath` in-memory filesystem |
 | `pathapi.ftp` | `FTPPath`, `FTPBackend` (FTP and FTPS on `ftplib`) |
 | `pathapi.archive` | `ZipPath`, `TarPath`, `ArchivePath` (members of a zip or tar file), `make_archive`, `unpack_archive` |
-| `pathapi.http` | `HTTPClient`, `HTTPTransport`, `HTTPResponse` (HTTP requests on `http.client`) |
+| `pathapi.http` | `HTTPClient`, `HTTPTransport`, `HTTPResponse`, `AsyncHTTPClient`, `ThreadedTransport` (HTTP requests on `http.client`, and from an event loop) |
 | `pathapi.protocols` | `Stat`, `Chmod`, `BinaryOpen`, `NativeChecksum` |
 | `pathapi.sync` | `PathSyncer`, `SyncEvent`, `PathAndStat` |
 | `pathapi.glob` | the glob engine behind `Path.glob()` |
@@ -192,13 +190,33 @@ The full reference is on the [documentation site](https://jose-pr.github.io/path
 an agent-oriented API summary ships inside the package as
 `pathapi/AGENTS.md`.
 
+## Async
+
+`AsyncPath(path)` wraps any `pathapi` path for use inside an event loop: the
+pure members stay plain, every method that does I/O is a coroutine of the same
+name, listings are async iterators and `open()` gives an `AsyncFile`. Each call
+runs the sync method on a worker thread, so every backend works at once and the
+loop is never blocked; it is not a native async client.
+
+```python
+import asyncio
+from pathapi import AsyncPath, LocalPath
+
+async def main():
+    root = AsyncPath(LocalPath("."))
+    async for entry in root.iterdir():
+        print(entry.name, await entry.is_dir())
+
+asyncio.run(main())
+```
+
 ## Extending
 
 Subclass `Path` for a resource of your own (`MemPath` is the reference), as
 worked through in
 [Extending](https://jose-pr.github.io/pathapi/guides/extending/).
 `pathapi.testing` provides the pytest contracts (`PurePathContract`,
-`ReadPathContract`, `PathContract`) and `populate_fixture_tree()` that every
+`ReadPathContract`, `PathContract`, `AsyncPathContract`) and `populate_fixture_tree()` that every
 class of the package and of the distributions above is verified with.
 
 ## Supported Python versions

{pathapi-0.1.0 → pathapi-0.1.2}/README.md

@@ -41,8 +41,10 @@ where the backend has a faster way.
 - **`pathapi.http`**: `HTTPClient` and a transport contract for HTTP
   requests on the standard library (redirects that never carry
   `Authorization` to another origin, TLS verified by default, a `proxies=`
-  provider); the `requests` library plugs in as a transport through the
-  `pathapi-requests` distribution.
+  provider); another HTTP library plugs in as a transport through the
+  `pathapi.http_transports` entry-point group. `AsyncHTTPClient` is the same
+  client for an event loop, over async transports registered in
+  `pathapi.http_async_transports`.
 - **`PathSyncer`**: one-way, content-compared tree sync between any two
   implementations, with dry runs and event hooks.
 - **Extensible**: subclass `Path` for any resource, and verify it with the
@@ -53,10 +55,6 @@ Paths for other places are separate distributions built on this one:
 | Distribution | Provides |
 | --- | --- |
 | [`uripath`](https://github.com/jose-pr/uripath) | `URIPath`: one class for any URI, with the schemes `file:`, `data:`, `ftp:`, `zip:`, `tar:`, `http:` and `dav:`, and the `uripath` command |
-| [`sftppath`](https://github.com/jose-pr/sftppath) | `SFTPPath` (paramiko or asyncssh) |
-| [`objpath`](https://github.com/jose-pr/objpath) | `S3Path`, `GSPath` and `AZPath` (Amazon S3, Google Cloud Storage, Azure Blob Storage) |
-| [`repopath`](https://github.com/jose-pr/repopath) | `RepoPath`, `GitHubPath` and `GitLabPath` (the REST APIs of the hosting services) |
-| [`pathapi-requests`](https://github.com/jose-pr/pathapi-requests) | `RequestsTransport`, the HTTP transport that sends through a `requests.Session` |
 
 ## Installation
 
@@ -141,7 +139,7 @@ print(sorted(p.name for p in Path("site-copy").iterdir()))
 | `pathapi.mempath` | `MemPath` in-memory filesystem |
 | `pathapi.ftp` | `FTPPath`, `FTPBackend` (FTP and FTPS on `ftplib`) |
 | `pathapi.archive` | `ZipPath`, `TarPath`, `ArchivePath` (members of a zip or tar file), `make_archive`, `unpack_archive` |
-| `pathapi.http` | `HTTPClient`, `HTTPTransport`, `HTTPResponse` (HTTP requests on `http.client`) |
+| `pathapi.http` | `HTTPClient`, `HTTPTransport`, `HTTPResponse`, `AsyncHTTPClient`, `ThreadedTransport` (HTTP requests on `http.client`, and from an event loop) |
 | `pathapi.protocols` | `Stat`, `Chmod`, `BinaryOpen`, `NativeChecksum` |
 | `pathapi.sync` | `PathSyncer`, `SyncEvent`, `PathAndStat` |
 | `pathapi.glob` | the glob engine behind `Path.glob()` |
@@ -155,13 +153,33 @@ The full reference is on the [documentation site](https://jose-pr.github.io/path
 an agent-oriented API summary ships inside the package as
 `pathapi/AGENTS.md`.
 
+## Async
+
+`AsyncPath(path)` wraps any `pathapi` path for use inside an event loop: the
+pure members stay plain, every method that does I/O is a coroutine of the same
+name, listings are async iterators and `open()` gives an `AsyncFile`. Each call
+runs the sync method on a worker thread, so every backend works at once and the
+loop is never blocked; it is not a native async client.
+
+```python
+import asyncio
+from pathapi import AsyncPath, LocalPath
+
+async def main():
+    root = AsyncPath(LocalPath("."))
+    async for entry in root.iterdir():
+        print(entry.name, await entry.is_dir())
+
+asyncio.run(main())
+```
+
 ## Extending
 
 Subclass `Path` for a resource of your own (`MemPath` is the reference), as
 worked through in
 [Extending](https://jose-pr.github.io/pathapi/guides/extending/).
 `pathapi.testing` provides the pytest contracts (`PurePathContract`,
-`ReadPathContract`, `PathContract`) and `populate_fixture_tree()` that every
+`ReadPathContract`, `PathContract`, `AsyncPathContract`) and `populate_fixture_tree()` that every
 class of the package and of the distributions above is verified with.
 
 ## Supported Python versions

{pathapi-0.1.0 → pathapi-0.1.2}/docs/benchmarks.md

@@ -17,6 +17,7 @@ Narrower suites:
 ```bash
 python benchmarks/bench.py syncer
 python benchmarks/bench.py recursive-matrix
+python benchmarks/bench.py fanout
 ```
 
 ## Saved Results
@@ -47,6 +48,9 @@ claims in release notes come from CI runs.
 - `LocalPath` vs `pathlib.Path` on common local operations
 - `PathSyncer` on local trees, and recursive copy/remove on local and
   in-memory trees
+- the `fanout` suite: recursive copy, remove and a first sync of a tree of
+  small files on a loopback FTP server and on a simulated slow backend (a
+  `MemPath` that waits 2 ms per call, not a measurement of a real one)
 
 The benchmarks of the classes in other distributions (URIs, HTTP listings,
 SFTP, object stores) live with those distributions.

{pathapi-0.1.0 → pathapi-0.1.2}/docs/divergences.md

@@ -70,8 +70,8 @@ these operations itself always keeps its own implementation.
 | `FTPPath.stat().st_mode` | pathlib reports the real mode | Taken from MLSD `unix.mode`, else derived from the `perm` fact (read/write bits only). | MLSD is the only mode source most servers offer. |
 | `Path.touch(mode=None, exist_ok=True)` on non-local backends | `pathlib.Path.touch(mode=0o666)` creates with the mode masked by the umask and updates an existing file's mtime | `mode` defaults to `None`: a new file keeps the backend's default permissions, and an explicit `mode` is applied with `chmod()` unmasked (a remote umask is unknown); a class that cannot `chmod()` raises `NotImplementedError` and removes the file it created, so a mode that was asked for is never silently dropped. An existing file's access and modification times are set to now through the overridable `_utime()` hook (`MemPath` and `FTPPath` on a server that lists `MFMT` implement it: whole seconds, no access time on FTP); a class that cannot set a time leaves the file as it is. `LocalPath` uses pathlib's `touch()` unchanged. | Always chmod'ing 0o666 left new files world-writable on FTP and other remote backends; a remote backend cannot apply the local umask. |
 | `Path.__iter__` | `pathlib.Path` is not iterable (no `__iter__`) | `iter(path)` is `path.iterdir()` | Deliberate extension for ergonomic `for child in path:` loops. **Caution:** on remote backends (FTP) this is a network call. **User decision, 2026-07-11.** |
-| `Path.copy(target, ...)` | CPython 3.14 `Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)`: overwrites an existing file, copies a directory tree without being asked, returns the new path | Ours predates 3.14. Signature: `copy(target, *, overwrite=False, follow_symlinks=True, preserve_metadata=True, recursive=False, ignore_error=None, progress=None, on_error=None)`; returns `None`. `ignore_error=` keeps its notify-only callable, and `on_error=` is `rm()`'s predicate `(error, path) -> bool` for a child error of a recursive copy (`True` skips the entry, `False` raises, a predicate that raises ends the copy with its own exception); passing both raises `TypeError`. An existing target raises `FileExistsError` unless `overwrite=True`; a directory needs `recursive=True`. `overwrite=True` unlinks an existing non-directory target with `unlink(missing_ok=True)`, but only once the source is open (a missing or unreadable source never destroys or creates the target; a copy that fails mid-stream removes its partial target; a backend whose write replaces the file and which cannot delete makes `unlink(missing_ok=True)` return without removing); copying onto the same file, or a directory into itself, raises `OSError(EINVAL)`: two files of this machine (`LocalPath`, a subclass, `pathlib.Path`, a class that names a local file through `filepath`) are compared by identity whatever their classes, a type that answers the overridable `_node_key()` hook (`MemPath`, archive members) by its normalized node, and anything else by `samefile()` where `stat()` has `st_dev`/`st_ino`, otherwise equal paths of one type that the overridable `_same_filesystem()` hook places on the same host or store (two paths of one class that name one server, built separately, count as the same file); `preserve_metadata` defaults to **True** (opposite of 3.14) and only propagates `st_mode`, not timestamps/xattrs: the permission bits of a file, and of each directory of a recursive copy once its children are copied (as `shutil.copytree` and 3.14 do), with the setuid, setgid and sticky bits dropped when source and target are different classes; a recreated symlink (`follow_symlinks=False`) carries only its target text, not its own mode, times or owner; a dangling symlink at the target is written through, as `shutil.copyfile` and 3.14 do, with or without `overwrite`, while a live one counts as existing and `overwrite=True` replaces the link itself | 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, ...)` | CPython 3.14 `Path.move(target)`: `os.replace` semantics (replaces an existing file), falls back to copy + delete across filesystems, returns the new path | Ours predates 3.14 and keeps `overwrite=False`: an existing target raises `FileExistsError`. Returns whatever `rename()` returns (`None` on the copy fallback). Our own extension: tries `rename()` (by default only onto a path of the same class; `LocalPath` and classes for URIs decide for themselves), falls back to copy+unlink, which recreates a symlink and the links inside a moved tree wherever the target can hold links, so the result does not depend on whether `rename()` was available. Validates before touching the target: a missing source raises `FileNotFoundError`, a file onto a directory raises `IsADirectoryError`, a target that holds the source (`OSError(ENOTEMPTY)`), lies inside it (`OSError(EINVAL)`) or is a link to or from the same file (`OSError(EINVAL)`) is refused with both trees intact, and the same file under another spelling (a case-only rename, another class, a relative `MemPath`, another spelling of the same archive) is renamed in place. "Same" is decided as for `copy()`. Two hard links of one file are two names: an existing target needs `overwrite=True`, and the source name is then removed. `overwrite=True` replaces a local file target atomically (`os.replace`); on other backends it unlinks the target immediately before `rename()`, so a failing rename can still lose it. | N/A -- pure extension, no pathlib method to diverge from. Removing the target before checking the source deleted it on a typo or a locked source. |
+| `Path.copy(target, ...)` | CPython 3.14 `Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)`: overwrites an existing file, copies a directory tree without being asked, returns the new path | Ours predates 3.14. Signature: `copy(target, *, overwrite=False, follow_symlinks=True, preserve_metadata=True, recursive=False, ignore_error=None, progress=None, on_error=None)`; returns `None`. `ignore_error=` keeps its notify-only callable, and `on_error=` is `rm()`'s predicate `(error, path) -> bool` for a child error of a recursive copy (`True` skips the entry, `False` raises, a predicate that raises ends the copy with its own exception); passing both raises `TypeError`. An existing target raises `FileExistsError` unless `overwrite=True`; a directory needs `recursive=True`. `overwrite=True` never removes or truncates the old file before the new content is secured: a missing, unreadable or half-read source leaves the target as it was, and a new file whose copy fails is removed. The new content is finished in a hidden temporary sibling and renamed over the old file (`os.replace` for a local path); a class that cannot rename writes the temporary sibling and then writes it over the target, which truncates it in place for the moment of that second write (the temporary file is kept and named if that fails), and a class whose write stream commits on close is written to directly, since a failed write leaves the old file. 3.14's `Path.copy()` truncates an existing target in place; copying onto the same file, or a directory into itself, raises `OSError(EINVAL)`: two files of this machine (`LocalPath`, a subclass, `pathlib.Path`, a class that names a local file through `filepath`) are compared by identity whatever their classes, a type that answers the overridable `_node_key()` hook (`MemPath`, archive members) by its normalized node, and anything else by `samefile()` where `stat()` has `st_dev`/`st_ino`, otherwise equal paths of one type that the overridable `_same_filesystem()` hook places on the same host or store (two paths of one class that name one server, built separately, count as the same file); `preserve_metadata` defaults to **True** (opposite of 3.14) and only propagates `st_mode`, not timestamps/xattrs: the permission bits of a file, and of each directory of a recursive copy once its children are copied (as `shutil.copytree` and 3.14 do), with the setuid, setgid and sticky bits dropped when source and target are different classes; a recreated symlink (`follow_symlinks=False`) carries only its target text, not its own mode, times or owner, and with `overwrite=True` it is made in a hidden sibling and renamed over the old entry where the class can rename (a failed link leaves the old entry), while a class that cannot rename unlinks the old entry first and so loses it if the new link then fails; a dangling symlink at the target is written through, as `shutil.copyfile` and 3.14 do, with or without `overwrite`, while a live one counts as existing and `overwrite=True` replaces the link itself | 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, ...)` | CPython 3.14 `Path.move(target)`: `os.replace` semantics (replaces an existing file), falls back to copy + delete across filesystems, returns the new path | Ours predates 3.14 and keeps `overwrite=False`: an existing target raises `FileExistsError`. Returns whatever `rename()` returns (`None` on the copy fallback). Our own extension: tries `rename()` (by default only onto a path of the same class; `LocalPath` and classes for URIs decide for themselves), falls back to copy+unlink, which recreates a symlink and the links inside a moved tree wherever the target can hold links, so the result does not depend on whether `rename()` was available. Validates before touching the target: a missing source raises `FileNotFoundError`, a file onto a directory raises `IsADirectoryError`, a target that holds the source (`OSError(ENOTEMPTY)`), lies inside it (`OSError(EINVAL)`) or is a link to or from the same file (`OSError(EINVAL)`) is refused with both trees intact, and the same file under another spelling (a case-only rename, another class, a relative `MemPath`, another spelling of the same archive) is renamed in place. "Same" is decided as for `copy()`. Two hard links of one file are two names: an existing target needs `overwrite=True`, and the source name is then removed. `overwrite=True` keeps an existing target until what replaces it is in place: a local file is replaced atomically (`os.replace`); elsewhere the source is renamed over it, or, where the backend refuses, the target is renamed aside, the source renamed in and the target put back if that fails; a copy and delete finishes the new file or tree beside the target first (a directory target is swapped in by rename where its class has one, and otherwise removed only after the copy beside it is complete). A hidden `.NAME.<hex>.pathapi-tmp` sibling exists meanwhile. | N/A -- pure extension, no pathlib method to diverge from. Removing the target before checking the source deleted it on a typo or a locked source. |
 | `Path.is_junction()` / `is_mount()` / `is_dir_binding()` | `pathlib` has `is_junction()` (3.12+) and `is_mount()`, but only for local paths and with no shared concept | Both are part of the `Path` contract (False by default, answered by `LocalPath`), and `is_dir_binding()` is their union: a directory that is another tree's second NAME rather than part of this one. A junction is the Windows spelling of a bind mount, and neither is a symlink -- `is_symlink()` is False and a non-following stat reports a plain directory. | Walking code needs the distinction: a symlink announces itself and every walker here already declines to follow one, while a binding looks exactly like an ordinary directory and its contents belong to whoever mounted or junctioned it. |
 | `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 -- or a binding (`is_dir_binding()`: a Windows junction, a mount point), which a non-following stat still reports as a directory -- is unlinked or `rmdir()`'d rather than traversed -- `rm -r` semantics. `follow_symlinks=`/`follow_binds=` select that per call: `False` (default), `True` (remove what is behind it, then the entry: a followed symlink is unlinked), `None` (leave it), or a callable asked per entry -- the same keyword `stat()`/`walk()`/`copy()` use for the same idea. They decide the path `rm()` is called on as they decide an entry met on the way down. A policy that is not one of those, or a callable's answer that is not, raises `ValueError` and is never offered to `ignore_error`. Every class that overrides `rm()` takes both keywords; a backend with no symlinks or bindings decides nothing with them, and one with a concurrent native walk runs it only for `follow_symlinks=False`. `rmdir()` on a live mount fails, which is the intended answer. | 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. |
@@ -94,7 +94,7 @@ these operations itself always keeps its own implementation.
 | `FTPPath`, `ZipPath`, `TarPath`, `ArchivePath`: `==`, rooted and relative spellings | `PurePosixPath("a") != PurePosixPath("/a")`, and equal paths are the same file because there is one filesystem | `==` and `hash` compare the names only (as `MemPath` does), so two paths of different servers or archives are equal; `copy()`, `move()` and `PathSyncer` ask the overridable `_same_filesystem()` and `_node_key()` hooks before they call two equal paths one file. `a/b` and `/a/b` are two spellings of one node, because the tree has no working directory and is read from its root: the server root for an `FTPPath`, the archive root for the archive paths (`_node_key()` is equal; `==` is not). An `FTPPath` sends `..` as written, and an archive path applies it to the member name and refuses a name that leaves the archive. | A remote tree and an archive hold names, not a current directory, and carry their connection or handle in the object (the model is `MemPath`). Making `==` compare the server too would make a path unequal to its own copy on a second connection, and would break `is_relative_to()`, which decides by `==`. |
 | `full_match()` on a generic path, with a bracket expression | `PurePath.full_match` (3.13+) compiles the whole pattern to one regular expression, so a negated bracket such as `[!x]` can match a separator: `PurePosixPath("a/b").full_match("a[!x]b")` and `PurePosixPath("/").full_match("[!a]")` are `True` | `Pathname.full_match` compares one component at a time and a bracket expression never matches a separator: both are `False` | A component-wise automaton keeps `**` linear in the path and the pattern (a regular expression backtracks exponentially on repeated `**`). A pattern that reads a separator out of a bracket is not a pattern anyone writes on purpose. Everything else, the root included, answers as `pathlib` does. |
 | `copy_into()`, `move_into()`, `replace()` | 3.14: `copy_into(target_dir, **kwargs)` and `move_into(target_dir)` call `copy()`/`move()` and return the new path; `copy()` overwrites an existing file and copies trees. `replace(target)` is `os.replace()` and returns the target | Defined once on `Path` over `copy()`/`move()`, on every backend and version. `copy_into(target_dir, *, overwrite=False, follow_symlinks=True, preserve_metadata=True, recursive=False, ignore_error=None, progress=None, on_error=None)` has the keywords and **the defaults of `copy()`**: an existing target needs `overwrite=True` and a directory needs `recursive=True`. `move_into(target_dir, *, overwrite=False)` has those of `move()`. Both return the new path. `replace(target)` is `move(target, overwrite=True)` and returns `target`: a directory is replaced only when empty (`OSError(ENOTEMPTY)` otherwise, nothing removed). On 3.14 `LocalPath` uses these rather than stdlib's `copy_into`/`move_into`; `LocalPath.replace` stays stdlib's `os.replace()` on every version. | One behaviour on every backend, interpreter and `Path` subclass, and one that cannot overwrite or recurse by accident (3.14's default replaces a file silently). A caller that wants 3.14's behaviour passes `overwrite=True, recursive=True`. |
-| `Path.info` and `pathlib.Path(...).copy(target)` onto a `Path` of this library (3.14) | 3.14 `Path.info` is a `PathInfo` kept on the path (its answers are cached for the life of the path object); `pathlib.Path.copy(target)` calls `target._copy_from(source, **kwargs)` on any target with `with_segments()`, so a target without it raises `AttributeError` | `info` is defined on every `Path`, on every version: an object with `exists()`, `is_dir()`, `is_file()` (each with `follow_symlinks=True`) and `is_symlink()`, over at most one following and one non-following `stat()`. A path holds no state, so its answers are cached on the `info` object, not on the path: each `path.info` asks again. `LocalPath` keeps stdlib's `info` on 3.14. `Path._copy_from(source, follow_symlinks=True, preserve_metadata=False)` makes a stdlib path's `copy()` work onto any `Path` of this library (overwrites a file and raises on an existing directory, as 3.14 does; `preserve_metadata` copies the permission bits and the modification time where the class can set them). A class that mixes a stdlib path keeps stdlib's. The private `pathlib` ABCs (`_ReadablePath`, ...) and `__open_rb__`/`__open_wb__` are not implemented. | Code written for 3.14's `PathInfo` and `Path.copy()` accepts these paths. Only the hooks `Path.copy()` reads from its target are carried, since the ABCs are private in 3.14 and have changed between `pathlib-abc` releases. |
+| `Path.info` and `pathlib.Path(...).copy(target)` onto a `Path` of this library (3.14) | 3.14 `Path.info` is a `PathInfo` kept on the path (its answers are cached for the life of the path object); `pathlib.Path.copy(target)` calls `target._copy_from(source, **kwargs)` on any target with `with_segments()`, so a target without it raises `AttributeError` | `info` is defined on every `Path`, on every version: an object with `exists()`, `is_dir()`, `is_file()` (each with `follow_symlinks=True`) and `is_symlink()`, over at most one following and one non-following `stat()`. A path holds no state, so its answers are cached on the `info` object, not on the path: each `path.info` asks again. `LocalPath` keeps stdlib's `info` on 3.14. `Path._copy_from(source, follow_symlinks=True, preserve_metadata=False)` makes a stdlib path's `copy()` work onto any `Path` of this library (overwrites a file and raises on an existing directory, as 3.14 does; a listed child name that is not one safe component raises `ValueError`, as in `copy(recursive=True)`; `preserve_metadata` copies the permission bits and the modification time where the class can set them). A class that mixes a stdlib path keeps stdlib's. The private `pathlib` ABCs (`_ReadablePath`, ...) and `__open_rb__`/`__open_wb__` are not implemented. | Code written for 3.14's `PathInfo` and `Path.copy()` accepts these paths. Only the hooks `Path.copy()` reads from its target are carried, since the ABCs are private in 3.14 and have changed between `pathlib-abc` releases. |
 | `Path.walk()` and a Windows junction | 3.14: `Path.walk()` (`os.walk` with symlinks as files) lists a junction in `filenames` and does not enter it unless `follow_symlinks=True` | A non-following `walk()` lists a junction in `filenames` and does not enter it, on every version and for every class whose `is_junction()` says so (`LocalPath`, and a class for `file:` URIs). `follow_symlinks=True` enters it, as pathlib does. | A junction, like a symlink, is a second name for another tree; a junction that points at its own parent was walked 64 levels deep, until the path got too long. 3.14's behaviour is the safe one and the only one that can be had on 3.9-3.11, where `Path.walk` does not exist. |
 | `LocalPath.symlink_to(target)` with a relative `str` target, on Windows | `pathlib` stores the text as given, `../real.txt` included, and Windows cannot resolve a link whose relative target spells its separators `/` | The path class rewrites the text into Windows separators (`..
 eal.txt`) before the link is made; on POSIX the text is stored as given | A link that cannot be followed is never what a caller wants, and `PathSyncer` recreates links from `as_posix()` text. |
@@ -171,6 +171,14 @@ because a behavioral decision needed documenting:
   (`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.**
+- `max_workers=None` on `Path.copy(recursive=True)`, `Path.rm(recursive=True)` and
+  `PathSyncer(...)`: no pathlib equivalent. `None` is one thread, as before. An int
+  of 2 or more hands the files and links of each directory to a pool of that many
+  threads, for a class that sets `_threadsafe = True` (`LocalPath`, `FTPPath`); any
+  other class runs serially. Callbacks (`progress`, `on_error`, `ignore_error`, the
+  sync `hook`, follow policies) are called one at a time but from pool threads and in
+  no fixed order, and the error that ends the operation is the first to happen, not
+  the first in listing order.
 - `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.

{pathapi-0.1.0 → pathapi-0.1.2}/docs/index.md

@@ -28,10 +28,6 @@ Paths for other places are separate distributions built on this one:
 | Distribution | Provides |
 | --- | --- |
 | [`uripath`](https://github.com/jose-pr/uripath) | `URIPath`: one class for any URI (`file:`, `data:`, `ftp:`, `zip:`, `tar:`, `http:`, `dav:`), and the `uripath` command |
-| [`sftppath`](https://github.com/jose-pr/sftppath) | `SFTPPath` (paramiko or asyncssh) |
-| [`objpath`](https://github.com/jose-pr/objpath) | `S3Path`, `GSPath` and `AZPath` |
-| [`repopath`](https://github.com/jose-pr/repopath) | `RepoPath`, `GitHubPath` and `GitLabPath` |
-| [`pathapi-requests`](https://github.com/jose-pr/pathapi-requests) | `RequestsTransport` for `pathapi.http` |
 
 ## Tour
 

{pathapi-0.1.0 → pathapi-0.1.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 [project]
 # The distribution and the import package are both `pathapi`.
 name = "pathapi"
-version = "0.1.0"
+version = "0.1.2"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"
@@ -43,6 +43,11 @@ docs = ['mkdocs', 'mkdocs-material', 'mkdocstrings[python]']
 [project.entry-points."pathapi.http_transports"]
 builtin = "pathapi.http:HTTPTransport"
 
+# The async HTTP transports `pathapi.http.AsyncHTTPClient` can send through;
+# `pathapi.http.async_transport_names()` lists them without importing them.
+[project.entry-points."pathapi.http_async_transports"]
+builtin = "pathapi.http:ThreadedTransport"
+
 [project.urls]
 Homepage = "https://github.com/jose-pr/pathapi/"
 Documentation = "https://jose-pr.github.io/pathapi/"
@@ -57,6 +62,8 @@ Issues = "https://github.com/jose-pr/pathapi/issues"
 [tool.hatch.build.targets.wheel.force-include]
 "README.md" = "pathapi/README.md"
 # The transport suite (`python -m pathapi.http.testing`) runs from the installed package.
+"tests/transport/test_async_client.py" = "pathapi/http/testing/suite/test_async_client.py"
+"tests/transport/test_async_transport.py" = "pathapi/http/testing/suite/test_async_transport.py"
 "tests/transport/test_client_default.py" = "pathapi/http/testing/suite/test_client_default.py"
 "tests/transport/test_client_errors.py" = "pathapi/http/testing/suite/test_client_errors.py"
 "tests/transport/test_client_peer_text.py" = "pathapi/http/testing/suite/test_client_peer_text.py"