asanypath 2.1.1__tar.gz → 2.3.0__tar.gz

{asanypath-2.1.1 → asanypath-2.3.0}/.github/workflows/unittests.yml

@@ -49,11 +49,8 @@ jobs:
       - name: Ruff checks
         run: uvx ruff check src tests && uvx ruff format --check src tests
 
-      - name: Create virtual environment
-        run: uv venv --python "${{ matrix.python-version }}"
-
-      - name: Install project and native extension
-        run: uv pip install -e ".[dev]"
+      - name: Install project and native extension from uv.lock
+        run: uv sync --locked --extra dev --python "${{ matrix.python-version }}"
 
       - name: Test with pytest and coverage
         env:

{asanypath-2.1.1 → asanypath-2.3.0}/.pre-commit-config.yaml

@@ -22,4 +22,10 @@ repos:
       entry: cargo check --manifest-path rust/Cargo.toml --locked
       language: system
       files: ^rust/.*\.(rs|toml|lock)$
-      pass_filenames: false
+      pass_filenames: false
+    # uv.lock must only reference the public index (a mirror URL leaks internal hosts).
+    - id: uv-lock-public-index
+      name: uv.lock uses only public index URLs
+      language: pygrep
+      entry: '(registry|url) = "https?://(?!pypi\.org/|files\.pythonhosted\.org/)'
+      files: ^uv\.lock$

{asanypath-2.1.1 → asanypath-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asanypath
-Version: 2.1.1
+Version: 2.3.0
 Summary: Async pathlib for local and cloud storage
 License-Expression: MIT
 License-File: LICENSE
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: anyio>=4
-Requires-Dist: asanypath-native~=2.1.0
+Requires-Dist: asanypath-native~=2.3.0
 Requires-Dist: msgspec>=0.22.0
 Requires-Dist: yarl>=1.2
 Provides-Extra: all
@@ -145,6 +145,46 @@ await src.copy(dst, recursive=True)
 await path.rmdir(recursive=True)
 ```
 
+Copies automatically use spare transfer concurrency for large ranged reads.
+The default target is 8 streams, with an 8 MiB minimum range size and at most
+8 range streams per file. Files smaller than 16 MiB stay single-stream. When
+enough files are active to meet the target, automatic copies use one request
+per file instead of adding ranges. The target is best-effort, not a minimum
+number of requests that must always be launched.
+
+S3, GCS, Azure, Artifactory, SSH, and range-capable HTTP/HTTPS sources use the
+shared reader for local downloads and source reads in cross-backend copies.
+FTP/FTPS, sources without size metadata, and HTTP servers without advertised
+range support retain single-stream downloads. Local-only copies and native
+server-side copy/rename operations retain their existing implementations.
+Uploads remain single writes; this does not introduce multipart uploads.
+
+Concurrent library copies share a default budget within the event loop. To
+configure a batch explicitly:
+
+```python
+import asyncio
+from asanypath import TransferBudget
+
+with TransferBudget(floor=8, ceiling=32, min_range_size=8 * 1024 * 1024, per_file_cap=8):
+    await asyncio.gather(*(src.copy(dst) for src, dst in pairs))
+```
+
+The ceiling bounds concurrent reads in this budget, not metadata requests or
+other processes. Parallel range buffers are bounded by the active streams
+times the range size; cross-backend destinations still buffer the complete
+object for their existing write API. `floor=1` disables automatic splitting.
+Explicit `chunk_size` requests retain sequential streaming when splitting
+would be inappropriate, and `chunk_size=0` disables streaming to local paths.
+
+S3/Azure ETags, GCS generations, and HTTP conditional requests pin the source
+version when available. Other sources are checked against fresh metadata
+after the download, which cannot guarantee a snapshot if the backend does
+not expose a reliable change token. Use `atomic=True` to keep an existing
+local destination intact on failure. Moves remove the source only after a
+successful copy. The updated Python package requires the matching native
+extension for conditional cloud reads.
+
 For synchronous code (no `await` needed):
 
 ```python
@@ -161,11 +201,136 @@ for child in p.parent.iterdir():  # yields synchronously
 Local paths (`file://` or bare `/path`) bypass the proxy entirely and use
 `pathlib.Path` directly — zero threading overhead.
 
+### Large uploads stream automatically
+
+Writing or copying a large object never buffers the whole thing in memory — it
+streams in bounded-size parts using each backend's native mechanism (S3
+multipart, Azure block blobs, GCS resumable, SSH chunked writes, FTP data
+connection, Artifactory streamed `PUT`). This is the **default** behaviour — no
+flag, no API change:
+
+```python
+# open("wb") spills to disk past 16 MiB and uploads in parts on close
+async with AsAnyPath("s3://bucket/huge.bin").open("wb") as f:
+    f.write(data)
+
+# local -> cloud copy streams straight from the source file (async and sync)
+await AsAnyPath("/data/movie.mp4").copy("s3://bucket/movie.mp4")
+```
+
+Peak memory per upload is one part — **8 MiB by default**. Objects smaller than
+one part upload in a single request. (`write_bytes(data)` / `write_text(...)`
+take the whole payload in memory by definition — use `open("wb")` or `copy()`
+for large data.)
+
+**Tuning the memory footprint.** The part size *is* the max RAM held per
+in-flight chunk (parts upload sequentially, so there is no concurrency
+multiplier). Set it globally via env, or per call:
+
+```bash
+export ASANYPATH_UPLOAD_CHUNK_SIZE=33554432   # 32 MiB parts (bytes)
+export ASANYPATH_SPOOL_MAX_SIZE=67108864      # 64 MiB before open("wb") spills to disk
+```
+
+```python
+# per call: copy(chunk_size=...) or, for writes, open(..., buffering=...)
+await src.copy("s3://bucket/huge.bin", chunk_size=32 * 1024 * 1024)
+async with dst.open("wb", buffering=32 * 1024 * 1024) as f:
+    f.write(data)
+```
+
+Bigger parts mean fewer requests and a larger single-object ceiling (S3 allows
+10,000 parts, so 8 MiB parts cap an object at ~80 GB). Backend minimums are
+applied automatically: **S3** clamps to ≥ 5 MiB parts, **GCS** rounds down to a
+256 KiB multiple.
+
 Unknown URI schemes now construct as `UnsupportedProtocolPath` placeholders.
 Pure path operations (e.g. `.name`, `.parent`, joins) still work, while backend
 operations (e.g. `.exists()`, `.read_bytes()`, `.open()`) raise
 `UnsupportedProtocolError` on use.
 
