internetdata 2.5.0__tar.gz → 2.6.1__tar.gz

{internetdata-2.5.0 → internetdata-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.5.0
+Version: 2.6.1
 Summary: Official Python client library for the InternetData API. Download and verify licensed IP datasets.
 Project-URL: Homepage, https://internetdata.io
 Project-URL: Documentation, https://docs.internetdata.io
@@ -203,6 +203,26 @@ client = InternetData(tokens.apikey)
 
 A refusal raises `OauthAccessDeniedError` and a code that ran out raises `OauthExpiredTokenError`, and client IDs are issued on request from support@internetdata.io. `client.oauth.revoke("your-client-id", tokens.refresh_token)` signs the machine out.
 
+### Sign in with OAuth (authorization code)
+
+An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
+
+```python
+from internetdata import InternetData
+
+signin = InternetData()
+redirect_uri = "http://127.0.0.1:8765/callback"
+pkce = signin.oauth.create_pkce()
+
+url = signin.oauth.authorization_url(
+    "your-client-id", redirect_uri, pkce.challenge, scope="apikeys.use", state="your-state"
+)
+# Open url in the browser. Its redirect to redirect_uri carries code and state.
+tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.verifier, redirect_uri)
+```
+
+Check that `state` came back as you sent it before you exchange `code`, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so `tokens.apikey` stays `None`.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.5.0 → internetdata-2.6.1}/README.md

@@ -169,6 +169,26 @@ client = InternetData(tokens.apikey)
 
 A refusal raises `OauthAccessDeniedError` and a code that ran out raises `OauthExpiredTokenError`, and client IDs are issued on request from support@internetdata.io. `client.oauth.revoke("your-client-id", tokens.refresh_token)` signs the machine out.
 
+### Sign in with OAuth (authorization code)
+
+An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
+
+```python
+from internetdata import InternetData
+
+signin = InternetData()
+redirect_uri = "http://127.0.0.1:8765/callback"
+pkce = signin.oauth.create_pkce()
+
+url = signin.oauth.authorization_url(
+    "your-client-id", redirect_uri, pkce.challenge, scope="apikeys.use", state="your-state"
+)
+# Open url in the browser. Its redirect to redirect_uri carries code and state.
+tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.verifier, redirect_uri)
+```
+
+Check that `state` came back as you sent it before you exchange `code`, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so `tokens.apikey` stays `None`.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.5.0 → internetdata-2.6.1}/src/internetdata/__init__.py

@@ -34,11 +34,12 @@ from .models import (
     MetadataColumn,
     OauthMetadata,
     Outcome,
+    Pkce,
     Standing,
     TokenResponse,
 )
 
