runpod 2.0.1.dev1__tar.gz → 2.1.0__tar.gz

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

@@ -8,12 +8,26 @@
 
 ### 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.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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runpod
-Version: 2.0.1.dev1
+Version: 2.1.0
 Summary: 🐍 | Python library for Runpod API and serverless worker SDK.
 Home-page: https://runpod.io
 Author: Runpod

runpod-2.1.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.0.1.dev1 → runpod-2.1.0}/docs/cli/references/command_line_interface.md

@@ -34,11 +34,14 @@ rp --help
 ### Authenticate
 
 ```bash
-rp login                        # browser approval
+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`.
 

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

@@ -8,7 +8,7 @@ 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`.
 

{runpod-2.0.1.dev1 → runpod-2.1.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.1.0'
+__version_tuple__ = version_tuple = (2, 1, 0)
 
-__commit_id__ = commit_id = 'ga4ba07898'
+__commit_id__ = commit_id = 'g0d59088b9'

runpod-2.1.0/runpod/api/_rate_limit.py

@@ -0,0 +1,259 @@
+"""Shared REST quotas for threads and asynchronous callers."""
+
+import hmac
+import math
+import os
+import random
+import re
+import threading
+import time
+from concurrent.futures import Future
+from contextlib import contextmanager
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+from typing import Mapping, Optional
+from urllib.parse import urlsplit
+
+from runpod.error import RateLimitError
+
+
+def _retry_after(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        delay = float(value)
+    except ValueError:
+        try:
+            date = parsedate_to_datetime(value)
+            if date.tzinfo is None:
+                date = date.replace(tzinfo=timezone.utc)
+            delay = date.timestamp() - time.time()
+        except (ValueError, TypeError, OverflowError):
+            return None
+        delay = max(0.0, delay)
+    return delay if math.isfinite(delay) and delay >= 0 else None
+
+
+def _windows(value: str) -> dict[str, tuple[int, float]]:
+    windows = {}
+    for member in value.split(","):
+        parts = member.strip().split(";")
+        if parts[0] not in {'"minute"', '"hour"', '"day"'}:
+            continue
+        parameters = {}
+        for part in parts[1:]:
+            match = re.fullmatch(r"\s*([a-z]+)\s*=\s*([0-9]{1,15})\s*", part)
+            if match:
+                parameters[match[1]] = int(match[2])
+        if "r" in parameters and "t" in parameters:
+            windows[parts[0]] = (parameters["r"], float(parameters["t"]))
+    return windows
+
+
+class _RetryBudget:
+    def __init__(self, max_retries: int, max_wait: float, query: str):
+        self.max_retries = max_retries
+        self.remaining_wait = max_wait
+        self.query = query
+
+    def wait(self, delay: float) -> None:
+        if delay > self.remaining_wait:
+            raise RateLimitError(
+                "Rate limit wait budget exceeded", self.query, retry_after=delay
+            )
+        self.remaining_wait -= delay
+
+    def can_retry(self, attempt: int, retry_after: Optional[float]) -> bool:
+        return (
+            retry_after is not None
+            and attempt < self.max_retries
+            and retry_after <= self.remaining_wait
+        )
+
+
+class _Bucket:
+    def __init__(self):
+        self.lock = threading.Lock()
+        self.waiters: set[Future[None]] = set()
+        self.windows: dict[str, tuple[Optional[int], float]] = {}
+        self.estimates: dict[str, int] = {}
+        self.reset_lower_bounds: dict[str, float] = {}
+        self.blocked_until = 0.0
+        self.discovered = False
+        self.in_flight = 0
+        self.users = 0
+        self.last_used = time.monotonic()
+
+    def acquire(self, budget: Optional[_RetryBudget] = None) -> float | Future[None]:
+        with self.lock:
+            now = time.monotonic()
+            delay = max(0.0, self.blocked_until - now)
+            for name, (remaining, reset_at) in self.windows.items():
+                if remaining is not None and now >= reset_at:
+                    self.windows[name] = (None, reset_at)
+                    if remaining == 0:
+                        self.discovered = False
+                elif remaining == 0:
+                    delay = max(delay, reset_at - now)
+            if delay:
+                if budget is not None:
+                    budget.wait(delay)
+                return delay
+            if self.in_flight and (
+                not self.discovered or (self.blocked_until and not delay)
+            ):
+                waiter: Future[None] = Future()
+                self.waiters.add(waiter)
+                waiter.add_done_callback(self._remove_waiter)
+                return waiter
+            self.in_flight += 1
+            for name, (remaining, reset_at) in self.windows.items():
+                if remaining is not None:
+                    self.windows[name] = (max(0, remaining - 1), reset_at)
+                    self.estimates[name] = max(0, self.estimates[name] - 1)
+            return 0.0
+
+    def _remove_waiter(self, waiter: Future[None]) -> None:
+        with self.lock:
+            self.waiters.discard(waiter)
+
+    def _notify_waiters(self) -> None:
+        with self.lock:
+            waiters, self.waiters = self.waiters, set()
+        for waiter in waiters:
+            if waiter.set_running_or_notify_cancel():
+                waiter.set_result(None)
+
+    def update(
+        self,
+        status: int,
+        headers: Mapping[str, str],
+        attempt: int,
+        *,
+        started_at: Optional[float] = None,
+    ) -> Optional[float]:
+        windows = _windows(
+            ", ".join(
+                value for key, value in headers.items() if key.lower() == "ratelimit"
+            )
+        )
+        headers = {key.lower(): value for key, value in headers.items()}
+        retry_after = None
+        if status == 429:
+            retry_after = _retry_after(headers.get("retry-after"))
+            if retry_after is None:
+                retry_after = random.uniform(0.5, 1.0) * 2 ** min(attempt, 6)
+        with self.lock:
+            now = time.monotonic()
+            self.discovered = True
+            if self.blocked_until <= now:
+                self.blocked_until = 0.0
+            for name, (remaining, reset_after) in windows.items():
+                reset_at = now + reset_after
+                reset_lower = (now if started_at is None else started_at) + max(
+                    0.0, reset_after - 1.0
+                )
+                previous, previous_reset = self.windows.get(name, (None, 0.0))
+                previous_lower = self.reset_lower_bounds.get(name, 0.0)
+                if reset_at < previous_lower:
+                    continue
+                if (
+                    previous is not None
+                    and now < previous_reset
+                    and reset_lower <= previous_reset
+                ):
+                    remaining = min(remaining, self.estimates[name])
+                    reset_at = min(reset_at, previous_reset)
+                    reset_lower = max(reset_lower, previous_lower)
+                self.estimates[name] = remaining
+                self.reset_lower_bounds[name] = reset_lower
+                self.windows[name] = (
+                    max(0, remaining - max(0, self.in_flight - 1)),
+                    reset_at,
+                )
+            for name in list(self.windows):
+                if name not in windows and self.windows[name][1] <= now:
+                    del self.windows[name]
+                    del self.estimates[name]
+                    del self.reset_lower_bounds[name]
+            if retry_after is not None:
+                retry_after = max(
+                    retry_after,
+                    self.blocked_until - now,
+                    *(
+                        reset - now
+                        for name, (_, reset) in self.windows.items()
+                        if self.estimates[name] == 0
+                    ),
+                    0.0,
+                )
+                self.blocked_until = max(self.blocked_until, now + retry_after)
+        self._notify_waiters()
+        return retry_after
+
+    def release(self):
+        with self.lock:
+            self.in_flight -= 1
+            for name, (remaining, reset_at) in self.windows.items():
+                if remaining is not None:
+                    self.windows[name] = (
+                        max(0, self.estimates[name] - self.in_flight),
+                        reset_at,
+                    )
+        self._notify_waiters()
+
+
+class _RateLimits:
+    def __init__(self):
+        self.lock = threading.Lock()
+        self.fingerprint_key = os.urandom(32)
+        self.buckets: dict[tuple[str, str, bytes], _Bucket] = {}
+        self.next_cleanup = 0.0
+
+    @contextmanager
+    def bucket(self, url: str, api_key: str):
+        origin = urlsplit(url)
+        key = (
+            origin.scheme.lower(),
+            origin.netloc.lower(),
+            hmac.digest(self.fingerprint_key, api_key.encode(), "sha256"),
+        )
+        with self.lock:
+            now = time.monotonic()
+            if now >= self.next_cleanup:
+                for cached_key, bucket in list(self.buckets.items()):
+                    if bucket.users or now - bucket.last_used < 300:
+                        continue
+                    with bucket.lock:
+                        if bucket.blocked_until <= now and all(
+                            reset <= now for _, reset in bucket.windows.values()
+                        ):
+                            del self.buckets[cached_key]
+                self.next_cleanup = now + 60
+            bucket = self.buckets.setdefault(key, _Bucket())
+            bucket.users += 1
+        try:
+            yield bucket
+        finally:
+            with self.lock:
+                bucket.users -= 1
+                bucket.last_used = time.monotonic()
+
+
+def _validate_retry_options(max_retries: int, max_rate_limit_wait: float) -> None:
+    if (
+        isinstance(max_retries, bool)
+        or not isinstance(max_retries, int)
+        or max_retries < 0
+    ):
+        raise ValueError("max_retries must be a non-negative integer")
+    if (
+        isinstance(max_rate_limit_wait, bool)
+        or not isinstance(max_rate_limit_wait, (int, float))
+        or not math.isfinite(max_rate_limit_wait)
+        or max_rate_limit_wait < 0
+    ):
+        raise ValueError("max_rate_limit_wait must be finite and non-negative")
+
+
+rate_limits = _RateLimits()

{runpod-2.0.1.dev1 → runpod-2.1.0}/runpod/api/graphql.py

@@ -98,9 +98,8 @@ async def run_graphql_query_async(
         variables: Optional GraphQL variables to send with the query.
         timeout: Total request timeout in seconds.
         anonymous: Send the request without credentials even when a key
-            is available. The browser-login flow requires this: the
-            server only releases the granted key to guest requests, so
-            a stale stored key would make the poll spin forever.
+            is available. Login creates its auth request this way so a
+            stale stored key cannot fail the request.
     """
     import aiohttp  # pylint: disable=import-outside-toplevel
 

{runpod-2.0.1.dev1 → runpod-2.1.0}/runpod/api/queries/apps.py

@@ -66,13 +66,12 @@ query getFlashEnvironmentByName($input: FlashEnvironmentByNameInput!) {
 }
 """
 
+# no apiKey: the console shows the key only to the approver.
 QUERY_FLASH_AUTH_REQUEST_STATUS = """
 query flashAuthRequestStatus($flashAuthRequestId: String!) {
     flashAuthRequestStatus(flashAuthRequestId: $flashAuthRequestId) {
         id
         status
-        expiresAt
-        apiKey
     }
 }
 """