+### Download caching (opt-in)
+
+Reading the same object or URL twice always re-downloads it — there is **no
+cache by default**, and the read path is unchanged unless you opt in, so
+non-caching callers pay zero overhead.
+
+Caching is included in the native extension with no extra dependencies or
+installation extras. Opt in per read with `use_cache=True`:
+
+```python
+from asanypath import AsAnyPath
+
+p = AsAnyPath("s3://bucket/model.bin")
+data = await p.read_bytes(use_cache=True)   # first call fetches + stores
+data = await p.read_bytes(use_cache=True)   # subsequent calls served from disk
+text = await p.read_text(use_cache=True)
+```
+
+Configure the location and limits once (location defaults to
+`~/.cache/asanypath`, honoring `$XDG_CACHE_HOME` and `$ASANYPATH_CACHE_DIR`):
+
+```python
+from asanypath import configure_cache
+
+configure_cache(
+    directory="/var/cache/asanypath",  # default: ~/.cache/asanypath
+    size_limit=2 * 1024**3,            # stored key + payload budget (default 1 GiB, LRU)
+    ttl=3600,                          # per-entry expiry in seconds (default: none)
+    enabled=True,                      # make use_cache default to True process-wide
+)
+```
+
+Or via environment: `ASANYPATH_CACHE_DIR`, `ASANYPATH_CACHE_SIZE_LIMIT` (bytes),
+`ASANYPATH_CACHE_TTL` (seconds).
+
+Behaviour and trade-offs:
+
+- **Off by default, opt-in per call.** With `configure_cache(enabled=True)` the
+  default flips process-wide; an explicit `use_cache=False` always bypasses.
+- **Works for every remote backend** (S3, GCS, Azure, Artifactory, HTTP, SSH,
+  FTP). Local paths are never cached.
+- **Size-bounded, LRU-evicted;** disk I/O runs in a worker thread so the
+  event loop stays responsive. Concurrent reads of the same key collapse to a
+  single fetch within a cache instance. The byte budget counts UTF-8 keys and
+  payloads; SQLite metadata and transaction journals add filesystem overhead.
+  Objects larger than the budget are returned without being cached.
+- **Byte-only native storage:** SQLite stores raw bytes, never Python pickles.
+  The database lives under `native-v1/` in the configured cache directory.
+  Legacy DiskCache files are ignored, not migrated or deleted. Multiple
+  processes can share the new store; use the same size limit across them.
+- **Staleness is on you.** Entries are keyed by URL with no revalidation — a
+  cached object that changes upstream is served stale until it expires (`ttl`)
+  or is evicted. Prefer caching immutable/versioned objects, or set a `ttl`.
+
+### Resumable downloads
+
+`download(dst)` streams an object to a local file and **resumes an interrupted
+transfer** instead of starting over:
+
+```python
+await AsAnyPath("s3://bucket/huge.bin").download("/data/huge.bin")
+# process killed mid-download... run the same call again — it continues
+await AsAnyPath("s3://bucket/huge.bin").download("/data/huge.bin")
+```
+
+Bytes stream into `<dst>.part` with a `<dst>.part.meta` sidecar recording the
+object's ETag (or `Last-Modified`) and total size. On resume the identity is
+re-checked: if the upstream object is unchanged the download continues from the
+saved offset; if it changed, the partial is discarded and it restarts cleanly.
+On completion `<dst>.part` is atomically renamed to `dst`.
+
+```python
+# tune the range-request size; disable resume to always start fresh
+await path.download("/data/huge.bin", chunk_size=32 * 1024 * 1024, resume=False)
+```
+
+Resume needs range reads **and** a HEAD probe, so it's available on the object
+stores (S3/GCS/Azure) and Artifactory/HTTP where the server supports it.
+Backends without those (e.g. FTP) download in a single pass automatically. This
+needs no extra dependency — resume state is plain sidecar files, independent of
+the optional download cache.
+
 ## Installation
 
 Most cloud backends (S3, GCS, Azure, Artifactory, HTTP) are included in the base