-__version__ = "2.5.0"
+__version__ = "2.6.1"
 
 __all__ = [
     "DATABASE_FORMATS",
@@ -66,6 +67,7 @@ __all__ = [
     "OauthExpiredTokenError",
     "OauthMetadata",
     "Outcome",
+    "Pkce",
     "Standing",
     "TokenResponse",
     "__version__",

{internetdata-2.5.0 → internetdata-2.6.1}/src/internetdata/_core.py

@@ -4,24 +4,28 @@ each attempt, response unwrapping, and the retry policy."""
 from __future__ import annotations
 
 import asyncio
+import base64
 import contextlib
 import contextvars
+import hashlib
 import json
 import math
 import os
+import secrets
 import threading
 import time
 from collections.abc import Awaitable, Callable, Iterator
 from pathlib import Path
 from types import ModuleType
 from typing import IO, Any, TypeVar, cast
+from urllib.parse import quote
 
 import httpx
 
 from ._generated.client import AuthenticatedClient, Client
 from ._generated.types import Response
 from .errors import InternetDataError, error_from_response, oauth_error_from
-from .models import Database, Download, to_database, to_download
+from .models import Database, Download, Pkce, to_database, to_download
 
 DEFAULT_BASE_URL = "https://internetdata.io"
 DEFAULT_RETRIES = 2
@@ -32,6 +36,7 @@ OAUTH_METADATA_PATH = "/.well-known/oauth-authorization-server"
 OAUTH_DEVICE_AUTHORIZATION_PATH = "/oauth/device_authorization"
 OAUTH_TOKEN_PATH = "/oauth/token"
 OAUTH_REVOKE_PATH = "/oauth/revoke"
+OAUTH_AUTHORIZE_PATH = "/oauth/authorize"
 DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
 
 # One chunk of a transfer, and therefore the ceiling on what a download of any size
@@ -40,6 +45,20 @@ TRANSFER_CHUNK_BYTES = 1 << 20
 
 _BACKOFF_BASE = 1.0
 
+# The longest wait the sync client's clock can count, about 292 years: past it a lock's
+# wait, `socket.settimeout` and `time.sleep` all raise OverflowError instead.
+WAIT_CEILING = threading.TIMEOUT_MAX
+
+# The longest `Retry-After` waited as given, 2^31 - 1 ms, the bound every SDK takes. One
+# past it is still a throttle, waited out on the backoff: as given, 2147484 held a call
+# for 24.8 days, and 9223372036854775807, 1e400 or a year-9999 date raised a raw
+# OverflowError from the sync client's sleep (measured on 2.6.0, 2026-09-30).
+RETRY_AFTER_CEILING = 2147483.647
+
+# An `expires_in` past this, about 146 billion years, is a deadline nobody reaches. The
+# cap keeps the poll's deadline a float: past 1.8e308 adding it to the clock raises.
+POLL_DEADLINE_CAP = 2**62
+
 T = TypeVar("T")
 
 
@@ -119,8 +138,9 @@ def check_timeout(timeout: float | None) -> float | None:
     Refused where it is SET, because nothing downstream refuses it: zero, a negative
     number, NaN or a string reached the first call and failed it, and every call after,
     as a retried `network` error after three seconds of backoff, or for a string as a
-    `server_error` blaming the API. Infinity is refused too, since the sync client's wait
-    cannot hold it (`OverflowError`); None is the spelling for no bound.
+    `server_error` blaming the API. So is anything past `WAIT_CEILING`, infinity
+    included, since the sync client's wait cannot hold it: 1e300 failed every call with
+    a raw `OverflowError` (2.6.0, measured 2026-09-30). None is the spelling for no bound.
     """
     if timeout is None:
         return None
@@ -129,10 +149,11 @@ def check_timeout(timeout: float | None) -> float | None:
         or not isinstance(timeout, int | float)
         or not math.isfinite(timeout)
         or timeout <= 0
+        or timeout > WAIT_CEILING
     ):
         raise ValueError(
-            f"timeout must be a number of seconds greater than 0, or None for no bound, "
-            f"not {timeout!r}"
+            f"timeout must be a number of seconds greater than 0 and at most "
+            f"{WAIT_CEILING:.0f}, or None for no bound, not {timeout!r}"
         )
     return timeout
 
@@ -337,6 +358,58 @@ async def oauth_request_async(
     return oauth_checked(await exchange_async(http, req, bound))
 
 
+def authorization_url(
+    base_url: str,
+    client_id: str,
+    redirect_uri: str,
+    code_challenge: str,
+    optional: dict[str, str | None],
+) -> str:
+    """The authorization code flow's URL, built with no request: the five parameters every
+    one carries, then `scope`, `state` and `resource` when given and not empty.
+
+    Each value is percent-encoded over UTF-8 with only A-Z a-z 0-9 - . _ ~ left literal, so
+    a space is %20 and never +. A required value that is empty, or has no UTF-8 (a lone
+    surrogate), is refused.
+    """
+    required = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "code_challenge": code_challenge,
+    }
+    for name, value in required.items():
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{name} must be a non-empty string, not {value!r}")
+    params = [
+        ("response_type", "code"),
+        *required.items(),
+        ("code_challenge_method", "S256"),
+        *((name, value) for name, value in optional.items() if value),
+    ]
+    encoded = []
+    for name, value in params:
+        try:
+            encoded.append(f"{name}={quote(value, safe='')}")
+        except UnicodeEncodeError as exc:
+            raise ValueError(f"{name} has no UTF-8 to send: {value!r}") from exc
+    return f"{base_url.rstrip('/')}{OAUTH_AUTHORIZE_PATH}?{'&'.join(encoded)}"
+
+
+def create_pkce() -> Pkce:
+    """A fresh PKCE pair, from 32 bytes of the system's secure random source."""
+    verifier = _base64url(secrets.token_bytes(32))
+    return Pkce(verifier=verifier, challenge=pkce_challenge(verifier))
+
+
+def pkce_challenge(verifier: str) -> str:
+    """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+    return _base64url(hashlib.sha256(verifier.encode("utf-8")).digest())
+
+
+def _base64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
 def oauth_checked(res: httpx.Response) -> httpx.Response:
     """A 2xx as it came, or the failure it describes.
 
@@ -368,7 +441,11 @@ class Clock:
         return time.monotonic()
 
     def sleep(self, seconds: float) -> None:
-        time.sleep(seconds)
+        # In parts, since `time.sleep` raises past WAIT_CEILING rather than waiting.
+        while seconds > 0:
+            part = min(seconds, WAIT_CEILING)
+            time.sleep(part)
+            seconds -= part
 
 
 class AsyncClock:
@@ -456,11 +533,12 @@ def retry_delay(err: InternetDataError, attempt: int, retries: int) -> float | N
 
     A server-supplied `Retry-After` wins over the backoff schedule outright: it is the
     only thing that makes a 429 worth retrying at all, so second-guessing it with a
-    shorter wait would just spend the next attempt on the same rejection.
+    shorter wait would just spend the next attempt on the same rejection. One past
+    `RETRY_AFTER_CEILING` is waited out on the backoff instead.
     """
     if attempt >= retries or not err.retryable:
         return None
-    if err.retry_after_seconds is not None:
+    if err.retry_after_seconds is not None and err.retry_after_seconds <= RETRY_AFTER_CEILING:
         return err.retry_after_seconds
     return _BACKOFF_BASE * (2.0**attempt)
 

{internetdata-2.5.0 → internetdata-2.6.1}/src/internetdata/aio.py

@@ -26,20 +26,24 @@ from ._core import (
     OAUTH_METADATA_PATH,
     OAUTH_REVOKE_PATH,
     OAUTH_TOKEN_PATH,
+    POLL_DEADLINE_CAP,
     TRANSFER_CHUNK_BYTES,
     AsyncClock,
     as_error,
     assert_whole_transfer,
+    authorization_url,
     build_async_transfer_client,
     build_client,
     check_timeout,
     checksums_of,
+    create_pkce,
     databases_of,
     downloads_of,
     oauth_body,
     oauth_request_async,
     parse_body,
     part_file,
+    pkce_challenge,
     redirect_location,
     request_async,
     retry_delay,
@@ -63,6 +67,7 @@ from .models import (
     Download,
     Format,
     OauthMetadata,
+    Pkce,
     TokenResponse,
     to_device_authorization,
     to_metadata,
@@ -99,6 +104,7 @@ class AsyncInternetData:
     ) -> None:
         timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
+        self._base_url = base_url
         self._transfer = build_async_transfer_client(timeout, transport)
         self._retries = retries
         self._timeout = timeout
@@ -381,6 +387,54 @@ class AsyncOauthApi:
         }
         return await self._exchange(form, timeout)
 
+    async def exchange_authorization_code(
+        self,
+        client_id: str,
+        code: str,
+        code_verifier: str,
+        redirect_uri: str,
+        *,
+        timeout: float | None = None,
+    ) -> TokenResponse:
+        """Trade a redirect's code for tokens, once; see `OauthApi.exchange_authorization_code`."""
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": code_verifier,
+        }
+        return await self._exchange(form, timeout)
+
+    def authorization_url(
+        self,
+        client_id: str,
+        redirect_uri: str,
+        code_challenge: str,
+        *,
+        scope: str | None = None,
+        state: str | None = None,
+        resource: str | None = None,
+    ) -> str:
+        """The authorization code flow's URL, made with no request; see
+        `OauthApi.authorization_url`.
+        """
+        return authorization_url(
+            self._owner._base_url,
+            client_id,
+            redirect_uri,
+            code_challenge,
+            {"scope": scope, "state": state, "resource": resource},
+        )
+
+    def create_pkce(self) -> Pkce:
+        """A fresh PKCE pair for one sign-in, from the system's secure random source."""
+        return create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> str:
+        """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+        return pkce_challenge(verifier)
+
     async def revoke(self, client_id: str, token: str, *, timeout: float | None = None) -> None:
         """End a token; revoking the refresh token signs the machine out."""
 
@@ -398,9 +452,14 @@ class AsyncOauthApi:
         # Refused before the first wait, not after it.
         check_timeout(timeout)
         interval = device.interval if device.interval >= 1 else 5
-        deadline = self._clock.now() + device.expires_in
+        # Capped where a deadline stops meaning anything, since the clock is a float and
+        # `expires_in` is the server's integer, of any size.
+        deadline = self._clock.now() + min(device.expires_in, POLL_DEADLINE_CAP)
         while True:
-            await self._clock.sleep(interval)
+            # No wait runs past the deadline: an interval ending after it waits only the
+            # time left, and the expiry follows with nothing sent. In full, an interval of
+            # 2147483647 held a poll with 2 s left for 68 years (2.6.0).
+            await self._clock.sleep(min(interval, max(deadline - self._clock.now(), 0)))
             if self._clock.now() >= deadline:
                 raise OauthExpiredTokenError()
             try:

{internetdata-2.5.0 → internetdata-2.6.1}/src/internetdata/client.py

@@ -21,20 +21,24 @@ from ._core import (
     OAUTH_METADATA_PATH,
     OAUTH_REVOKE_PATH,
     OAUTH_TOKEN_PATH,
+    POLL_DEADLINE_CAP,
     TRANSFER_CHUNK_BYTES,
     Clock,
     as_error,
     assert_whole_transfer,
+    authorization_url,
     build_client,
     build_transfer_client,
     check_timeout,
     checksums_of,
+    create_pkce,
     databases_of,
     downloads_of,
     oauth_body,
     oauth_request,
     parse_body,
     part_file,
+    pkce_challenge,
     redirect_location,
     request,
     retry_delay,
@@ -58,6 +62,7 @@ from .models import (
     Download,
     Format,
     OauthMetadata,
+    Pkce,
     TokenResponse,
     to_device_authorization,
     to_metadata,
@@ -107,6 +112,7 @@ class InternetData:
     ) -> None:
         timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
+        self._base_url = base_url
         self._transfer = build_transfer_client(timeout, transport)
         self._retries = retries
         self._timeout = timeout
@@ -339,7 +345,8 @@ class DatabaseApi:
 
 class OauthApi:
     """Signing a person in with the OAuth device flow, so a program running on their own
