runpod 2.0.1.dev1__tar.gz → 2.2.0__tar.gz

{runpod-2.0.1.dev1 → runpod-2.2.0}/CHANGELOG.md

@@ -5,15 +5,56 @@
 ### Features
 
 * Apps expose `NetworkVolume` and `GlobalVolume` resources with explicit path-keyed mounts, lazy create-if-missing provisioning, and execution-bound filesystem access. Global volumes use GraphQL for lookup and creation.
+* Deployed Flash calls use endpoint or pod runtime credentials. Release requires deployed support from [RunPod#6686](https://github.com/runpod/RunPod/pull/6686), [ai-api#1176](https://github.com/runpod/ai-api/pull/1176), and [sdk-runtime#4](https://github.com/runpod-workers/sdk-runtime/pull/4).
+
+### Breaking Changes
+
+* Production endpoint environment variables reserve `RUNPOD_API_KEY` and runtime identity fields. Workers authenticate Flash calls with platform-issued runtime credentials; application credentials must use non-reserved environment names.
+* Deployed workers can invoke Flash resources only within their own app and environment, including through `Queue`, `Api`, and `Task` stubs. Local clients use account credentials subject to their permissions.
+* Remote queues, tasks, and JSON API calls require finite JSON-compatible arguments and results in local, dev, and deployed execution. Dev workers receive source separately from the JSON argument contract. Explicit `.local()` calls run Python directly.
 
 ### Bug Fixes
 
+* [BREAKING] `rp login` asks you to paste the API key shown in the console after approval. It no longer collects the key by polling the auth request, and it fails fast without an interactive terminal.
 * Task calls support indefinite execution with bounded interruption cleanup. Failed deletion retains the pod ID for recovery.
 * Network volume creation intersects catalog storage support with every sharing resource's hardware stock and datacenter constraints. Unsupported explicit pins fail before creation; existing volumes retain their authoritative IDs and datacenters.
 * Global volume attachments require GPU compute for tasks and endpoints.
 * Deployment artifacts apply project ignore rules and mandatory secret-file exclusions while preserving vendored dependency assets.
 * Synchronous calls wait across polling timeouts on Python 3.10 and propagate operation timeouts.
 
+## [2.2.0](https://github.com/runpod/runpod-python/compare/v2.1.0...v2.2.0) (2026-11-09)
+
+
+### Features
+
+* invoke deployed flash tasks with runtime credentials (SEC-375 CON-1833) ([#644](https://github.com/runpod/runpod-python/issues/644)) ([367f174](https://github.com/runpod/runpod-python/commit/367f174ef14cc7fcf909a3b26413c3f2d38cbd9b))
+* make console, proxy, and endpoint hosts configurable ([#684](https://github.com/runpod/runpod-python/issues/684)) ([b9583f7](https://github.com/runpod/runpod-python/commit/b9583f7c0a02e6c0cbb9598538393fc239d88852))
+* resumable network volume upload and download ([#655](https://github.com/runpod/runpod-python/issues/655)) ([a677ee9](https://github.com/runpod/runpod-python/commit/a677ee9f08f21da5a29cc126ed63032fc1063365))
+
+
+### Bug Fixes
+
+* **apps:** accept datacenter ids outside the built-in list ([#690](https://github.com/runpod/runpod-python/issues/690)) ([dbc251a](https://github.com/runpod/runpod-python/commit/dbc251ac8ba87ed4cc53f71010bc8c87dba1c77d))
+* **serverless:** stop taking jobs after a per-job refresh_worker (SLS-900) ([#663](https://github.com/runpod/runpod-python/issues/663)) ([8ca9d9b](https://github.com/runpod/runpod-python/commit/8ca9d9bcfdc0ad1792e899cdef49a4fd172fbb13))
+
+
+### Documentation
+
+* rename getting_Started.md to getting_started.md ([#697](https://github.com/runpod/runpod-python/issues/697)) ([fbcabcd](https://github.com/runpod/runpod-python/commit/fbcabcd73889783d8e03b6261154891f13b0d9d6))
+
+## [2.1.0](https://github.com/runpod/runpod-python/compare/v2.0.0...v2.1.0) (2026-11-03)
+
+
+### Features
+
+* rp login prompts for the api key instead of polling ([#675](https://github.com/runpod/runpod-python/issues/675)) ([2217b6d](https://github.com/runpod/runpod-python/commit/2217b6d15a0554e2652506068f438d740392ad37))
+
+
+### Bug Fixes
+
+* coordinate REST API rate limits and bound retries ([#618](https://github.com/runpod/runpod-python/issues/618)) ([d6ce9a8](https://github.com/runpod/runpod-python/commit/d6ce9a8c572ac117f0641846f45dadaa40954e57))
+* require https for documented cli installation ([#674](https://github.com/runpod/runpod-python/issues/674)) ([946afb4](https://github.com/runpod/runpod-python/commit/946afb4ea45ac526c81106783faeac73caf17ee6))
+
 ## [2.1.0](https://github.com/runpod/runpod-python/compare/v2.0.0...v2.1.0) (2026-10-28)
 
 

{runpod-2.0.1.dev1/runpod.egg-info → runpod-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runpod
-Version: 2.0.1.dev1
+Version: 2.2.0
 Summary: 🐍 | Python library for Runpod API and serverless worker SDK.
 Home-page: https://runpod.io
 Author: Runpod
@@ -34,7 +34,6 @@ Requires-Dist: backoff>=2.2.1
 Requires-Dist: boto3>=1.43.118
 Requires-Dist: certifi>=2026.10.19
 Requires-Dist: click>=8.5.0
-Requires-Dist: cloudpickle>=3.1.2
 Requires-Dist: colorama<0.4.7,>=0.4.6
 Requires-Dist: cryptography>=50.0.2
 Requires-Dist: fastapi[all]>=0.162.0
@@ -143,6 +142,18 @@ make setup
 make test
 ```
 
+## Remote values
+
+Queue and task calls use finite JSON-compatible arguments, return values,
+and stream chunks. JSON conversion turns tuples into lists and supported
+dictionary keys into strings, including in same-worker remote calls.
+Bytes, custom objects, circular references, and non-finite numbers produce
+explicit errors. `.local()` remains a direct Python call.
+
+Successful function responses contain `json_result`, including for a null
+return value. SDK and worker runtimes share the JSON protocol validators;
+use compatible package releases when building worker images.
+
 ## ⚡ | Serverless Worker (SDK)
 
 This python package can also be used to create a serverless worker that can be deployed to Runpod as a custom endpoint API.

{runpod-2.0.1.dev1 → runpod-2.2.0}/README.md

@@ -84,6 +84,18 @@ make setup
 make test
 ```
 
+## Remote values
+
+Queue and task calls use finite JSON-compatible arguments, return values,
+and stream chunks. JSON conversion turns tuples into lists and supported
+dictionary keys into strings, including in same-worker remote calls.
+Bytes, custom objects, circular references, and non-finite numbers produce
+explicit errors. `.local()` remains a direct Python call.
+
+Successful function responses contain `json_result`, including for a null
+return value. SDK and worker runtimes share the JSON protocol validators;
+use compatible package releases when building worker images.
+
 ## ⚡ | Serverless Worker (SDK)
 
 This python package can also be used to create a serverless worker that can be deployed to Runpod as a custom endpoint API.

runpod-2.2.0/docs/api/handling_errors.md

@@ -0,0 +1,69 @@
+# Handling API errors
+
+Authentication failures raise `AuthenticationError`:
+
+```python
+import runpod
+
+try:
+    runpod.get_pods()
+except runpod.error.AuthenticationError as err:
+    print(err)
+```
+
+REST API problem responses raise `QueryError`. The exception includes the HTTP
+status code, request method and path, and request-validation errors when present:
+
+```python
+try:
+    runpod.create_pod(
+        "training",
+        "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
+        "NVIDIA GeForce RTX 4090",
+    )
+except runpod.error.QueryError as err:
+    print(err.status_code)
+    print(err.query)
+    print(err.errors)
+```
+
+## REST rate limits
+
+REST calls share Runpod's minute, hour, and day quotas across routes within the
+process, keyed by API origin and API key. Both synchronous and asynchronous calls
+reserve the remaining budget advertised by the `RateLimit` response header and
+wait when a window is exhausted. Separate processes and different API keys for the
+same account cannot coordinate their local budgets.
+
+Quota estimates account for outstanding requests separately from response
+snapshots. A window refreshes when the response timing establishes a later reset;
+out-of-order snapshots within a window cannot restore spent quota. Discovery and
+reset probes coordinate concurrent callers without consuming their rate-limit
+wait budgets.
+
+HTTP 429 responses honor `Retry-After` in seconds or HTTP-date format. Missing or
+invalid retry hints use capped exponential backoff with jitter. By default, a call
+allows three retries and at most 60 seconds of cumulative rate-limit sleeps.
+Network failures and other HTTP errors are not retried, since a failed response
+can follow a successful resource mutation.
+
+An exhausted retry or wait budget raises `RateLimitError`, a `QueryError` subclass
+with `status_code=429` and a `retry_after` delay in seconds. A successful call that
+uses the last available token still returns immediately; subsequent calls wait or
+raise if the required delay exceeds their wait budget.
+
+```python
+try:
+    pods = runpod.get_pods()
+except runpod.error.RateLimitError as err:
+    print(f"Quota exhausted. Retry after {err.retry_after:.1f} seconds.")
+```
+
+The low-level `runpod.api.rest.run_rest_request` and `run_rest_request_async`
+functions accept `max_retries` and `max_rate_limit_wait` keyword arguments. Set
+`max_retries=0` to surface the first 429, or `max_rate_limit_wait=0` to fail rather
+than sleep for an exhausted quota. `timeout` applies separately to each HTTP
+attempt. Async quota waits are cancellable and do not block the event loop.
+
+These protections apply to the management REST API transport. GraphQL calls and
+Serverless job execution use separate transports.

runpod-2.2.0/docs/cli/references/command_line_interface.md

@@ -0,0 +1,104 @@
+# Runpod CLI
+
+Note: This CLI is not the same as runpodctl and provides a different set of features.
+
+```bash
+# Auth
+rp login
+
+# Flash apps
+rp flash init my-app
+rp flash dev main.py
+rp flash deploy
+rp flash app list
+rp flash env list --app my-app
+rp flash undeploy --app my-app
+
+# SSH
+rp ssh add          # add a key to your account
+rp ssh list         # list account keys
+rp ssh POD_ID       # open a terminal on a pod
+
+# Pods
+rp pod list
+rp pod create
+rp pod connect POD_ID
+
+# Network volume files
+rp volume upload VOLUME ./dataset datasets/dataset
+rp volume download VOLUME outputs/ ./outputs
+```
+
+## Overview
+
+```bash
+rp --help
+```
+
+### Authenticate
+
+```bash
+rp login                        # browser approval, then paste the key
+rp login --api-key YOUR_KEY     # store a key directly
+rp login --profile staging      # save browser credentials in a named profile
+```
+
+`rp login` opens the console to approve the request. After you approve, the console shows a new API key; paste it at the hidden prompt. The CLI checks the key before saving it.
+`rp login` needs an interactive terminal. In CI or scripts, set `RUNPOD_API_KEY` or use `rp login --api-key`.
+
+Credentials are stored in `~/.runpod/config.toml`.
+Use `--profile NAME` with either login method to update only that profile; the default is `default`.
+Set `RUNPOD_PROFILE=NAME` to select the profile for all commands and for `runpod` in Python; `--profile` overrides it, and `RUNPOD_API_KEY` overrides any stored profile.
+
+### Flash apps
+
+```bash
+rp flash init my-app              # scaffold a project
+rp flash dev main.py              # run a live development session
+rp flash deploy                   # deploy the current project
+rp flash app list                 # list deployed apps
+rp flash env list --app my-app    # list an app's environments
+rp flash undeploy --app my-app    # delete an environment's endpoints
+```
+
+App discovery imports modules synchronously. Keep blocking work inside an
+entrypoint or a resource function; interrupt discovery if an import blocks.
+
+On Ctrl-C, a dev session waits for its running local entrypoint to finish before
+deleting endpoints. Blocking entrypoint code can delay shutdown. Cleanup failures
+exit with an error and report the endpoint IDs that still need deletion.
+
+### Network volume files
+
+```bash
+rp volume upload VOLUME ./model.safetensors models/
+rp volume upload VOLUME ./dataset datasets/dataset
+rp volume download VOLUME models/model.safetensors
+rp volume download VOLUME outputs/ ./outputs
+```
+
+Transfers use the volume's S3-compatible API, so they need S3 API keys
+(separate from the API key): set `RUNPOD_S3_ACCESS_KEY` and
+`RUNPOD_S3_SECRET_KEY`, pass `--s3-access-key` / `--s3-secret-key`, or save
+`s3_access_key` / `s3_secret_key` in `~/.runpod/config.toml`. The CLI prompts
+for missing keys and offers to save them. You can omit `VOLUME` in an
+interactive session to pick a volume from a list. The
+volume must be in a [datacenter with the S3 API](https://docs.runpod.io/storage/s3-api).
+`VOLUME` is the volume's ID or name, looked up with your API key.
+
+To resume an interrupted transfer, run the same command again. Files that
+are unchanged (same size, destination not older) are skipped, a large upload
+reuses the parts it already sent, and a large download keeps its finished
+chunks in `<name>.rpdownload`. `--force` transfers every file. Parts of an
+upload that is never resumed stay in the volume's hidden `.s3compat_uploads`
+folder and count toward its size.
+
+The same transfers are available from Python:
+
+```python
+from runpod import NetworkVolume
+
+volume = NetworkVolume("my-volume")
+volume.upload("./dataset", "datasets/dataset")
+volume.download("outputs/", "./outputs")
+```

{runpod-2.0.1.dev1 → runpod-2.2.0}/docs/cli/start_here.md

@@ -8,10 +8,12 @@ Note: This CLI is not the same as runpodctl and provides a different set of feat
 
 ### Authenticate
 
-Store your Runpod API key by running `rp login` (browser approval) or `rp login --api-key YOUR_KEY`. Credentials are stored in `~/.runpod/config.toml`.
+Store your Runpod API key by running `rp login` (approve in the browser, then paste the key the console shows) or `rp login --api-key YOUR_KEY`. Credentials are stored in `~/.runpod/config.toml`.
 
 Pass `--profile staging` with either login method to update a named credential profile without changing the others. The default profile is `default`.
 
+Set `RUNPOD_PROFILE=staging` to use that profile for every command, including `rp login`. `--profile` takes precedence over `RUNPOD_PROFILE`, and `RUNPOD_API_KEY` takes precedence over any stored profile.
+
 ### SSH
 
 Add an SSH key to your account by running `rp ssh add`. To use an existing key pass `--key` or `--key-file`. Keys are stored in `~/.runpod/ssh/`. If no key is specified a new one is generated and stored.

runpod-2.2.0/docs/getting_started.md

@@ -0,0 +1,34 @@
+# Getting Started
+
+The Runpod python library is a powerful library providing SDK functions, API access, and CLI commands for interacting with the Runpod platform.
+
+## Credentials File
+
+`rp login` stores your API key in `~/.runpod/config.toml`, one table per profile:
+
+```toml
+[default]
+api_key = "YOUR_RUNPOD_API_KEY"
+```
+
+### Profile
+
+By default, credentials are stored under and read from the `default` profile. To store a key under another profile, pass `--profile` to `rp login`:
+
+```bash
+rp login --profile my_profile
+```
+
+To use that profile, set the `RUNPOD_PROFILE` environment variable before importing `runpod`. The library reads the profile and its API key once, at import time.
+
+```bash
+export RUNPOD_PROFILE=my_profile
+```
+
+`RUNPOD_API_KEY`, when set, takes precedence over any stored profile. Inside a script, you can also set the key directly:
+
+```python
+import runpod
+
+runpod.api_key = "YOUR_RUNPOD_API_KEY"
+```

{runpod-2.0.1.dev1 → runpod-2.2.0}/requirements.txt

@@ -5,7 +5,6 @@ backoff >= 2.2.1
 boto3 >= 1.43.118
 certifi >= 2026.10.19
 click >= 8.5.0
-cloudpickle >= 3.1.2
 colorama >= 0.4.6, < 0.4.7
 cryptography >= 50.0.2
 fastapi[all] >= 0.162.0

{runpod-2.0.1.dev1 → runpod-2.2.0}/runpod/__init__.py

@@ -54,6 +54,7 @@ _LAZY_ATTRS = {
     "Model": "runpod.apps",
     "NetworkVolume": "runpod.apps",
     "Queue": "runpod.apps",
+    "Task": "runpod.apps",
     "Secret": "runpod.apps",
     "Volume": "runpod.apps",
     "is_local": "runpod.apps",
@@ -86,6 +87,18 @@ __all__ = [
 ]
 
 
+DEFAULT_PROFILE = "default"
+
+
+def _selected_profile() -> str:
+    """credential profile in ~/.runpod/config.toml to use.
+
+    set RUNPOD_PROFILE to pick a named profile (saved with
+    `rp login --profile NAME`); unset or blank means "default".
+    """
+    return os.environ.get("RUNPOD_PROFILE", "").strip() or DEFAULT_PROFILE
+
+
 def _load_api_key():
     """resolve the api key from the environment, then stored credentials.
 
@@ -102,7 +115,7 @@ def _load_api_key():
         ).get_credentials(profile)
     except Exception:  # noqa: BLE001 - no stored key is a valid state
         return None
-    return creds["api_key"] if creds else None
+    return creds.get("api_key") if creds else None
 
 
 def __getattr__(name):
@@ -118,7 +131,7 @@ def __getattr__(name):
 # ------------------------------- Config Paths ------------------------------- #
 SSH_KEY_PATH = os.path.expanduser("~/.runpod/ssh")
 
-profile = "default"  # pylint: disable=invalid-name
+profile = _selected_profile()  # pylint: disable=invalid-name
 
 api_key = _load_api_key()  # pylint: disable=invalid-name
 

runpod-2.2.0/runpod/_hosts.py

@@ -0,0 +1,54 @@
+"""Service hosts used to build console, proxy, and endpoint URLs.
+
+Each host can be overridden with an environment variable, which is read on
+every call so a change takes effect without re-importing ``runpod``. Unset or
+blank values fall back to the public Runpod hosts.
+
+    RUNPOD_CONSOLE_URL        web console base URL (default https://console.runpod.io)
+    RUNPOD_PROXY_DOMAIN       pod HTTP proxy domain (default proxy.runpod.net)
+    RUNPOD_ENDPOINT_BASE_URL  serverless base URL (default https://api.runpod.ai/v2)
+
+The endpoint domain is the host of ``RUNPOD_ENDPOINT_BASE_URL``. When that is
+unset or blank, a non-blank ``runpod.endpoint_url_base`` set programmatically
+is used instead.
+
+Example:
+    >>> proxy_url("abc123", 8080)
+    'https://abc123-8080.proxy.runpod.net'
+"""
+
+import os
+from typing import Union
+
+DEFAULT_CONSOLE_URL = "https://console.runpod.io"
+DEFAULT_PROXY_DOMAIN = "proxy.runpod.net"
+DEFAULT_ENDPOINT_BASE_URL = "https://api.runpod.ai/v2"
+
+
+def _env(name: str, default: str) -> str:
+    value = os.environ.get(name, "").strip()
+    return value or default
+
+
+def console_url() -> str:
+    """Web console base URL, without a trailing slash."""
+    return _env("RUNPOD_CONSOLE_URL", DEFAULT_CONSOLE_URL).rstrip("/")
+
+
+def proxy_url(pod_id: str, port: Union[int, str]) -> str:
+    """Public HTTP proxy URL for ``port`` on ``pod_id``."""
+    domain = _env("RUNPOD_PROXY_DOMAIN", DEFAULT_PROXY_DOMAIN).strip("/")
+    return f"https://{pod_id}-{port}.{domain}"
+
+
+def endpoint_domain() -> str:
+    """Host of the serverless data plane, e.g. ``api.runpod.ai``.
+
+    Load-balanced endpoints are served on ``<endpoint_id>.<endpoint_domain>``.
+    """
+    import runpod
+
+    module_base = (runpod.endpoint_url_base or "").strip()
+    base = _env("RUNPOD_ENDPOINT_BASE_URL", module_base or DEFAULT_ENDPOINT_BASE_URL)
+    host = base.split("://", 1)[-1]
+    return host.split("/", 1)[0]

runpod-2.2.0/runpod/_serialization.py

@@ -0,0 +1,21 @@
+"""finite json validation and wire-value conversion for callers and workers."""
+
+import json
+from typing import Any
+
+
+def _json_text(value: Any, label: str) -> str:
+    try:
+        return json.dumps(value, allow_nan=False)
+    except (TypeError, ValueError, RecursionError) as exc:
+        raise TypeError(f"{label} must be json-serializable: {exc}") from exc
+
+
+def validate_json(value: Any, label: str = "value") -> None:
+    """require values encodable as finite json."""
+    _json_text(value, label)
+
+
+def normalize_json(value: Any, label: str = "value") -> Any:
+    """apply json's container and key conversions without a network roundtrip."""
+    return json.loads(_json_text(value, label))

{runpod-2.0.1.dev1 → runpod-2.2.0}/runpod/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.1.dev1'
-__version_tuple__ = version_tuple = (2, 0, 1, 'dev1')
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
 
-__commit_id__ = commit_id = 'ga4ba07898'
+__commit_id__ = commit_id = 'g89d72b8c4'

runpod-2.2.0/runpod/_volume_transfer_utils.py

@@ -0,0 +1,171 @@
+"""Filesystem and checksum helpers for resumable transfers.
+
+This private module keeps disk state and path safety details out of the S3
+request orchestration. network_volume_transfer re-exports the error type.
+"""
+
+import hashlib
+import json
+import os
+import unicodedata
+from pathlib import Path, PurePosixPath
+from typing import Any, Dict, List, Optional
+
+MIB = 1024 * 1024
+PARTIAL_SUFFIX = ".rpdownload"
+SIDECAR_SUFFIX = ".rpdownload.json"
+# every file a download writes next to its target
+TRANSFER_SUFFIXES = (PARTIAL_SUFFIX, SIDECAR_SUFFIX, SIDECAR_SUFFIX + ".tmp")
+
+
+class NetworkVolumeTransferError(RuntimeError):
+    """a transfer failed. `resumable` says whether re-running can help."""
+
+    def __init__(self, message: str, resumable: bool = False):
+        super().__init__(message)
+        self.resumable = resumable
+
+
+def _read_json(path: Path) -> Optional[Dict[str, Any]]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _write_json(path: Path, data: Dict[str, Any]) -> None:
+    """replace path atomically, synced, so a crash leaves the old state or
+    the new one."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as handle:
+        json.dump(data, handle)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(tmp, path)
+    _sync_dir(path.parent)
+
+
+def _sync_dir(path: Path) -> None:
+    """make a rename in path survive a power loss. best effort: windows
+    cannot open a directory."""
+    try:
+        fd = os.open(path, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        # some filesystems refuse fsync on a directory; the rename stands
+        pass
+    finally:
+        os.close(fd)
+
+
+def _md5_hex(path: Path, offset: int, length: int) -> str:
+    digest = hashlib.md5()  # noqa: S324 - etag comparison, not security
+    with open(path, "rb") as handle:
+        handle.seek(offset)
+        while length > 0 and (block := handle.read(min(8 * MIB, length))):
+            digest.update(block)
+            length -= len(block)
+    return digest.hexdigest()
+
+
+def _etag(value: Any) -> str:
+    return str(value or "").strip('"')
+
+
+def _is_md5(etag: str) -> bool:
+    return len(etag) == 32 and all(c in "0123456789abcdef" for c in etag.lower())
+
+
+def _multipart_etag(parts: List[Dict[str, Any]]) -> str:
+    """the etag s3 (and runpod, verified) gives an object assembled from
+    parts: md5 of the parts' binary md5s, then "-<count>". "" when a part
+    etag is not an md5."""
+    etags = [_etag(part["ETag"]) for part in parts]
+    if not all(_is_md5(etag) for etag in etags):
+        return ""
+    digest = hashlib.md5(b"".join(bytes.fromhex(etag) for etag in etags))  # noqa: S324
+    return f"{digest.hexdigest()}-{len(parts)}"
+
+
+def _same_version(a: os.stat_result, b: os.stat_result) -> bool:
+    return a.st_size == b.st_size and a.st_mtime_ns == b.st_mtime_ns
+
+
+def _not_older(a: float, b: float) -> bool:
+    """a >= b in whole seconds; s3 dates carry no finer precision."""
+    return int(a) >= int(b)
+
+
+def _check_remote_path(remote_path: Optional[str]) -> None:
+    if remote_path and ".." in remote_path.replace("\\", "/").split("/"):
+        raise ValueError(f"remote path {remote_path!r} must not contain '..'")
+
+
+def _check_local_names(targets: List[Path], root: Path) -> None:
+    """refuse targets that would share a path on disk: two that are one name
+    on a case-insensitive or normalizing filesystem ("Model.bin" and
+    "model.bin"), a file whose name is also a folder another file lives in
+    ("a" beside "A/b"), or a file whose partial, sidecar or sidecar temp name
+    is also a target or a folder one lives in ("x" beside "x.rpdownload/y").
+    names are compared nfc-normalized (apfs ignores normalization) and case
+    folded, which can refuse a listing a case-sensitive filesystem would
+    take: the safe direction."""
+
+    def fold(path: PurePosixPath) -> str:
+        return unicodedata.normalize("NFC", str(path)).casefold()
+
+    rels = [PurePosixPath(target.relative_to(root).as_posix()) for target in targets]
+    files: Dict[str, PurePosixPath] = {}
+    dirs: Dict[str, PurePosixPath] = {}
+    for rel in rels:
+        if fold(rel) in files:
+            raise NetworkVolumeTransferError(
+                f"cannot download both {files[fold(rel)]} and {rel}: they would be one "
+                "file on a case-insensitive or normalizing filesystem"
+            )
+        files[fold(rel)] = rel
+        dirs.update({fold(parent): rel for parent in rel.parents if str(parent) != "."})
+    for rel in rels:
+        if fold(rel) in dirs:
+            raise NetworkVolumeTransferError(
+                f"cannot download both {rel} and {dirs[fold(rel)]}: "
+                "the first would have to be a file and a folder"
+            )
+        for suffix in TRANSFER_SUFFIXES:
+            twin = fold(rel.with_name(rel.name + suffix))
+            other = files.get(twin) or dirs.get(twin)
+            if other is not None:
+                raise NetworkVolumeTransferError(
+                    f"cannot download both {rel} and {other}: "
+                    f"{rel.name + suffix} is used for the first's partial download"
+                )
+
+
+def _safe_target(root: Path, rel: str) -> Path:
+    """local path for a remote relative key, refusing anything outside root.
+    "." and empty segments are refused too: "a/./b" would alias "a/b"."""
+    segments = rel.split("/")
+    if (
+        rel.startswith("/")
+        or "\\" in rel
+        or any(seg in ("..", ".", "") for seg in segments)
+        or ":" in segments[0]
+    ):
+        raise NetworkVolumeTransferError(f"refusing unsafe remote path: {rel!r}")
+    target = root.joinpath(*segments)
+    if root.resolve() not in target.resolve().parents:
+        raise NetworkVolumeTransferError(f"refusing unsafe remote path: {rel!r}")
+    # a symlinked folder would let two remote paths share one local file,
+    # which the name collision check cannot see
+    for depth in range(1, len(segments)):
+        if root.joinpath(*segments[:depth]).is_symlink():
+            raise NetworkVolumeTransferError(
+                f"{root.joinpath(*segments[:depth])} is a symlink; "
+                "download into a folder without symlinked subfolders"
+            )
+    return target