pathapi 0.1.0__tar.gz → 0.1.1__tar.gz

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

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 +3572,8 @@ 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.1...HEAD
+[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pathapi
-Version: 0.1.0
+Version: 0.1.1
 Summary: Generic Path Protocol based pathlib
 Project-URL: Homepage, https://github.com/jose-pr/pathapi/
 Project-URL: Documentation, https://jose-pr.github.io/pathapi/

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

@@ -70,7 +70,7 @@ 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.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; 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.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. |
@@ -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. |

{pathapi-0.1.0 → pathapi-0.1.1}/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.1"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"

{pathapi-0.1.0 → pathapi-0.1.1}/src/pathapi/AGENTS.md

@@ -424,10 +424,16 @@ Base class for I/O paths.
     `samefile()` where `stat()` carries `st_dev`/`st_ino`, else equal paths
     of one type that `_same_filesystem()` places together.
   - The source is opened before the target is touched; a failed stream
-    removes the partial target. `overwrite=True` removes an existing file
-    target with `unlink(missing_ok=True)` just before writing: a backend
-    whose write replaces the file and which cannot delete implements
-    `unlink()` so that `missing_ok=True` returns without removing.
+    removes the partial target it created. `overwrite=True` never removes
+    or truncates the old file first: a source that fails half way leaves it
+    as it was. The new content is finished in a hidden temporary sibling
+    (`.NAME.<hex>.pathapi-tmp`) and renamed over the old file (`os.replace`
+    for a local path); where `rename()` is refused it is written over the
+    target from the finished copy, and the sibling is kept and named if that
+    fails. A class without `rename()` stages the same way when its write
+    stream takes bytes in place; one whose stream commits on close (it has
+    `discard()`) is written to directly, since a failed write leaves the old
+    file.
   - A recursive copy runs inside `target._write_batch()`: onto a zip
     archive it is one rewrite of the file, and a copy that raises leaves
     the archive as it was.
@@ -591,7 +597,9 @@ class CommitOnClose(DiscardOnError, BytesIO):
   works on 3.14, and returns `target.joinpath()`. It copies `source` (anything
   with `info`, `iterdir()`, `readlink()`, `open()` and `stat()`) as 3.14 does:
   an existing file is overwritten, an existing directory raises, children are
-  copied one by one, `follow_symlinks=False` makes a link through
+  copied one by one (a listed name that is not one safe component for this
+  path, by `providers.is_safe_child_name()`, is `ValueError` naming it before
+  anything is written for it), `follow_symlinks=False` makes a link through
   `symlink_to()`, and `preserve_metadata` copies the permission bits and the
   modification time where the class can set them (`chmod()`, `_utime()`).
   `Path.copy()` of this library does not call it. A class that mixes a
@@ -1150,18 +1158,20 @@ distributions are built on it.
 class HTTPClient:
     headers: dict
     timeout: float | tuple | None
+    deadline: float | None
     user_agent: str
     def __init__(
-        self, transport=None, *, headers=None, timeout=(10, 60), user_agent=None,
+        self, transport=None, *, headers=None, timeout=(10, 60), deadline=None,
+        user_agent=None,
     ): ...
     transport
     def request(
         self, method, url, *, data=None, headers=None, stream=False,
-        allow_redirects=None, timeout=..., auth=None,
+        allow_redirects=None, timeout=..., deadline=..., auth=None,
     ): ...
     def redirect(
         self, method, url, resp, *, headers=None, stream=False, timeout=...,
-        auth=None,
+        deadline=..., auth=None,
     ): ...
     def close(self): ...
 
@@ -1170,7 +1180,7 @@ MAX_REPLY_BYTES = 8388608
 ```
 
 - **`HTTPClient(transport=None, *, headers=None, timeout=(10, 60),
-  user_agent=None)`** holds a transport and what every request is sent with.
+  deadline=None, user_agent=None)`** holds a transport and what every request is sent with.
   `transport` is any object with `send()` (the contract below); without one the
   client builds the transport that `PATHAPI_HTTP_TRANSPORT` names (the
   built-in `HTTPTransport` by default) on first use, and `close()` or leaving
@@ -1181,8 +1191,16 @@ MAX_REPLY_BYTES = 8388608
   `pathapi/<version>`) and `Accept: */*`. Every request gets
   `timeout=(10, 60)` seconds (`connect`, `read`) unless the client or the call
   gives one; `timeout=None` waits without limit. `repr()` shows no header.