-    machine can be handed one of their API keys instead of asking them to paste it.
+    machine can be handed one of their API keys instead of asking them to paste it, or
+    through a browser redirect with the authorization code flow.
 
     No request here carries this client's API key, and none needs one: build the client
     with no key to sign in, then a second one with the key the sign-in hands over. The
@@ -412,6 +419,58 @@ class OauthApi:
         }
         return self._exchange(form, timeout)
 
+    def exchange_authorization_code(
+        self,
+        client_id: str,
+        code: str,
+        code_verifier: str,
+        redirect_uri: str,
+        *,
+        timeout: float | None = None,
+    ) -> TokenResponse:
+        """Trade the `code` a sign-in's redirect brought back for tokens, once: the server
+        spends the code on first read, before it checks `code_verifier`, the PKCE verifier
+        whose challenge went into the authorization URL. `redirect_uri` is that URL's, exactly.
+        """
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": code_verifier,
+        }
+        return self._exchange(form, timeout)
+
+    def authorization_url(
+        self,
+        client_id: str,
+        redirect_uri: str,
+        code_challenge: str,
+        *,
+        scope: str | None = None,
+        state: str | None = None,
+        resource: str | None = None,
+    ) -> str:
+        """The URL to open in the person's browser for the authorization code flow. Makes no
+        request. Once they decide, the server redirects to `redirect_uri` with a `code` for
+        `exchange_authorization_code` (and `state`, when one was given), or with an `error`.
+        """
+        return authorization_url(
+            self._owner._base_url,
+            client_id,
+            redirect_uri,
+            code_challenge,
+            {"scope": scope, "state": state, "resource": resource},
+        )
+
+    def create_pkce(self) -> Pkce:
+        """A fresh PKCE pair for one sign-in, from the system's secure random source."""
+        return create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> str:
+        """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
+        return pkce_challenge(verifier)
+
     def revoke(self, client_id: str, token: str, *, timeout: float | None = None) -> None:
         """End a token. A refresh token ends the whole sign-in and every token it issued, so
         revoking it is how a program signs the machine out."""
@@ -439,9 +498,14 @@ class OauthApi:
         # Refused before the first wait, not after it.
         check_timeout(timeout)
         interval = device.interval if device.interval >= 1 else 5
-        deadline = self._clock.now() + device.expires_in
+        # Capped where a deadline stops meaning anything, since the clock is a float and
+        # `expires_in` is the server's integer, of any size.
+        deadline = self._clock.now() + min(device.expires_in, POLL_DEADLINE_CAP)
         while True:
-            self._clock.sleep(interval)
+            # No wait runs past the deadline: an interval ending after it waits only the
+            # time left, and the expiry follows with nothing sent. In full, an interval of
+            # 2147483647 held a poll with 2 s left for 68 years (2.6.0).
+            self._clock.sleep(min(interval, max(deadline - self._clock.now(), 0)))
             if self._clock.now() >= deadline:
                 raise OauthExpiredTokenError()
             try:

{internetdata-2.5.0 → internetdata-2.6.1}/src/internetdata/models.py

@@ -278,6 +278,17 @@ class DeviceAuthorization:
     verification_uri_complete: str | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class Pkce:
+    """One sign-in's PKCE pair: `challenge` goes in the authorization URL, `verifier` to the
+    code exchange. The verifier is left out of the repr, so logging the pair does not leak it.
+    """
+
+    verifier: str = field(repr=False)
+    challenge: str
+    method: Literal["S256"] = "S256"
+
+
 @dataclass(frozen=True, slots=True)
 class TokenResponse:
     """What a token exchange answers.