@@ -232,6 +397,12 @@ asanypath cp /local/file.txt s3://bucket/file.txt
 # Copy cloud → local
 asanypath cp s3://bucket/file.txt /local/file.txt
 
+# Allow 32 concurrent files; fill spare capacity toward 8 streams for large files
+asanypath cp -r s3://bucket/data/ ./data/ -j 32 --concurrency-floor 8
+
+# Disable automatic range splitting (also supported by mv and sync)
+asanypath cp s3://bucket/file.txt ./file.txt --concurrency-floor 1
+
 # Delete a file
 asanypath rm s3://bucket/file.txt --force
 
@@ -438,10 +609,11 @@ Factory that returns the appropriate path instance based on the URI scheme.
 
 All path implementations support:
 
-- `open(mode, buffering)` — file-like streaming with lazy range reads
-- `copy(dst, recursive)` — copy file or tree (cross-backend)
-- `read_bytes()` / `write_bytes(data)`
-- `read_text(encoding)` / `write_text(data, encoding)`
+- `open(mode, buffering)` — file-like streaming with lazy range reads; for writes, `buffering` sets the upload part size
+- `copy(dst, recursive, chunk_size)` — copy file or tree (cross-backend); `chunk_size` tunes the upload part size
+- `download(dst, resume, chunk_size)` — stream an object to a local file, resuming an interrupted transfer
+- `read_bytes()` / `write_bytes(data)` — `read_bytes(use_cache=True)` serves from / stores in the opt-in [download cache](#download-caching-opt-in)
+- `read_text(encoding)` / `write_text(data, encoding)` — `read_text` also accepts `use_cache`
 - `exists()` / `is_file()` / `is_dir()`
 - `stat()` / `checksums()` (cloud backends)
 - `mkdir(parents, exist_ok)` / `touch(exist_ok)`

{asanypath-2.1.1 → asanypath-2.3.0}/README.md

@@ -90,6 +90,46 @@ await src.copy(dst, recursive=True)
 await path.rmdir(recursive=True)
 ```
 
+Copies automatically use spare transfer concurrency for large ranged reads.
+The default target is 8 streams, with an 8 MiB minimum range size and at most
+8 range streams per file. Files smaller than 16 MiB stay single-stream. When
+enough files are active to meet the target, automatic copies use one request
+per file instead of adding ranges. The target is best-effort, not a minimum
+number of requests that must always be launched.
+
+S3, GCS, Azure, Artifactory, SSH, and range-capable HTTP/HTTPS sources use the
+shared reader for local downloads and source reads in cross-backend copies.
+FTP/FTPS, sources without size metadata, and HTTP servers without advertised
+range support retain single-stream downloads. Local-only copies and native
+server-side copy/rename operations retain their existing implementations.
+Uploads remain single writes; this does not introduce multipart uploads.
+
+Concurrent library copies share a default budget within the event loop. To
+configure a batch explicitly:
+
+```python
+import asyncio
+from asanypath import TransferBudget
+
+with TransferBudget(floor=8, ceiling=32, min_range_size=8 * 1024 * 1024, per_file_cap=8):
+    await asyncio.gather(*(src.copy(dst) for src, dst in pairs))
+```
+
+The ceiling bounds concurrent reads in this budget, not metadata requests or
+other processes. Parallel range buffers are bounded by the active streams
+times the range size; cross-backend destinations still buffer the complete
+object for their existing write API. `floor=1` disables automatic splitting.
+Explicit `chunk_size` requests retain sequential streaming when splitting
+would be inappropriate, and `chunk_size=0` disables streaming to local paths.
+
+S3/Azure ETags, GCS generations, and HTTP conditional requests pin the source
+version when available. Other sources are checked against fresh metadata
+after the download, which cannot guarantee a snapshot if the backend does
+not expose a reliable change token. Use `atomic=True` to keep an existing
+local destination intact on failure. Moves remove the source only after a
+successful copy. The updated Python package requires the matching native
+extension for conditional cloud reads.
+
 For synchronous code (no `await` needed):
 
 ```python
@@ -106,11 +146,136 @@ for child in p.parent.iterdir():  # yields synchronously
 Local paths (`file://` or bare `/path`) bypass the proxy entirely and use
 `pathlib.Path` directly — zero threading overhead.
 
+### Large uploads stream automatically
+
+Writing or copying a large object never buffers the whole thing in memory — it
+streams in bounded-size parts using each backend's native mechanism (S3
+multipart, Azure block blobs, GCS resumable, SSH chunked writes, FTP data
+connection, Artifactory streamed `PUT`). This is the **default** behaviour — no
+flag, no API change:
+
+```python
+# open("wb") spills to disk past 16 MiB and uploads in parts on close
+async with AsAnyPath("s3://bucket/huge.bin").open("wb") as f:
+    f.write(data)
+
+# local -> cloud copy streams straight from the source file (async and sync)
+await AsAnyPath("/data/movie.mp4").copy("s3://bucket/movie.mp4")
+```
+
+Peak memory per upload is one part — **8 MiB by default**. Objects smaller than
+one part upload in a single request. (`write_bytes(data)` / `write_text(...)`
+take the whole payload in memory by definition — use `open("wb")` or `copy()`
+for large data.)
+
+**Tuning the memory footprint.** The part size *is* the max RAM held per
+in-flight chunk (parts upload sequentially, so there is no concurrency
+multiplier). Set it globally via env, or per call:
+
+```bash
+export ASANYPATH_UPLOAD_CHUNK_SIZE=33554432   # 32 MiB parts (bytes)
+export ASANYPATH_SPOOL_MAX_SIZE=67108864      # 64 MiB before open("wb") spills to disk
+```
+
+```python
+# per call: copy(chunk_size=...) or, for writes, open(..., buffering=...)
+await src.copy("s3://bucket/huge.bin", chunk_size=32 * 1024 * 1024)
+async with dst.open("wb", buffering=32 * 1024 * 1024) as f:
+    f.write(data)
+```
+
+Bigger parts mean fewer requests and a larger single-object ceiling (S3 allows
+10,000 parts, so 8 MiB parts cap an object at ~80 GB). Backend minimums are
+applied automatically: **S3** clamps to ≥ 5 MiB parts, **GCS** rounds down to a
+256 KiB multiple.
+
 Unknown URI schemes now construct as `UnsupportedProtocolPath` placeholders.
 Pure path operations (e.g. `.name`, `.parent`, joins) still work, while backend
 operations (e.g. `.exists()`, `.read_bytes()`, `.open()`) raise
 `UnsupportedProtocolError` on use.
 