+  `timeout` bounds each wait; `deadline` (seconds, `None` for none) bounds the
+  whole request, redirects and the reading of the body included: every wait is
+  held to the time that remains, and `TimeoutError` is raised once it has
+  passed (also between reads of a streamed body). A call's `deadline=` replaces
+  the client's; a value that is not a number or `None` is `TypeError`, one
+  that is not positive `ValueError`, before anything is sent. A read already
+  blocked can overrun it by at most the timeout of that wait. It works over
+  any transport: the contract below is unchanged.
 - **`request(method, url, *, data=None, headers=None, stream=False,
-  allow_redirects=None, timeout, auth=None)`** returns the final
+  allow_redirects=None, timeout, deadline, auth=None)`** returns the final
   `HTTPResponse`. `data` is `bytes`, `str` (UTF-8), a binary file or an
   iterable of `bytes`; one that is not `bytes` cannot be sent twice, so it is
   not sent again after a redirect or a dropped connection. `auth` is a
@@ -1213,7 +1231,7 @@ MAX_REPLY_BYTES = 8388608
   status and the `Location` (userinfo, query and fragment removed). A body
   that is not `bytes` cannot be sent again, so it raises too.
 - **`redirect(method, url, resp, *, headers=None, stream=False, timeout,
-  auth=None)`** sends `method` to where `resp`, the answer to a request for
+  deadline, auth=None)`** sends `method` to where `resp`, the answer to a request for
   `url` made with `allow_redirects=False`, redirects to, and follows what that
   redirects to in turn. `Authorization` is left off whenever the target is
   another scheme, host or port than `url`'s. No usable `Location` is