{internetdata-2.5.0 → internetdata-2.6.1}/testdata/testdata.json

@@ -1215,6 +1215,72 @@
               5
             ]
           }
+        },
+        {
+          "name": "interval-past-the-deadline-sleeps-only-to-it",
+          "clientId": "internetdata-cli",
+          "device": {
+            "device_code": "mo_dc_poll",
+            "user_code": "BCDF-GHJK",
+            "verification_uri": "https://app.internetdata.io/device",
+            "verification_uri_complete": "https://app.internetdata.io/device?user_code=BCDF-GHJK",
+            "expires_in": 2,
+            "interval": 2147483647
+          },
+          "why": "A sleep that would end past the local deadline ends at it, and the local expiry follows with no request sent: the outcome the full sleep reaches anyway, without asking the runtime for a sleep it may not hold (.NET's Task.Delay throws past ~49.7 days). 2147483647 is the largest interval every SDK's type holds.",
+          "responses": [
+            {
+              "status": 400,
+              "body": {
+                "error": "authorization_pending"
+              }
+            }
+          ],
+          "expect": {
+            "outcome": "expiredToken",
+            "requests": 0,
+            "waits": [
+              2
+            ],
+            "status": null
+          }
+        },
+        {
+          "name": "slow-down-past-the-deadline-sleeps-only-to-it",
+          "clientId": "internetdata-cli",
+          "device": {
+            "device_code": "mo_dc_poll",
+            "user_code": "BCDF-GHJK",
+            "verification_uri": "https://app.internetdata.io/device",
+            "verification_uri_complete": "https://app.internetdata.io/device?user_code=BCDF-GHJK",
+            "expires_in": 8,
+            "interval": 1
+          },
+          "why": "The cut applies to every sleep, a widened one included: 1, then 6 after the first slow_down, then only the 1 s left of the 8 rather than 11.",
+          "responses": [
+            {
+              "status": 400,
+              "body": {
+                "error": "slow_down"
+              }
+            },
+            {
+              "status": 400,
+              "body": {
+                "error": "slow_down"
+              }
+            }
+          ],
+          "expect": {
+            "outcome": "expiredToken",
+            "requests": 2,
+            "waits": [
+              1,
+              6,
+              1
+            ],
+            "status": null
+          }
         }
       ]
     },