+### Download caching (opt-in)
+
+Reading the same object or URL twice always re-downloads it — there is **no
+cache by default**, and the read path is unchanged unless you opt in, so
+non-caching callers pay zero overhead.
+
+Caching is included in the native extension with no extra dependencies or
+installation extras. Opt in per read with `use_cache=True`:
+
+```python
+from asanypath import AsAnyPath
+
+p = AsAnyPath("s3://bucket/model.bin")
+data = await p.read_bytes(use_cache=True)   # first call fetches + stores
+data = await p.read_bytes(use_cache=True)   # subsequent calls served from disk
+text = await p.read_text(use_cache=True)
+```
+
+Configure the location and limits once (location defaults to
+`~/.cache/asanypath`, honoring `$XDG_CACHE_HOME` and `$ASANYPATH_CACHE_DIR`):
+
+```python
+from asanypath import configure_cache
+
+configure_cache(
+    directory="/var/cache/asanypath",  # default: ~/.cache/asanypath
+    size_limit=2 * 1024**3,            # stored key + payload budget (default 1 GiB, LRU)
+    ttl=3600,                          # per-entry expiry in seconds (default: none)
+    enabled=True,                      # make use_cache default to True process-wide
+)
+```
+
+Or via environment: `ASANYPATH_CACHE_DIR`, `ASANYPATH_CACHE_SIZE_LIMIT` (bytes),
+`ASANYPATH_CACHE_TTL` (seconds).
+
+Behaviour and trade-offs:
+
+- **Off by default, opt-in per call.** With `configure_cache(enabled=True)` the
+  default flips process-wide; an explicit `use_cache=False` always bypasses.
+- **Works for every remote backend** (S3, GCS, Azure, Artifactory, HTTP, SSH,
+  FTP). Local paths are never cached.
+- **Size-bounded, LRU-evicted;** disk I/O runs in a worker thread so the
+  event loop stays responsive. Concurrent reads of the same key collapse to a
+  single fetch within a cache instance. The byte budget counts UTF-8 keys and
+  payloads; SQLite metadata and transaction journals add filesystem overhead.
+  Objects larger than the budget are returned without being cached.
+- **Byte-only native storage:** SQLite stores raw bytes, never Python pickles.
+  The database lives under `native-v1/` in the configured cache directory.
+  Legacy DiskCache files are ignored, not migrated or deleted. Multiple
+  processes can share the new store; use the same size limit across them.
+- **Staleness is on you.** Entries are keyed by URL with no revalidation — a
+  cached object that changes upstream is served stale until it expires (`ttl`)
+  or is evicted. Prefer caching immutable/versioned objects, or set a `ttl`.
+
+### Resumable downloads
+
+`download(dst)` streams an object to a local file and **resumes an interrupted
+transfer** instead of starting over:
+
+```python
+await AsAnyPath("s3://bucket/huge.bin").download("/data/huge.bin")
+# process killed mid-download... run the same call again — it continues
+await AsAnyPath("s3://bucket/huge.bin").download("/data/huge.bin")
+```
+
+Bytes stream into `<dst>.part` with a `<dst>.part.meta` sidecar recording the
+object's ETag (or `Last-Modified`) and total size. On resume the identity is
+re-checked: if the upstream object is unchanged the download continues from the
+saved offset; if it changed, the partial is discarded and it restarts cleanly.
+On completion `<dst>.part` is atomically renamed to `dst`.
+
+```python
+# tune the range-request size; disable resume to always start fresh
+await path.download("/data/huge.bin", chunk_size=32 * 1024 * 1024, resume=False)
+```
+
+Resume needs range reads **and** a HEAD probe, so it's available on the object
+stores (S3/GCS/Azure) and Artifactory/HTTP where the server supports it.
+Backends without those (e.g. FTP) download in a single pass automatically. This
+needs no extra dependency — resume state is plain sidecar files, independent of
+the optional download cache.
+
 ## Installation
 
 Most cloud backends (S3, GCS, Azure, Artifactory, HTTP) are included in the base