@@ -2279,7 +2297,8 @@ distribution and `pytest` installed:
 python -m pathapi.http.testing --http-transports requests -q
 ```
 
-Everything after `python -m pathapi.http.testing` goes to pytest.
+Everything after `python -m pathapi.http.testing` goes to pytest, which is
+rooted at `suite_directory()` unless the arguments give `--rootdir`.
 `--http-transports` takes names that `transport_names()` lists, separated by
 commas (default `builtin`): each test that depends on the transport runs once
 per name, with `PATHAPI_HTTP_TRANSPORT` set to it, so the clients the

{pathapi-0.1.0 → pathapi-0.1.1}/src/pathapi/http/_client.py

@@ -8,6 +8,7 @@ import typing as _ty
 
 from .. import __version__
 from . import _follow, _settings
+from ._deadline import Deadline, check_deadline
 from ._headers import check_headers, check_url, has_header, merge_headers
 from ._response import HTTPResponse
 from ._status import too_large
@@ -19,7 +20,7 @@ unless it is given `timeout` (`HTTPClient(timeout=...)` or per request);
 `timeout=None` waits without a limit."""
 
 _UNSET = object()
-"""The `timeout` of a call that did not give one: the client's own."""
+"""The `timeout` or `deadline` of a call that did not give one: the client's own."""
 
 
 class HTTPClient:
@@ -35,6 +36,11 @@ class HTTPClient:
     `user_agent` (`pathapi/<version>` by default) and `Accept: */*`.
     Every request gets `timeout=DEFAULT_TIMEOUT` (`(10, 60)` seconds) unless
     `timeout` here or in the call says otherwise (`None` waits without limit).
+    `timeout` bounds each wait; `deadline` (seconds, `None` for no limit, the
+    default) bounds the whole request: redirects and the reading of the body
+    included, each wait's timeout is held to the time that remains, and
+    `TimeoutError` is raised once it has passed. A read already blocked can
+    overrun it by at most the timeout of that wait.
 
     The client, not the transport, follows redirects. `GET`, `HEAD` and
     `OPTIONS` follow up to 30; a redirect that changes the scheme, host or
@@ -47,6 +53,7 @@ class HTTPClient:
     __slots__ = (
         "headers",
         "timeout",
+        "deadline",
         "user_agent",
         "_transport",
         "_built",
@@ -60,6 +67,7 @@ class HTTPClient:
         *,
         headers: "_ty.Mapping[str, str] | None" = None,
         timeout: "float | tuple | None" = DEFAULT_TIMEOUT,
+        deadline: "float | None" = None,
         user_agent: "str | None" = None,
     ):
         if transport is not None and not callable(getattr(transport, "send", None)):
@@ -69,6 +77,7 @@ class HTTPClient:
         self._transport_lock = _threading.Lock()
         self.headers = dict(headers or {})
         self.timeout = timeout
+        self.deadline = check_deadline(deadline)
         self.user_agent = user_agent or f"pathapi/{__version__}"
 
     def __repr__(self) -> str:
@@ -115,12 +124,24 @@ class HTTPClient:
         return sent
 
     def _dispatch(
-        self, method, url, sent, data, allow_redirects, stream, timeout, first=None
+        self,
+        method,
+        url,
+        sent,
+        data,
+        allow_redirects,
+        stream,
+        timeout,
+        deadline,
+        first=None,
     ) -> HTTPResponse:
         check_url(url)
         check_headers(sent)
         if timeout is _UNSET:
             timeout = self.timeout
+        deadline = self.deadline if deadline is _UNSET else check_deadline(deadline)
+        if deadline is not None:
+            deadline = Deadline(deadline, f"{method} {_follow.shown(first or url)}")
         if isinstance(data, str):
             data = data.encode("utf-8")
         transport = self.transport
@@ -129,7 +150,11 @@ class HTTPClient:
         if method.upper() in _follow.FOLLOWED_METHODS and data is None:
             if allow_redirects is False and first is None:
                 resp = transport.send(
-                    method, url, headers=sent, timeout=timeout, stream=True
+                    method,
+                    url,
+                    headers=sent,
+                    timeout=timeout if deadline is None else deadline.cap(timeout),
+                    stream=True,
                 )
             else:
                 resp = _follow.send_following(
@@ -140,6 +165,7 @@ class HTTPClient:
                     timeout=timeout,
                     stream=True,
                     first=first,
+                    deadline=deadline,
                 )
         else:
             resp = _follow.send_once(
@@ -150,7 +176,10 @@ class HTTPClient:
                 body=data,
                 timeout=timeout,
                 stream=True,
+                deadline=deadline,
             )
+        if deadline is not None:
+            deadline.bound(resp)
         if not stream:
             limit = _settings.MAX_REPLY_BYTES
             resp._buffered(limit, too_large(_follow.shown(url), limit))
@@ -166,6 +195,7 @@ class HTTPClient:
         stream: bool = False,
         allow_redirects: "bool | None" = None,
         timeout=_UNSET,
+        deadline=_UNSET,
         auth: "tuple[str | bytes, str | bytes] | str | None" = None,
     ) -> HTTPResponse:
         """Send `method` to `url` and return the final response. A `data` that
@@ -182,7 +212,9 @@ class HTTPClient:
         body over `MAX_REPLY_BYTES` is `OSError(EFBIG)`; with `stream=True` the
         caller reads it, and closes the response."""
         sent = self._sent_headers(headers, auth)
-        return self._dispatch(method, url, sent, data, allow_redirects, stream, timeout)
+        return self._dispatch(
+            method, url, sent, data, allow_redirects, stream, timeout, deadline
+        )
 
     def redirect(
         self,
@@ -193,6 +225,7 @@ class HTTPClient:
         headers: "_ty.Mapping[str, str] | None" = None,
         stream: bool = False,
         timeout=_UNSET,
+        deadline=_UNSET,
         auth: "tuple[str | bytes, str | bytes] | str | None" = None,
     ) -> HTTPResponse:
         """Send `method` to where `resp`, the answer to a request for `url`,
@@ -207,5 +240,5 @@ class HTTPClient:
                 method, url, resp, None, "no usable Location"
             )
         return self._dispatch(
-            method, location, sent, None, None, stream, timeout, first=url
+            method, location, sent, None, None, stream, timeout, deadline, first=url
         )

pathapi-0.1.1/src/pathapi/http/_deadline.py

@@ -0,0 +1,74 @@
+"""A time limit for a whole request, above the per-wait timeout."""
+
+from __future__ import annotations
+
+import math as _math
+import time as _time
+
+
+def check_deadline(deadline) -> "float | None":
+    """`deadline` as seconds, or `None` for no limit. `TypeError` for anything
+    but a number or `None`, `ValueError` for a number that is not positive."""
+    if deadline is None:
+        return None
+    if isinstance(deadline, bool) or not isinstance(deadline, (int, float)):
+        raise TypeError("a deadline is a number of seconds or None")
+    if _math.isnan(deadline) or deadline <= 0:
+        raise ValueError("a deadline is a positive number of seconds, or None")
+    return float(deadline)
+
+
+class Deadline:
+    """The moment a request must be finished by. It lives for one request,
+    redirects included."""
+
+    __slots__ = ("_seconds", "_at", "_what")
+
+    def __init__(self, seconds: float, what: str):
+        self._seconds = seconds
+        self._at = _time.monotonic() + seconds
+        self._what = what
+
+    def check(self) -> float:
+        """The seconds that remain; `TimeoutError` once there are none."""
+        left = self._at - _time.monotonic()
+        if left <= 0:
+            raise TimeoutError(
+                f"the {self._seconds:g} s deadline of {self._what} passed"
+            )
+        return left
+
+    def cap(self, timeout):
+        """`timeout` (a number, `None` or a `(connect, read)` pair) with each
+        wait held to the time that remains."""
+        left = self.check()
+        if isinstance(timeout, tuple):
+            return tuple(self._capped(part, left) for part in timeout)
+        return self._capped(timeout, left)
+
+    @staticmethod
+    def _capped(wait, left):
+        return left if wait is None else min(wait, left)
+
+    def bound(self, response):
+        """Make `response` check the deadline before each read of its body."""
+        source = getattr(response, "_source", None)
+        if source is not None:
+            response._source = _Bounded(source, self)
+        return response
+
+
+class _Bounded:
+    """A response body that raises `TimeoutError` instead of reading once the
+    deadline has passed."""
+
+    def __init__(self, source, deadline: Deadline):
+        self._source = source
+        self._deadline = deadline
+
+    def read(self, amount: int) -> bytes:
+        self._deadline.check()
+        return self._source.read(amount)
+
+    def close(self) -> None:
+        self._source.close()

{pathapi-0.1.0 → pathapi-0.1.1}/src/pathapi/http/_follow.py

@@ -137,6 +137,11 @@ def _discard(resp: HTTPResponse) -> None:
         resp.close()
 
 
+def _capped(timeout, deadline):
+    """`timeout` held to what remains of `deadline`; as it is without one."""
+    return timeout if deadline is None else deadline.cap(timeout)
+
+
 def can_resend_body(body) -> bool:
     return body is None or isinstance(body, (bytes, bytearray, memoryview))
 
@@ -150,6 +155,7 @@ def send_following(
     timeout,
     stream: bool,
     first: "str | None" = None,
+    deadline=None,
 ) -> HTTPResponse:
     """Send a request that carries no body and follow its redirects, up to
     `MAX_REDIRECTS`. `Authorization` goes to the origin of `first` (the URL
@@ -163,7 +169,12 @@ def send_following(
         if origin(current) != home:
             headers = drop_header(headers, "Authorization")
         resp = transport.send(
-            method, current, headers=headers, body=None, timeout=timeout, stream=stream
+            method,
+            current,
+            headers=headers,
+            body=None,
+            timeout=_capped(timeout, deadline),
+            stream=stream,
         )
         if not is_redirect(resp):
             return resp
@@ -193,13 +204,19 @@ def send_once(
     body,
     timeout,
     stream: bool,
+    deadline=None,
 ) -> HTTPResponse:
     """Send a request that must not be redirected the way a browser does: a
     redirect with a status in `RESENT_STATUSES` to the same scheme, host and
     port is sent once more with the same method and body, and any other 3xx
     raises `OSError(EIO)` naming the status and the `Location`."""
     resp = transport.send(
-        method, url, headers=headers, body=body, timeout=timeout, stream=stream
+        method,
+        url,
+        headers=headers,
+        body=body,
+        timeout=_capped(timeout, deadline),
+        stream=stream,
     )
     if not 300 <= resp.status < 400:
         return resp
@@ -220,7 +237,12 @@ def send_once(
     else:
         _discard(resp)
         resp = transport.send(
-            method, location, headers=headers, body=body, timeout=timeout, stream=stream
+            method,
+            location,
+            headers=headers,
+            body=body,
+            timeout=_capped(timeout, deadline),
+            stream=stream,
         )
         if not 300 <= resp.status < 400:
             return resp

{pathapi-0.1.0 → pathapi-0.1.1}/src/pathapi/http/testing/__init__.py

@@ -64,7 +64,8 @@ def suite_directory() -> _pathlib.Path:
 
 def run(arguments: "_ty.Sequence[str] | None" = None) -> int:
     """Runs `MODULES` with pytest and `arguments` (pytest options, such as
-    `--http-transports requests`) and returns the exit status. Raises
+    `--http-transports requests`) and returns the exit status. pytest's
+    rootdir is `suite_directory()` unless `arguments` give `--rootdir`. Raises
     `ImportError` when pytest is not installed."""
     try:
         import pytest
@@ -77,4 +78,9 @@ def run(arguments: "_ty.Sequence[str] | None" = None) -> int:
     # The files go first: with an option and its value ahead of them, pytest
     # 8 reads the value as the first path and loads no `conftest.py`, so the
     # option `--http-transports` is not known.
-    return int(pytest.main([*files, *(arguments or ())]))
+    arguments = list(arguments or ())
+    # pytest roots node ids at its rootdir; a checkout on another drive than
+    # the installed suite would list them without their file.
+    if not any(a == "--rootdir" or a.startswith("--rootdir=") for a in arguments):
+        files.append(f"--rootdir={directory}")
+    return int(pytest.main([*files, *arguments]))

pathapi-0.1.1/src/pathapi/protocols/_copytree.py

@@ -0,0 +1,83 @@
+"""The recursive part of `copy()`: a directory and what is listed in it."""
+
+from __future__ import annotations
+
+import errno as _errno
+import typing as _ty
+
+from .. import _names
+from ._relation import contains
+from ._removal import _write_batch_of
+from ._transfer import _copy_mode, _require_safe_child
+
+if _ty.TYPE_CHECKING:
+    from ..path import Path
+
+
+def _copy_tree(
+    src: "Path",
+    target: "Path",
+    src_stat,
+    target_absent: bool,
+    *,
+    overwrite,
+    follow_symlinks,
+    preserve_metadata,
+    ignore_error,
+    progress,
+    offering,
+) -> None:
+    """Copy the directory `src` and what it holds to `target`, each child
+    through its own `copy(recursive=True)`; `copy()` passes its keywords on."""
+    if contains(src, target):
+        # Checked before anything is created: the new directory would
+        # be listed and copied into itself without end.
+        raise OSError(
+            _errno.EINVAL,
+            "Cannot copy a directory into itself",
+            str(target),
+        )
+    # The writes below may be committed together by a backend that
+    # pays for each one (see `_write_batch`).
+    with _write_batch_of(target):
+        # Listed before the target exists, as shutil.copytree does.
+        children = list(src.iterdir())
+        if not target_absent and target.exists():
+            if not target.is_dir():
+                raise FileExistsError(target)
+            if not overwrite:
+                raise FileExistsError(target)
+        else:
+            target.mkdir()
+        windows_target = _names.is_windows_flavoured(target)
+        for child in children:
+            try:
+                # A listed name is untrusted: one that is not a single component inside
+                # `target` is refused (see the child-name paragraph of the docstring).
+                _require_safe_child(target, child.name, windows_target)
+                child.copy(
+                    target / child.name,
+                    overwrite=overwrite,
+                    follow_symlinks=follow_symlinks,
+                    preserve_metadata=preserve_metadata,
+                    recursive=True,
+                    ignore_error=ignore_error,
+                    progress=progress,
+                    # Passed on only when given, so a `copy()` override
+                    # without the keyword still works as a child.
+                    **({} if offering is None else {"on_error": offering}),
+                )
+            except Exception as e:
+                if offering is not None:
+                    if not offering(e, child):
+                        raise
+                elif callable(ignore_error):
+                    # A notify-and-suppress hook: its return value is not
+                    # consulted, so `errors.append` works.
+                    ignore_error(e)
+                elif not ignore_error:
+                    raise
+        if preserve_metadata:
+            # After the children: a read-only directory could not take
+            # them, and its mode is only settled once they are in.
+            _copy_mode(src, target, follow_symlinks, src_stat)