{internetdata-2.5.0 → internetdata-2.6.1}/tests/helpers.py

@@ -139,9 +139,26 @@ class OauthAdapter:
     def exchange_refresh_token(self, client_id: str, refresh_token: str, **kwargs: Any) -> Any:
         return self._call("exchange_refresh_token", client_id, refresh_token, **kwargs)
 
+    def exchange_authorization_code(
+        self, client_id: str, code: str, code_verifier: str, redirect_uri: str, **kwargs: Any
+    ) -> Any:
+        return self._call(
+            "exchange_authorization_code", client_id, code, code_verifier, redirect_uri, **kwargs
+        )
+
     def revoke(self, client_id: str, token: str, **kwargs: Any) -> Any:
         return self._call("revoke", client_id, token, **kwargs)
 
+    # These three make no request, so they are plain methods on both clients.
+    def authorization_url(self, *args: Any, **kwargs: Any) -> Any:
+        return self._client.oauth.authorization_url(*args, **kwargs)
+
+    def create_pkce(self) -> Any:
+        return self._client.oauth.create_pkce()
+
+    def pkce_challenge(self, verifier: str) -> Any:
+        return self._client.oauth.pkce_challenge(verifier)
+
     def poll_device_token(self, client_id: str, device: Any, **kwargs: Any) -> Any:
         return self._call("poll_device_token", client_id, device, **kwargs)
 

{internetdata-2.5.0 → internetdata-2.6.1}/tests/test_client.py