@@ -177,6 +342,12 @@ asanypath cp /local/file.txt s3://bucket/file.txt
 # Copy cloud → local
 asanypath cp s3://bucket/file.txt /local/file.txt
 
+# Allow 32 concurrent files; fill spare capacity toward 8 streams for large files
+asanypath cp -r s3://bucket/data/ ./data/ -j 32 --concurrency-floor 8
+
+# Disable automatic range splitting (also supported by mv and sync)
+asanypath cp s3://bucket/file.txt ./file.txt --concurrency-floor 1
+
 # Delete a file
 asanypath rm s3://bucket/file.txt --force
 
@@ -383,10 +554,11 @@ Factory that returns the appropriate path instance based on the URI scheme.
 
 All path implementations support:
 
-- `open(mode, buffering)` — file-like streaming with lazy range reads
-- `copy(dst, recursive)` — copy file or tree (cross-backend)
-- `read_bytes()` / `write_bytes(data)`
-- `read_text(encoding)` / `write_text(data, encoding)`
+- `open(mode, buffering)` — file-like streaming with lazy range reads; for writes, `buffering` sets the upload part size
+- `copy(dst, recursive, chunk_size)` — copy file or tree (cross-backend); `chunk_size` tunes the upload part size
+- `download(dst, resume, chunk_size)` — stream an object to a local file, resuming an interrupted transfer
+- `read_bytes()` / `write_bytes(data)` — `read_bytes(use_cache=True)` serves from / stores in the opt-in [download cache](#download-caching-opt-in)
+- `read_text(encoding)` / `write_text(data, encoding)` — `read_text` also accepts `use_cache`
 - `exists()` / `is_file()` / `is_dir()`
 - `stat()` / `checksums()` (cloud backends)
 - `mkdir(parents, exist_ok)` / `touch(exist_ok)`

{asanypath-2.1.1 → asanypath-2.3.0}/pyproject.toml

@@ -20,7 +20,7 @@ asanypath-native = { path = "rust" }
 root = "src"
 
 [tool.hatch.build.targets.sdist]
-exclude = ["rust"]
+exclude = ["rust", "uv.lock"]
 
 [tool.hatch.metadata.hooks.custom]
 
@@ -102,7 +102,7 @@ disable_error_code = ["attr-defined", "arg-type", "assignment"]
 module = "asanypath.local"
 disallow_untyped_defs = false
 warn_return_any = false
-disable_error_code = ["type-var", "misc", "override", "return-value"]
+disable_error_code = ["type-var", "misc", "override", "return-value", "assignment", "no-redef"]
 
 [[tool.mypy.overrides]]
 module = "asanypath.common"
@@ -120,19 +120,31 @@ disable_error_code = ["override", "type-arg", "return-value", "assignment", "att
 module = ["asanypath.s3", "asanypath.gcs", "asanypath.azure", "asanypath.artifactory"]
 disallow_untyped_defs = false
 warn_return_any = false
-disable_error_code = ["no-any-return", "attr-defined", "assignment", "override"]
+disable_error_code = ["no-any-return", "attr-defined", "assignment", "override", "arg-type", "misc"]
+
+[[tool.mypy.overrides]]
+module = ["asanypath.ssh", "asanypath.ftp"]
+disallow_untyped_defs = false
+warn_return_any = false
+disable_error_code = ["attr-defined", "override", "arg-type", "misc", "no-any-return", "assignment"]
+
+[[tool.mypy.overrides]]
+module = "asanypath.sync"
+disallow_untyped_defs = false
+warn_return_any = false
+disable_error_code = ["no-any-return", "misc", "attr-defined", "arg-type"]
 
 [[tool.mypy.overrides]]
 module = "asanypath.cloud"
 disallow_untyped_defs = false
 warn_return_any = false
-disable_error_code = ["no-any-return", "arg-type"]
+disable_error_code = ["no-any-return", "arg-type", "attr-defined", "misc", "assignment"]
 
 [[tool.mypy.overrides]]
 module = "asanypath.asanypath"
 disallow_untyped_defs = false
 warn_return_any = false
-disable_error_code = ["no-any-return", "misc", "union-attr", "type-var"]
+disable_error_code = ["no-any-return", "misc", "union-attr", "type-var", "attr-defined"]
 
 [[tool.mypy.overrides]]
 module = "asanypath.batcher"

{asanypath-2.1.1 → asanypath-2.3.0}/src/asanypath/__init__.py

@@ -4,6 +4,7 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
+from asanypath._transfer import TransferBudget
 from asanypath.artifactory import ArtifactoryPath
 from asanypath.asanypath import (
     PROTOCOL_MAP,
@@ -13,6 +14,7 @@ from asanypath.asanypath import (
     register_protocol,
 )
 from asanypath.azure import AzurePath
+from asanypath.cache import configure_cache
 from asanypath.cloud import CloudPathMixin
 from asanypath.common import CommonPurePathMixin
 from asanypath.exceptions import (
@@ -52,6 +54,7 @@ __all__ = [
     "AsAnyPath",
     "AsyncPath",
     "SyncPath",
+    "TransferBudget",
     "BackendOptions",
     "AccessGrant",
     "AccessPolicy",
@@ -62,6 +65,7 @@ __all__ = [
     "GCSPath",
     "AzurePath",
     "ArtifactoryPath",
+    "configure_cache",
     "register_protocol",
     "list_protocols",
     "AsAnyPathError",

{asanypath-2.1.1 → asanypath-2.3.0}/src/asanypath/__init__.pyi

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+from ._transfer import TransferBudget as TransferBudget
 from ._version import __version__ as __version__
 from .artifactory import ArtifactoryPath as ArtifactoryPath
 from .asanypath import (

asanypath-2.3.0/src/asanypath/_backend_opts.py

@@ -0,0 +1,61 @@
+"""CLI backend options: ``scheme.key=value`` mapped onto path constructor kwargs."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from asanypath.asanypath import PROTOCOL_MAP, _match_base_url_flavor
+
+Options = dict[str, dict[str, Any]]
+
+
+def option_keys(cls: type) -> dict[str, Callable[[str], Any]]:
+    """Return ``{key: coercer}`` for the keyword arguments a path class accepts."""
+    keys: dict[str, Callable[[str], Any]] = {}
+    for name, param in inspect.signature(cls.__init__).parameters.items():
+        if name == "self" or param.kind in (
+            param.VAR_POSITIONAL,
+            param.VAR_KEYWORD,
+            param.POSITIONAL_ONLY,
+        ):
+            continue
+        ann = str(param.annotation)
+        keys[name] = int if re.search(r"\bint\b", ann) and "str" not in ann else str
+    return keys
+
+
+def parse_options(specs: Iterable[str]) -> Options:
+    """Parse ``scheme.key=value`` specs; raise ValueError on anything unsupported."""
+    parsed: Options = {}
+    for spec in specs:
+        lhs, eq, value = spec.partition("=")
+        scheme, dot, key = lhs.partition(".")
+        if not eq or not dot or not key:
+            raise ValueError(f"invalid option {spec!r}; expected SCHEME.KEY=VALUE")
+        scheme = scheme.lower()
+        if scheme not in PROTOCOL_MAP:
+            raise ValueError(f"unknown protocol {scheme!r} in option {spec!r}")
+        keys = option_keys(PROTOCOL_MAP[scheme])
+        if key not in keys:
+            valid = ", ".join(sorted(keys)) or "none"
+            raise ValueError(f"{scheme} does not support option {key!r} (valid: {valid})")
+        try:
+            parsed.setdefault(scheme, {})[key] = keys[key](value)
+        except ValueError:
+            raise ValueError(f"invalid value {value!r} for {scheme}.{key}") from None
+    return parsed
+
+
+def kwargs_for(path: str, options: Options) -> dict[str, Any]:
+    """Return the options that apply to the backend serving ``path``."""
+    if not options:
+        return {}
+    flavor = _match_base_url_flavor(path)
+    merged: dict[str, Any] = {}
+    for scheme, values in options.items():
+        if PROTOCOL_MAP[scheme] is flavor:
+            merged.update(values)
+    return merged

asanypath-2.3.0/src/asanypath/_resume.py

@@ -0,0 +1,43 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+"""Sidecar state for resumable downloads.
+
+A partial download lives in ``<dst>.part`` with a ``<dst>.part.meta`` sidecar
+recording the remote object's identity (ETag/Last-Modified) and total size. On
+resume the identity is re-checked so a changed upstream object restarts cleanly
+rather than stitching mismatched bytes. State is plain files — no dependency on
+the optional download cache.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import msgspec
+
+
+class ResumeMeta(msgspec.Struct, frozen=True):
+    """Identity and size of the object a ``.part`` file is downloading."""
+
+    identity: str | None
+    size: int
+
+
+_encoder = msgspec.json.Encoder()
+_decoder = msgspec.json.Decoder(ResumeMeta)
+
+
+def read_meta(path: Path) -> ResumeMeta | None:
+    """Return the sidecar meta at *path*, or ``None`` if missing/corrupt."""
+    try:
+        return _decoder.decode(path.read_bytes())
+    except (OSError, msgspec.DecodeError):
+        return None
+
+
+def write_meta(path: Path, meta: ResumeMeta) -> None:
+    path.write_bytes(_encoder.encode(meta))