@@ -357,6 +357,34 @@ def test_a_rate_limit_is_retried_and_honors_retry_after(make_client: ClientFacto
     assert len(stub.requests) == 3
 
 
+@pytest.mark.parametrize(
+    "retry_after", ["2147484", "9223372036854775807", "1e400", "Fri, 31 Dec 9999 23:59:59 GMT"]
+)
+def test_a_retry_after_past_the_ceiling_waits_the_backoff_and_stays_a_throttle(
+    make_client: ClientFactory, monkeypatch: pytest.MonkeyPatch, retry_after: str
+) -> None:
+    """As given, 2147484 held the call for 24.8 days, and the rest raised a raw
+    OverflowError from the sync client's sleep."""
+    monkeypatch.setattr(_core, "_BACKOFF_BASE", 0.0)
+    headers = {"Retry-After": retry_after}
+    stub = Stub({LIST_PATH: {"status": 429, "body": {"rc": "RATE_LIMITED"}, "headers": headers}})
+    client = make_client(transport=stub.transport, retries=1)
+
+    outcome = settle(client.database.list, within=5.0)
+
+    assert isinstance(outcome, InternetDataError), f"settled with {outcome!r}"
+    assert outcome.kind == "rate_limited"
+    assert len(stub.requests) == 2
+
+
+def test_a_retry_after_is_waited_as_given_up_to_the_ceiling() -> None:
+    def throttled(seconds: float) -> InternetDataError:
+        return InternetDataError("rate_limited", "RATE_LIMITED", 429, seconds)
+
+    assert _core.retry_delay(throttled(2147483.647), 0, 1) == 2147483.647
+    assert _core.retry_delay(throttled(2147483.648), 0, 1) == _core._BACKOFF_BASE
+
+
 def test_a_transport_failure_surfaces_as_a_network_error() -> None:
     def refuse(request: httpx.Request) -> httpx.Response:
         raise httpx.ConnectError("connection refused", request=request)
@@ -441,7 +469,7 @@ def test_a_per_call_timeout_bounds_a_trickling_body_and_leaves_the_clients_own_a
     _assert_bounded_by(default, CLIENT_TIMEOUT)
 
 
-@pytest.mark.parametrize("timeout", [0, -1, float("nan"), float("inf"), "30", True])
+@pytest.mark.parametrize("timeout", [0, -1, float("nan"), float("inf"), 1e300, "30", True])
 @pytest.mark.parametrize("call", PER_CALL)
 def test_a_per_call_timeout_no_attempt_can_meet_is_refused_before_any_request(
     make_client: ClientFactory, call: str, timeout: Any
@@ -494,7 +522,9 @@ def test_the_default_timeout_is_thirty_seconds() -> None:
 
 
 @pytest.mark.parametrize("client", [InternetData, AsyncInternetData])
-@pytest.mark.parametrize("timeout", [0, -1, 0.0, float("nan"), float("inf"), "30", True])
+@pytest.mark.parametrize(
+    "timeout", [0, -1, 0.0, float("nan"), float("inf"), 9223372037, 1e300, "30", True]
+)
 def test_a_timeout_no_attempt_can_meet_is_refused_when_the_client_is_built(
     client: type[InternetData | AsyncInternetData], timeout: Any
 ) -> None:
@@ -503,7 +533,7 @@ def test_a_timeout_no_attempt_can_meet_is_refused_when_the_client_is_built(
         client(API_KEY, timeout=timeout)
 
 
-@pytest.mark.parametrize("timeout", [None, 0.25, 1, 30])
+@pytest.mark.parametrize("timeout", [None, 0.25, 1, 30, 9223372036])
 def test_a_usable_timeout_builds_a_client(timeout: float | None) -> None:
     InternetData(API_KEY, timeout=timeout).close()
     asyncio.run(AsyncInternetData(API_KEY, timeout=timeout).aclose())

{internetdata-2.5.0 → internetdata-2.6.1}/tests/test_download.py

@@ -326,6 +326,32 @@ def test_a_storage_5xx_before_the_body_is_retried(
     assert outcome == SMALL
 
 
+@pytest.mark.parametrize("retry_after", ["2147484", "9223372036854775807"])
+def test_a_storage_retry_after_past_the_ceiling_waits_the_backoff(
+    make_client: ClientFactory, monkeypatch: pytest.MonkeyPatch, retry_after: str
+) -> None:
+    """Object storage's 429 is bounded like the API's: as given, one held the transfer for
+    24.8 days, and the other raised a raw OverflowError from the sync client's sleep."""
+    monkeypatch.setattr(_core, "_BACKOFF_BASE", 0.0)
+    requests: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == DOWNLOAD_PATH:
+            return httpx.Response(302, headers={"Location": BLOB})
+        return httpx.Response(429, headers={"Retry-After": retry_after})
+
+    client = make_client(
+        api_key=API_KEY, base_url=API, transport=httpx.MockTransport(handle), retries=1
+    )
+
+    outcome = settle(lambda: client.database.download_bytes("bogon_ip_v1", "csvgz"), within=5.0)
+
+    assert [r.url.path for r in requests].count("/blob") == 2, "storage's 429 and its retry"
+    assert isinstance(outcome, InternetDataError), f"settled with {outcome!r}"
+    assert outcome.kind == "rate_limited"
+
+
 @pytest.mark.parametrize("method", ["download", "download_bytes"])
 def test_a_transfer_that_dies_part_way_is_not_fetched_again(
     make_client: ClientFactory, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, method: str

{internetdata-2.5.0 → internetdata-2.6.1}/tests/test_oauth.py

@@ -1,6 +1,6 @@
 """The `oauth` accessor against the shared corpus's oauth section, on both clients.
 
-Nothing here reads `oauth.deferred`: those operations are not in this release. Every call
+The authorization code flow's vectors, under `oauth.deferred`, are read here too. Every call
 under test runs through `settle`, so a loop that never ends fails its test instead of
 hanging the suite.
 """
@@ -8,6 +8,7 @@ hanging the suite.
 from __future__ import annotations
 
 import asyncio
+import re
 import time
 import urllib.parse
 from collections.abc import Iterator
@@ -82,7 +83,9 @@ def test_no_oauth_request_carries_the_api_key(make_client: ClientFactory) -> Non
     outcome = settle(lambda: _every_operation(client.oauth), bound)
 
     assert outcome is None, f"settled with {outcome!r}"
-    assert len(stub.requests) == 6
+    assert len(stub.requests) == 7
+    url = client.oauth.authorization_url("internetdata-cli", "http://127.0.0.1/cb", "c" * 43)
+    assert key not in url, "the authorization URL carried the API key"
     for req in stub.requests:
         label = f"{req.method} {req.url.path}"
         for name in case["forbiddenHeaders"]:
@@ -98,7 +101,9 @@ def test_no_oauth_request_carries_the_api_key(make_client: ClientFactory) -> Non
     assert stub.requests[-1].headers["authorization"] == f"Bearer {key}"
 
 
-@pytest.mark.parametrize("case", CORPUS["forms"]["cases"], ids=lambda case: case["name"])
+@pytest.mark.parametrize(
+    "case", CORPUS["forms"]["cases"] + CORPUS["deferred"]["forms"], ids=lambda case: case["name"]
+)
 def test_each_operation_requests_its_endpoint_with_exactly_its_form_fields(
     make_client: ClientFactory, case: dict[str, Any]
 ) -> None:
@@ -244,7 +249,11 @@ def test_a_failed_answer_is_an_oauth_refusal_only_when_it_is_one(
     _assert_outcome(outcome, case["expect"], case["name"])
 
 
-@pytest.mark.parametrize("case", CORPUS["retries"]["cases"], ids=lambda case: case["name"])
+@pytest.mark.parametrize(
+    "case",
+    CORPUS["retries"]["cases"] + CORPUS["deferred"]["retries"],
+    ids=lambda case: case["name"],
+)
 def test_only_what_consumes_nothing_is_retried(
     make_client: ClientFactory, case: dict[str, Any]
 ) -> None:
@@ -296,6 +305,92 @@ def test_poll_device_token_waits_widens_and_ends_as_the_corpus_says(
     _assert_outcome(outcome, {**expect, "type": expect["outcome"]}, case["name"])
 
 
+def test_the_poll_sleeps_the_fraction_left_before_its_deadline(make_client: ClientFactory) -> None:
+    """On the real clock, which the corpus's seam replaces. The second wait is the ~0.99 s
+    left, so the deadline passes with one request sent; a sleep that dropped the fraction
+    would poll again at once, and this stub approves that second poll."""
+    bound = LoopBound()
+    replies = [
+        {"status": 400, "body": {"error": "authorization_pending"}},
+        {"status": 200, "body": EVERY_REQUIRED_MEMBER},
+    ]
+    stub = OauthStub(replies, bound, limit=2)
+    client = make_client(base_url=BASE_URL, transport=stub.transport)
+    device = DeviceAuthorization(
+        device_code="mo_dc_x",
+        user_code="BCDF-GHJK",
+        verification_uri="https://app.example.test/device",
+        expires_in=2,
+        interval=1,
+    )
+
+    outcome = settle(lambda: client.oauth.poll_device_token("internetdata-cli", device), bound)
+
+    assert isinstance(outcome, OauthExpiredTokenError), f"settled with {outcome!r}"
+    assert outcome.status is None, "the local deadline, not the server's"
+    assert len(stub.requests) == 1
+
+
+def test_the_real_clock_sleeps_past_what_time_sleep_can_count_in_parts(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """`time.sleep` raises OverflowError past WAIT_CEILING, and a poll's wait is the server's
+    `interval` or `expires_in`, of any size."""
+    waits: list[float] = []
+    monkeypatch.setattr(time, "sleep", waits.append)
+
+    _core.Clock().sleep(_core.WAIT_CEILING * 2.5)
+
+    assert waits == [_core.WAIT_CEILING, _core.WAIT_CEILING, _core.WAIT_CEILING / 2]
+
+
+def test_a_poll_whose_request_outlives_the_deadline_waits_nothing_more(
+    make_client: ClientFactory,
+) -> None:
+    """The request itself takes the clock 10 s past the deadline, so the time left is
+    negative, and `time.sleep` raises ValueError for a negative wait."""
+    bound = LoopBound()
+    clock = FakeClock(bound)
+    stub = OauthStub([{"status": 400, "body": {"error": "authorization_pending"}}], bound, limit=1)
+
+    def slow(request: httpx.Request) -> httpx.Response:
+        clock._elapsed += 10
+        return stub._handle(request)
+
+    client = make_client(base_url=BASE_URL, transport=httpx.MockTransport(slow))
+    client.oauth.use_clock(clock)
+    device = DeviceAuthorization(**{**_device_fields(), "expires_in": 5, "interval": 1})
+
+    outcome = settle(lambda: client.oauth.poll_device_token("internetdata-cli", device), bound)
+
+    assert isinstance(outcome, OauthExpiredTokenError), f"settled with {outcome!r}"
+    assert clock.waits == [1, 0]
+
+
+def test_an_expires_in_past_any_float_still_polls(make_client: ClientFactory) -> None:
+    """The server's integer, of any size: added to the clock whole, 10**400 raised a raw
+    OverflowError before the first wait."""
+    bound = LoopBound()
+    stub = OauthStub([{"status": 200, "body": EVERY_REQUIRED_MEMBER}], bound, limit=1)
+    client = make_client(base_url=BASE_URL, transport=stub.transport)
+    clock = FakeClock(bound)
+    client.oauth.use_clock(clock)
+    device = DeviceAuthorization(**{**_device_fields(), "expires_in": 10**400, "interval": 1})
+
+    outcome = settle(lambda: client.oauth.poll_device_token("internetdata-cli", device), bound)
+
+    assert isinstance(outcome, TokenResponse), f"settled with {outcome!r}"
+    assert clock.waits == [1]
+
+
+def _device_fields() -> dict[str, Any]:
+    return {
+        "device_code": "mo_dc_x",
+        "user_code": "BCDF-GHJK",
+        "verification_uri": "https://app.example.test/device",
+    }
+
+
 def test_cancelling_a_poll_during_its_first_wait_ends_it_at_once() -> None:
     bound = LoopBound()
     stub = OauthStub([{"status": 400, "body": {"error": "authorization_pending"}}], bound, limit=1)
@@ -319,11 +414,68 @@ def test_cancelling_a_poll_during_its_first_wait_ends_it_at_once() -> None:
     assert stub.requests == [], "no request after the cancel"
 
 
+@pytest.mark.parametrize(
+    "case", CORPUS["deferred"]["authorizationUrl"], ids=lambda case: case["name"]
+)
+def test_an_authorization_url_is_built_exactly_as_the_corpus_spells_it(
+    make_client: ClientFactory, case: dict[str, Any]
+) -> None:
+    stub = OauthStub([{"status": 200, "body": EVERY_REQUIRED_MEMBER}], LoopBound())
+    client = make_client(base_url=case["baseUrl"], transport=stub.transport)
+
+    url = client.oauth.authorization_url(
+        case["clientId"],
+        case["redirectUri"],
+        case["codeChallenge"],
+        scope=case.get("scope"),
+        state=case.get("state"),
+        resource=case.get("resource"),
+    )
+
+    assert url == case["expect"]
+    assert stub.requests == [], "requests sent"
+
+
+def test_an_authorization_url_leaves_out_an_empty_option_and_refuses_an_empty_value(
+    make_client: ClientFactory,
+) -> None:
+    case = CORPUS["deferred"]["authorizationUrl"][0]
+    oauth = make_client(base_url=BASE_URL).oauth
+    args = (case["clientId"], case["redirectUri"], case["codeChallenge"])
+
+    url = oauth.authorization_url(*args, scope="", state="", resource="")
+
+    assert url == case["expect"].replace(case["baseUrl"], BASE_URL)
+    with pytest.raises(ValueError, match="client_id"):
+        oauth.authorization_url("", case["redirectUri"], case["codeChallenge"])
+    with pytest.raises(ValueError, match="code_challenge"):
+        oauth.authorization_url(case["clientId"], case["redirectUri"], "\ud800")
+
+
+def test_a_pkce_pair_is_fresh_and_its_challenge_is_the_s256_one(
+    make_client: ClientFactory,
+) -> None:
+    pkce = CORPUS["deferred"]["pkce"]
+    oauth = make_client().oauth
+
+    first = oauth.create_pkce()
+
+    assert oauth.pkce_challenge(pkce["verifier"]) == pkce["challenge"]
+    assert re.fullmatch(pkce["generatedVerifierPattern"], first.verifier)
+    assert first.challenge == oauth.pkce_challenge(first.verifier)
+    assert first.method == pkce["method"]
+    assert oauth.create_pkce().verifier != first.verifier, "two pairs share a verifier"
+    assert first.verifier not in repr(first)
+
+
 def _every_operation(oauth: OauthAdapter) -> None:
     oauth.metadata()
     oauth.device_authorization("internetdata-cli", scope="account.read")
     oauth.exchange_device_code("internetdata-cli", "mo_dc_x")
     oauth.exchange_refresh_token("internetdata-cli", "mo_rt_x")
+    oauth.exchange_authorization_code(
+        "internetdata-cli", "mo_ac_x", "v" * 43, "http://127.0.0.1/cb"
+    )
     oauth.revoke("internetdata-cli", "mo_rt_x")
     oauth.poll_device_token("internetdata-cli", DEVICE)
 
@@ -348,6 +500,10 @@ def _call(oauth: OauthAdapter, operation: str, args: dict[str, str]) -> Any:
         return oauth.exchange_device_code(args["clientId"], args["deviceCode"])
     if operation == "exchangeRefreshToken":
         return oauth.exchange_refresh_token(args["clientId"], args["refreshToken"])
+    if operation == "exchangeAuthorizationCode":
+        return oauth.exchange_authorization_code(
+            args["clientId"], args["code"], args["codeVerifier"], args["redirectUri"]
+        )
     if operation == "revoke":
         return oauth.revoke(args["clientId"], args["token"])
     raise AssertionError(f"the corpus names an operation this suite does not know: {operation}")