internetdata 2.1.0__tar.gz → 2.3.0__tar.gz

{internetdata-2.1.0 → internetdata-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.1.0
+Version: 2.3.0
 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
@@ -72,7 +72,7 @@ with InternetData(api_key) as client:
 
 ### The catalog
 
-`list` answers database FAMILIES. A licence is held against a family, while a download names a specific version, so the ids the other calls take come from each family's `versions`:
+`list` answers database FAMILIES. A license is held against a family, while a download names a specific version, so the ids the other calls take come from each family's `versions`:
 
 ```python
 for family in client.database.list():
@@ -82,7 +82,9 @@ for family in client.database.list():
         print(version.id, version.formats)   # 'bogon_ip_v1' ('csvgz', 'mmdb')
 ```
 
-`standing` is `licensed`, `expired` or `unlicensed`, and `license_type` is what your licence lets you do with the data (`evaluation`, `standard`, `redistribute`, or `None` when there is no licence). A family you have never bought is still listed, as `unlicensed`, so you can see what else exists.
+`standing` is `licensed`, `expired` or `unlicensed`, and `license_type` is what your license lets you do with the data (`evaluation`, `standard`, `redistribute`, or `None` when there is no license). A family you have never bought is still listed, as `unlicensed`, so you can see what else exists.
+
+A rolling license also carries `renews_at`, when it next renews, and `notice_due_at`, the last day you can give notice of non-renewal for that term. Both are `None` when there is no license, when it has no defined term, or when `expires` sets a hard stop instead. `DATABASE_FORMATS`, `STANDINGS` and `LICENSE_TYPES` hold the published values at runtime, for checking one that came from a flag or a form before you make a call.
 
 ### What is inside a build
 
@@ -165,14 +167,19 @@ except InternetDataError as err:
 
 `kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`. `message` is the API's own result code, passed through as it was sent, so you can switch on `NOT_LICENSED` against `LICENSE_EXPIRED` without reading the status.
 
-A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound:
+A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound. Anything else that is not a number greater than 0 raises `ValueError` where it is set:
 
 ```python
 client = InternetData(api_key, timeout=10)
+catalog = client.database.list(timeout=2)
 ```
 
+From 2.3.0, `list`, `metadata`, `checksums`, `downloads` and `download_url` each take a keyword-only `timeout` in seconds, bounding each attempt at that one call in place of the client's; `None` there means the client's own rather than no bound. `download` and `download_bytes` deliberately take none and raise `TypeError` if handed one, rather than accepting it and quietly doing nothing: a transfer runs to gigabytes and minutes, so any bound that suits a JSON call would abandon a healthy download. `download_url` does take one, because minting the link is an ordinary API request - it bounds that request, not whatever you do with the link afterwards.
+
 **Changed in 2.1.0:** the default was 10 seconds, and it bounded each read of a response rather than the whole attempt, so a response trickling in slowly could run past it for as long as the server kept sending.
 
+**Changed in 2.2.0:** a timeout of 0 or less, NaN or a string used to be accepted, and failed every call.
+
 Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a traffic burst, and retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, and server and network failures, but never a spent quota or anything else you sent.
 
 ## Other Libraries

{internetdata-2.1.0 → internetdata-2.3.0}/README.md

@@ -38,7 +38,7 @@ with InternetData(api_key) as client:
 
 ### The catalog
 
-`list` answers database FAMILIES. A licence is held against a family, while a download names a specific version, so the ids the other calls take come from each family's `versions`:
+`list` answers database FAMILIES. A license is held against a family, while a download names a specific version, so the ids the other calls take come from each family's `versions`:
 
 ```python
 for family in client.database.list():
@@ -48,7 +48,9 @@ for family in client.database.list():
         print(version.id, version.formats)   # 'bogon_ip_v1' ('csvgz', 'mmdb')
 ```
 
-`standing` is `licensed`, `expired` or `unlicensed`, and `license_type` is what your licence lets you do with the data (`evaluation`, `standard`, `redistribute`, or `None` when there is no licence). A family you have never bought is still listed, as `unlicensed`, so you can see what else exists.
+`standing` is `licensed`, `expired` or `unlicensed`, and `license_type` is what your license lets you do with the data (`evaluation`, `standard`, `redistribute`, or `None` when there is no license). A family you have never bought is still listed, as `unlicensed`, so you can see what else exists.
+
+A rolling license also carries `renews_at`, when it next renews, and `notice_due_at`, the last day you can give notice of non-renewal for that term. Both are `None` when there is no license, when it has no defined term, or when `expires` sets a hard stop instead. `DATABASE_FORMATS`, `STANDINGS` and `LICENSE_TYPES` hold the published values at runtime, for checking one that came from a flag or a form before you make a call.
 
 ### What is inside a build
 
@@ -131,14 +133,19 @@ except InternetDataError as err:
 
 `kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`. `message` is the API's own result code, passed through as it was sent, so you can switch on `NOT_LICENSED` against `LICENSE_EXPIRED` without reading the status.
 
-A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound:
+A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound. Anything else that is not a number greater than 0 raises `ValueError` where it is set:
 
 ```python
 client = InternetData(api_key, timeout=10)
+catalog = client.database.list(timeout=2)
 ```
 
+From 2.3.0, `list`, `metadata`, `checksums`, `downloads` and `download_url` each take a keyword-only `timeout` in seconds, bounding each attempt at that one call in place of the client's; `None` there means the client's own rather than no bound. `download` and `download_bytes` deliberately take none and raise `TypeError` if handed one, rather than accepting it and quietly doing nothing: a transfer runs to gigabytes and minutes, so any bound that suits a JSON call would abandon a healthy download. `download_url` does take one, because minting the link is an ordinary API request - it bounds that request, not whatever you do with the link afterwards.
+
 **Changed in 2.1.0:** the default was 10 seconds, and it bounded each read of a response rather than the whole attempt, so a response trickling in slowly could run past it for as long as the server kept sending.
 
+**Changed in 2.2.0:** a timeout of 0 or less, NaN or a string used to be accepted, and failed every call.
+
 Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a traffic burst, and retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, and server and network failures, but never a spent quota or anything else you sent.
 
 ## Other Libraries

{internetdata-2.1.0 → internetdata-2.3.0}/src/internetdata/__init__.py

@@ -15,6 +15,9 @@ from .aio import AsyncDatabaseApi, AsyncInternetData
 from .client import DatabaseApi, InternetData
 from .errors import ErrorKind, InternetDataError
 from .models import (
+    DATABASE_FORMATS,
+    LICENSE_TYPES,
+    STANDINGS,
     Database,
     DatabaseMetadata,
     DatabaseVersion,
@@ -26,10 +29,13 @@ from .models import (
     Standing,
 )
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 __all__ = [
+    "DATABASE_FORMATS",
     "DEFAULT_BASE_URL",
+    "LICENSE_TYPES",
+    "STANDINGS",
     "AsyncDatabaseApi",
     "AsyncInternetData",
     "Database",

{internetdata-2.1.0 → internetdata-2.3.0}/src/internetdata/_core.py

@@ -7,6 +7,7 @@ import asyncio
 import contextlib
 import contextvars
 import json
+import math
 import os
 import threading
 from collections.abc import Awaitable, Callable, Iterator
@@ -105,6 +106,30 @@ def build_async_transfer_client(
     )
 
 
+def check_timeout(timeout: float | None) -> float | None:
+    """`timeout`, once it is a bound an attempt can meet.
+
+    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.
+    """
+    if timeout is None:
+        return None
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, int | float)
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ValueError(
+            f"timeout must be a number of seconds greater than 0, or None for no bound, "
+            f"not {timeout!r}"
+        )
+    return timeout
+
+
 def storage_refusal(res: httpx.Response) -> InternetDataError:
     """What object storage refusing a download link becomes.
 

{internetdata-2.1.0 → internetdata-2.3.0}/src/internetdata/aio.py

@@ -26,6 +26,7 @@ from ._core import (
     assert_whole_transfer,
     build_async_transfer_client,
     build_client,
+    check_timeout,
     checksums_of,
     databases_of,
     downloads_of,
@@ -73,6 +74,7 @@ class AsyncInternetData:
         timeout: float | None = DEFAULT_TIMEOUT,
         transport: httpx.AsyncBaseTransport | None = None,
     ) -> None:
+        timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
         self._transfer = build_async_transfer_client(timeout, transport)
         self._retries = retries
@@ -94,6 +96,10 @@ class AsyncInternetData:
     ) -> None:
         await self.aclose()
 
+    # A per-call timeout, checked, or the client's own when the call gave none.
+    def _bound(self, timeout: float | None) -> float | None:
+        return self._timeout if timeout is None else check_timeout(timeout)
+
     async def _retrying(self, call: Callable[[], Awaitable[T]], retries: int) -> T:
         attempt = 0
         while True:
@@ -113,12 +119,17 @@ class AsyncDatabaseApi:
 
     `list` is a method here, which shadows the builtin for everything else in the class
     body, so the return annotations name `builtins.list` explicitly.
+
+    Every call here that asks the API a question takes `timeout`, in seconds, bounding
+    each ATTEMPT of that call alone and overriding the client's. The two transfers take
+    none and refuse one rather than ignoring it: a database runs to gigabytes and minutes,
+    so any bound that suits a JSON call would abandon a healthy download.
     """
 
     def __init__(self, owner: AsyncInternetData) -> None:
         self._owner = owner
 
-    async def list(self) -> builtins.list[Database]:
+    async def list(self, *, timeout: float | None = None) -> builtins.list[Database]:
         """The published catalog as YOUR organization may see it.
 
         Every family carries a `standing`, so one you have never bought is listed as
@@ -126,33 +137,43 @@ class AsyncDatabaseApi:
         single customer, which is absent entirely for everyone else. Nothing is cached
         and nothing is reconstructed here - what you get is what the server sent for the
         key you are holding.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
         """
 
         async def call() -> builtins.list[Database]:
-            res = await request_async(list_databases, self._client, self._owner._timeout)
+            res = await request_async(list_databases, self._client, self._bound(timeout))
             return parse_body(unwrap(res), databases_of)
 
         return await self._retrying(call)
 
-    async def metadata(self, database_id: str) -> DatabaseMetadata:
-        """What is inside one database: freshness, row count, columns, samples and sizes."""
+    async def metadata(self, database_id: str, *, timeout: float | None = None) -> DatabaseMetadata:
+        """What is inside one database: freshness, row count, columns, samples and sizes.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
+        """
 
         async def call() -> DatabaseMetadata:
             res = await request_async(
-                database_metadata_v2, self._client, self._owner._timeout, id=database_id
+                database_metadata_v2, self._client, self._bound(timeout), id=database_id
             )
             return parse_body(unwrap(res), to_metadata)
 
         return await self._retrying(call)
 
-    async def checksums(self, database_id: str, format: Format) -> dict[str, str]:
-        """Every checksum published for one database file, keyed by algorithm."""
+    async def checksums(
+        self, database_id: str, format: Format, *, timeout: float | None = None
+    ) -> dict[str, str]:
+        """Every checksum published for one database file, keyed by algorithm.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
+        """
 
         async def call() -> dict[str, str]:
             res = await request_async(
                 database_checksum_v2,
                 self._client,
-                self._owner._timeout,
+                self._bound(timeout),
                 id=database_id,
                 format_=DatabaseFormat(format),
             )
@@ -160,18 +181,25 @@ class AsyncDatabaseApi:
 
         return await self._retrying(call)
 
-    async def downloads(self, limit: int = DEFAULT_DOWNLOADS_LIMIT) -> builtins.list[Download]:
-        """Your organization's recent download attempts, newest first."""
+    async def downloads(
+        self, limit: int = DEFAULT_DOWNLOADS_LIMIT, *, timeout: float | None = None
+    ) -> builtins.list[Download]:
+        """Your organization's recent download attempts, newest first.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
+        """
 
         async def call() -> builtins.list[Download]:
             res = await request_async(
-                list_downloads, self._client, self._owner._timeout, limit=limit
+                list_downloads, self._client, self._bound(timeout), limit=limit
             )
             return parse_body(unwrap(res), downloads_of)
 
         return await self._retrying(call)
 
-    async def download_url(self, database_id: str, format: Format) -> str:
+    async def download_url(
+        self, database_id: str, format: Format, *, timeout: float | None = None
+    ) -> str:
         """The time-limited URL for one database file.
 
         The API answers `302` to object storage, and the link carries its own signature,
@@ -179,13 +207,16 @@ class AsyncDatabaseApi:
         rather than followed so the caller decides how to move a file that reaches
         gigabytes; the link authorizes the START of a transfer, so one already running is
         not interrupted when it lapses.
+
+        `timeout` bounds each attempt at MINTING the link, which is an ordinary API
+        request, and says nothing about the transfer you then run with it.
         """
 
         async def call() -> str:
             res = await request_async(
                 download_database_v2,
                 self._client,
-                self._owner._timeout,
+                self._bound(timeout),
                 id=database_id,
                 format_=DatabaseFormat(format),
             )
@@ -264,5 +295,8 @@ class AsyncDatabaseApi:
     def _client(self) -> AuthenticatedClient:
         return self._owner._client
 
+    def _bound(self, timeout: float | None) -> float | None:
+        return self._owner._bound(timeout)
+
     async def _retrying(self, call: Callable[[], Awaitable[T]]) -> T:
         return await self._owner._retrying(call, self._owner._retries)

{internetdata-2.1.0 → internetdata-2.3.0}/src/internetdata/client.py

@@ -21,6 +21,7 @@ from ._core import (
     assert_whole_transfer,
     build_client,
     build_transfer_client,
+    check_timeout,
     checksums_of,
     databases_of,
     downloads_of,
@@ -55,12 +56,15 @@ class InternetData:
     Every database published today is licensed, so create a key carrying the
     `db.download` scope in the console and pass it in. The argument is optional
     nonetheless, and an absent or empty one sends no `Authorization` header at all
-    rather than an empty one: what this API serves without a licence is a product
+    rather than an empty one: what this API serves without a license is a product
     decision, not the client's to refuse.
 
     `timeout` is how long one attempt at a request may take, in seconds, body included, so a
     call that is retried can take longer in total; None means no bound, and a database
-    transfer is exempt.
+    transfer is exempt. Every `database` call but the two transfers also takes `timeout`,
+    which overrides the client's for that call alone. Anything else that is not a finite
+    number greater than 0 is a `ValueError` where it is set, rather than a failure of every
+    call.
 
     Holds an HTTP connection pool, so use it as a context manager or call `close()` when
     you are done with it.
@@ -78,6 +82,7 @@ class InternetData:
         timeout: float | None = DEFAULT_TIMEOUT,
         transport: httpx.BaseTransport | None = None,
     ) -> None:
+        timeout = check_timeout(timeout)
         self._client = build_client(api_key, base_url, timeout, transport)
         self._transfer = build_transfer_client(timeout, transport)
         self._retries = retries
@@ -99,6 +104,10 @@ class InternetData:
     ) -> None:
         self.close()
 
+    # A per-call timeout, checked, or the client's own when the call gave none.
+    def _bound(self, timeout: float | None) -> float | None:
+        return self._timeout if timeout is None else check_timeout(timeout)
+
     def _retrying(self, call: Callable[[], T], retries: int) -> T:
         attempt = 0
         while True:
@@ -118,12 +127,17 @@ class DatabaseApi:
 
     `list` is a method here, which shadows the builtin for everything else in the class
     body, so the return annotations name `builtins.list` explicitly.
+
+    Every call here that asks the API a question takes `timeout`, in seconds, bounding
+    each ATTEMPT of that call alone and overriding the client's. The two transfers take
+    none and refuse one rather than ignoring it: a database runs to gigabytes and minutes,
+    so any bound that suits a JSON call would abandon a healthy download.
     """
 
     def __init__(self, owner: InternetData) -> None:
         self._owner = owner
 
-    def list(self) -> builtins.list[Database]:
+    def list(self, *, timeout: float | None = None) -> builtins.list[Database]:
         """The published catalog as YOUR organization may see it.
 
         Every family carries a `standing`, so one you have never bought is listed as
@@ -133,41 +147,49 @@ class DatabaseApi:
         customer. Nothing is cached and nothing is reconstructed here - what you get is
         what the server sent for the key you are holding.
 
-        A licence covers a FAMILY, while a download names a version, so the ids for the
+        A license covers a FAMILY, while a download names a version, so the ids for the
         other calls come from each entry's `versions`.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
         """
 
         def call() -> builtins.list[Database]:
-            res = request(list_databases, self._client, self._owner._timeout)
+            res = request(list_databases, self._client, self._bound(timeout))
             return parse_body(unwrap(res), databases_of)
 
         return self._retrying(call)
 
-    def metadata(self, database_id: str) -> DatabaseMetadata:
+    def metadata(self, database_id: str, *, timeout: float | None = None) -> DatabaseMetadata:
         """What is inside one database: freshness, row count, columns, samples and sizes.
 
         Cheap enough to poll: it answers `updated` and `entries` without moving the
         build. `size` is the number to budget a transfer against before starting one.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
         """
 
         def call() -> DatabaseMetadata:
-            res = request(database_metadata_v2, self._client, self._owner._timeout, id=database_id)
+            res = request(database_metadata_v2, self._client, self._bound(timeout), id=database_id)
             return parse_body(unwrap(res), to_metadata)
 
         return self._retrying(call)
 
-    def checksums(self, database_id: str, format: Format) -> dict[str, str]:
+    def checksums(
+        self, database_id: str, format: Format, *, timeout: float | None = None
+    ) -> dict[str, str]:
         """Every checksum published for one database file, keyed by algorithm.
 
         Keyed rather than one digest because the API publishes md5, sha1, sha256 and
         sha512 side by side and which of them you want is your verifier's business.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
         """
 
         def call() -> dict[str, str]:
             res = request(
                 database_checksum_v2,
                 self._client,
-                self._owner._timeout,
+                self._bound(timeout),
                 id=database_id,
                 format_=DatabaseFormat(format),
             )
@@ -175,20 +197,26 @@ class DatabaseApi:
 
         return self._retrying(call)
 
-    def downloads(self, limit: int = DEFAULT_DOWNLOADS_LIMIT) -> builtins.list[Download]:
+    def downloads(
+        self, limit: int = DEFAULT_DOWNLOADS_LIMIT, *, timeout: float | None = None
+    ) -> builtins.list[Download]:
         """Your organization's recent download attempts, newest first.
 
         Refusals are listed too: a denial is what answers "it stopped working", and its
         absence answers nothing.
+
+        `timeout` bounds each attempt at this call alone, in place of the client's.
         """
 
         def call() -> builtins.list[Download]:
-            res = request(list_downloads, self._client, self._owner._timeout, limit=limit)
+            res = request(list_downloads, self._client, self._bound(timeout), limit=limit)
             return parse_body(unwrap(res), downloads_of)
 
         return self._retrying(call)
 
-    def download_url(self, database_id: str, format: Format) -> str:
+    def download_url(
+        self, database_id: str, format: Format, *, timeout: float | None = None
+    ) -> str:
         """The time-limited URL for one database file.
 
         The API answers `302` to object storage, and the link carries its own signature,
@@ -196,13 +224,16 @@ class DatabaseApi:
         rather than followed so the caller decides how to move a file that reaches
         gigabytes; the link authorizes the START of a transfer, so one already running is
         not interrupted when it lapses.
+
+        `timeout` bounds each attempt at MINTING the link, which is an ordinary API
+        request, and says nothing about the transfer you then run with it.
         """
 
         def call() -> str:
             res = request(
                 download_database_v2,
                 self._client,
-                self._owner._timeout,
+                self._bound(timeout),
                 id=database_id,
                 format_=DatabaseFormat(format),
             )
@@ -276,5 +307,8 @@ class DatabaseApi:
     def _client(self) -> AuthenticatedClient:
         return self._owner._client
 
+    def _bound(self, timeout: float | None) -> float | None:
+        return self._owner._bound(timeout)
+
     def _retrying(self, call: Callable[[], T]) -> T:
         return self._owner._retrying(call, self._owner._retries)

{internetdata-2.1.0 → internetdata-2.3.0}/src/internetdata/models.py

@@ -11,9 +11,12 @@ from __future__ import annotations
 
 import datetime
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any, Literal, get_args
 
 __all__ = [
+    "DATABASE_FORMATS",
+    "LICENSE_TYPES",
+    "STANDINGS",
     "Database",
     "DatabaseMetadata",
     "DatabaseVersion",
@@ -37,7 +40,20 @@ Standing = Literal["licensed", "expired", "unlicensed"]
 """Where your organization stands with one database family."""
 
 LicenseType = Literal["evaluation", "standard", "redistribute"]
-"""What a licence permits you to do with the data. `None` when there is no licence."""
+"""What a license permits you to do with the data. `None` when there is no license."""
+
+DATABASE_FORMATS: tuple[Format, ...] = get_args(Format)
+"""Every `Format`, at runtime.
+
+A `Literal` is erased to nothing a program can check against, so a format read from a
+flag, a form or a config file has these to be tested against before a call.
+"""
+
+STANDINGS: tuple[Standing, ...] = get_args(Standing)
+"""Every `Standing`, at runtime."""
+
+LICENSE_TYPES: tuple[LicenseType, ...] = get_args(LicenseType)
+"""Every `LicenseType`, at runtime. `None`, for no license, is not one of them."""
 
 Outcome = Literal["ok", "unauthorized", "denied", "expired", "unknown", "unavailable"]
 """How one download attempt ended, refusals included."""
@@ -49,7 +65,7 @@ class DatabaseVersion:
 
     Old versions are frozen rather than migrated, so several stay downloadable at once.
     `id` is what `download`, `checksums` and `metadata` take; the family `base` is what a
-    licence is held against.
+    license is held against.
     """
 
     id: str
@@ -60,13 +76,18 @@ class DatabaseVersion:
 
 @dataclass(frozen=True, slots=True)
 class Database:
-    """One database FAMILY, with your organization's licence beside it.
+    """One database FAMILY, with your organization's license beside it.
 
     A family your organization has never licensed is still listed, with `standing` set to
     `unlicensed`, so you can see what else exists. A family commissioned for a single
     customer is a different matter: it is absent from this listing entirely for everyone
     who does not license it. Absence here means "not yours to see", never "does not
     exist", so the catalog is not the same document for every key.
+
+    A rolling license carries `renews_at`, when it next renews, and `notice_due_at`, the
+    last day notice of non-renewal can be given for the term ending then. Both are None
+    when there is no license, when it has no defined term, or when `expires` sets a hard
+    stop instead; `notice_due_at` is None too when the agreement records no notice period.
     """
 
     base: str
@@ -76,6 +97,10 @@ class Database:
     license_type: LicenseType | None
     starts: datetime.datetime | None
     expires: datetime.datetime | None
+    # Keyword-only with a default, so a Database built by hand before 2.2.0 still builds;
+    # the parser always sets both.
+    renews_at: datetime.datetime | None = field(default=None, kw_only=True)
+    notice_due_at: datetime.datetime | None = field(default=None, kw_only=True)
     versions: tuple[DatabaseVersion, ...]
     raw: dict[str, Any] = field(default_factory=dict)
 
@@ -137,6 +162,8 @@ def to_database(body: dict[str, Any]) -> Database:
         license_type=body["license_type"],
         starts=_datetime(body["starts"]),
         expires=_datetime(body["expires"]),
+        renews_at=_datetime(body["renews_at"]),
+        notice_due_at=_datetime(body["notice_due_at"]),
         versions=tuple(to_version(v) for v in body["versions"]),
         raw=body,
     )
@@ -185,7 +212,7 @@ def to_download(body: dict[str, Any]) -> Download:
 
 
 def _datetime(value: Any) -> datetime.datetime | None:
-    """A NULLABLE wire timestamp. A licence with no end date carries `expires: null`.
+    """A NULLABLE wire timestamp. A license with no end date carries `expires: null`.
 
     `fromisoformat` only learned to read a trailing `Z` in 3.11, which is one of the
     three reasons this package floors there. A value that is neither null nor readable

{internetdata-2.1.0 → internetdata-2.3.0}/testdata/testdata.json

@@ -27,7 +27,7 @@
       }
     },
     {
-      "name": "licence-lapsed",
+      "name": "license-lapsed",
       "status": 403,
       "headers": {},
       "body": {
@@ -78,6 +78,20 @@
         "message": "INVALID_FORMAT"
       }
     },
+    {
+      "name": "unlisted-4xx-is-not-retryable",
+      "why": "The RANGE is the rule, not a list of statuses. An SDK that enumerated 400 and 404 passed every other case here while a 422 fell through to the retryable server_error default.",
+      "status": 422,
+      "headers": {},
+      "body": {
+        "rc": "INVALID_REQUEST"
+      },
+      "expect": {
+        "kind": "bad_request",
+        "retryable": false,
+        "message": "INVALID_REQUEST"
+      }
+    },
     {
       "name": "rate-limited-transient",
       "status": 429,

{internetdata-2.1.0 → internetdata-2.3.0}/tests/helpers.py

@@ -83,32 +83,34 @@ class DatabaseAdapter:
     def __init__(self, client: InternetData | AsyncInternetData) -> None:
         self._client = client
 
-    def list(self) -> Any:
-        return self._call("list")
+    def list(self, **kwargs: Any) -> Any:
+        return self._call("list", **kwargs)
 
-    def metadata(self, database_id: str) -> Any:
-        return self._call("metadata", database_id)
+    def metadata(self, database_id: str, **kwargs: Any) -> Any:
+        return self._call("metadata", database_id, **kwargs)
 
-    def checksums(self, database_id: str, format: str) -> Any:
-        return self._call("checksums", database_id, format)
+    def checksums(self, database_id: str, format: str, **kwargs: Any) -> Any:
+        return self._call("checksums", database_id, format, **kwargs)
 
-    def downloads(self, *args: Any) -> Any:
-        return self._call("downloads", *args)
+    def downloads(self, *args: Any, **kwargs: Any) -> Any:
+        return self._call("downloads", *args, **kwargs)
 
-    def download_url(self, database_id: str, format: str) -> Any:
-        return self._call("download_url", database_id, format)
+    def download_url(self, database_id: str, format: str, **kwargs: Any) -> Any:
+        return self._call("download_url", database_id, format, **kwargs)
 
-    def download(self, database_id: str, format: str, path: Any) -> Any:
-        return self._call("download", database_id, format, path)
+    def download(self, database_id: str, format: str, path: Any, **kwargs: Any) -> Any:
+        return self._call("download", database_id, format, path, **kwargs)
 
-    def download_bytes(self, database_id: str, format: str) -> Any:
-        return self._call("download_bytes", database_id, format)
+    def download_bytes(self, database_id: str, format: str, **kwargs: Any) -> Any:
+        return self._call("download_bytes", database_id, format, **kwargs)
 
-    def _call(self, name: str, *args: Any) -> Any:
+    # Keyword arguments are forwarded untouched and none is named here: a `timeout`
+    # in this signature would swallow the TypeError a transfer must raise for one.
+    def _call(self, name: str, *args: Any, **kwargs: Any) -> Any:
         method = getattr(self._client.database, name)
         if isinstance(self._client, InternetData):
-            return method(*args)
-        return asyncio.run(method(*args))
+            return method(*args, **kwargs)
+        return asyncio.run(method(*args, **kwargs))
 
 
 class Stub:

{internetdata-2.1.0 → internetdata-2.3.0}/tests/test_client.py

@@ -2,13 +2,16 @@
 
 from __future__ import annotations
 
+import asyncio
 import dataclasses
 import datetime
 import inspect
 import time
 from collections.abc import Callable
-from typing import Any
+from pathlib import Path
+from typing import Any, get_args
 
+import attrs
 import httpx
 import pytest
 from helpers import (
@@ -18,7 +21,6 @@ from helpers import (
     DOWNLOADS_PATH,
     LIST_PATH,
     METADATA_PATH,
-    ClientAdapter,
     ClientFactory,
     SlowBody,
     Stub,
@@ -26,7 +28,28 @@ from helpers import (
     settle,
 )
 
-from internetdata import AsyncInternetData, InternetData, InternetDataError, _core
+from internetdata import (
+    AsyncInternetData,
+    Database,
+    DatabaseMetadata,
+    DatabaseVersion,
+    Download,
+    InternetData,
+    InternetDataError,
+    MetadataColumn,
+    Outcome,
+    _core,
+)
+from internetdata._generated.models.database import Database as WireDatabase
+from internetdata._generated.models.database_metadata import (
+    DatabaseMetadata as WireDatabaseMetadata,
+)
+from internetdata._generated.models.database_metadata_column import (
+    DatabaseMetadataColumn as WireDatabaseMetadataColumn,
+)
+from internetdata._generated.models.database_version import DatabaseVersion as WireDatabaseVersion
+from internetdata._generated.models.download import Download as WireDownload
+from internetdata._generated.models.download_outcome import DownloadOutcome as WireDownloadOutcome
 
 METADATA = {
     "id": "bogon_ip_v1",
@@ -77,13 +100,28 @@ TIMEOUT = 0.3
 TRICKLE = 0.02
 # What starting a thread or an event loop may add to a deadline.
 SLACK = 0.25
+# The client's bound sits far above the call's, so an override accepted and ignored fails
+# on how long the call took rather than passing on the timeout it hit anyway.
+CLIENT_TIMEOUT = 0.6
+CALL_TIMEOUT = 0.1
+
+# Every call that asks the API a question, called with the keyword arguments given.
+JSON_CALLS: dict[str, Callable[..., Any]] = {
+    "list": lambda client, **kw: client.database.list(**kw),
+    "metadata": lambda client, **kw: client.database.metadata("bogon_ip_v1", **kw),
+    "checksums": lambda client, **kw: client.database.checksums("bogon_ip_v1", "csvgz", **kw),
+    "downloads": lambda client, **kw: client.database.downloads(**kw),
+    "download_url": lambda client, **kw: client.database.download_url("bogon_ip_v1", "csvgz", **kw),
+}
 
-JSON_CALLS: dict[str, Callable[[ClientAdapter], Any]] = {
-    "list": lambda client: client.database.list(),
-    "metadata": lambda client: client.database.metadata("bogon_ip_v1"),
-    "checksums": lambda client: client.database.checksums("bogon_ip_v1", "csvgz"),
-    "downloads": lambda client: client.database.downloads(),
-    "download_url": lambda client: client.database.download_url("bogon_ip_v1", "csvgz"),
+# The two transfers, which must REFUSE a per-call timeout rather than ignore one.
+TRANSFERS: dict[str, Callable[..., Any]] = {
+    "download": lambda client, path, **kw: client.database.download(
+        "bogon_ip_v1", "csvgz", path, **kw
+    ),
+    "download_bytes": lambda client, _path, **kw: client.database.download_bytes(
+        "bogon_ip_v1", "csvgz", **kw
+    ),
 }
 
 
@@ -141,6 +179,54 @@ def test_a_licence_with_no_end_date_reads_as_none(make_client: ClientFactory) ->
 
     assert family.starts == datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
     assert family.expires is None
+    assert family.renews_at is None
+    assert family.notice_due_at is None
+
+
+def test_a_rolling_license_carries_its_renewal_dates(make_client: ClientFactory) -> None:
+    served = database(
+        "bogon_ip",
+        renews_at="2027-01-01T00:00:00.000Z",
+        notice_due_at="2026-10-02T00:00:00.000Z",
+    )
+    stub = Stub({LIST_PATH: {"body": {"databases": [served]}}})
+    client = make_client(transport=stub.transport)
+
+    family = client.database.list()[0]
+
+    assert family.renews_at == datetime.datetime(2027, 1, 1, tzinfo=datetime.UTC)
+    assert family.notice_due_at == datetime.datetime(2026, 10, 2, tzinfo=datetime.UTC)
+
+
+@pytest.mark.parametrize(
+    ("wire", "ours"),
+    [
+        (WireDatabase, Database),
+        (WireDatabaseVersion, DatabaseVersion),
+        (WireDatabaseMetadata, DatabaseMetadata),
+        (WireDatabaseMetadataColumn, MetadataColumn),
+        (WireDownload, Download),
+    ],
+)
+def test_every_field_the_pinned_spec_serves_is_on_the_model(wire: Any, ours: Any) -> None:
+    """The staleness pin on the hand-written models.
+
+    They parse the keys they name and nothing else, so a field a re-pin adds reaches the
+    generated code and `raw` while the typed model never hears of it: `renews_at` and
+    `notice_due_at` sat that way from the 2026-09-09 re-pin until 2.2.0. The generated
+    classes come from the same pinned spec, which makes them the list to check against.
+    The generator suffixes a name that shadows a builtin with `_`.
+    """
+    served = {f.name.rstrip("_") for f in attrs.fields(wire)} - {"additional_properties"}
+    modeled = {f.name for f in dataclasses.fields(ours)} - {"raw"}
+    assert served - modeled == set(), f"{ours.__name__} lacks what the spec serves"
+
+
+def test_the_outcome_vocabulary_is_the_pinned_specs() -> None:
+    """The staleness pin on `Outcome`, the one hand-written Literal the corpus does not
+    carry: the generated enum comes from the same pinned spec, so a re-pin that adds an
+    outcome turns this red instead of leaving the type a member short."""
+    assert sorted(get_args(Outcome)) == sorted(member.value for member in WireDownloadOutcome)
 
 
 def test_a_database_cannot_be_mutated(make_client: ClientFactory) -> None:
@@ -287,11 +373,87 @@ def test_a_timed_out_attempt_is_retried_under_a_bound_of_its_own(
     )
 
 
+@pytest.mark.parametrize("call", JSON_CALLS)
+def test_a_per_call_timeout_bounds_a_trickling_body_and_leaves_the_clients_own_alone(
+    make_client: ClientFactory, call: str
+) -> None:
+    with SlowBody(trickle=TRICKLE) as server:
+        client = make_client(base_url=server.url, timeout=CLIENT_TIMEOUT, retries=0)
+        overridden, first = _timed(lambda: JSON_CALLS[call](client, timeout=CALL_TIMEOUT))
+        default, second = _timed(lambda: JSON_CALLS[call](client))
+
+    _assert_timed_out(first)
+    _assert_bounded_by(overridden, CALL_TIMEOUT)
+    # A per-call value written onto the one httpx client every call shares passes the
+    # call above and fails this one, which is what the second call is here for.
+    _assert_timed_out(second)
+    _assert_bounded_by(default, CLIENT_TIMEOUT)
+
+
+@pytest.mark.parametrize("timeout", [0, -1, float("nan"), float("inf"), "30", True])
+@pytest.mark.parametrize("call", JSON_CALLS)
+def test_a_per_call_timeout_no_attempt_can_meet_is_refused_before_any_request(
+    make_client: ClientFactory, call: str, timeout: Any
+) -> None:
+    """Accepted, each of these failed the call instead, after the retries' backoff."""
+    stub = Stub({})
+    client = make_client(transport=stub.transport, retries=0)
+
+    with pytest.raises(ValueError, match="timeout"):
+        JSON_CALLS[call](client, timeout=timeout)
+
+    assert stub.requests == []
+
+
+@pytest.mark.parametrize("call", TRANSFERS)
+def test_a_transfer_refuses_a_per_call_timeout(
+    make_client: ClientFactory, call: str, tmp_path: Path
+) -> None:
+    """A transfer is exempt from the deadline, so the option is not in its signature and
+    Python refuses it for us. Accepted and quietly ignored, a caller would be told
+    nothing; honored, a bound that suits a JSON call would abandon a healthy download."""
+    stub = Stub({})
+    client = make_client(transport=stub.transport, retries=0)
+    path = tmp_path / "bogon_ip_v1.csv.gz"
+
+    with pytest.raises(TypeError, match="timeout"):
+        TRANSFERS[call](client, path, timeout=CALL_TIMEOUT)
+
+    assert stub.requests == []
+    assert not path.exists()
+
+
+@pytest.mark.parametrize("name", JSON_CALLS)
+def test_every_json_call_takes_a_per_call_timeout(make_client: ClientFactory, name: str) -> None:
+    """The other half of the refusal above, which without this would pass just as well on
+    a surface that had never been given a per-call timeout at all."""
+    timeout = inspect.signature(getattr(make_client().client.database, name)).parameters["timeout"]
+
+    assert timeout.kind is inspect.Parameter.KEYWORD_ONLY
+    assert timeout.default is None
+
+
 def test_the_default_timeout_is_thirty_seconds() -> None:
     for client in (InternetData, AsyncInternetData):
         assert inspect.signature(client).parameters["timeout"].default == 30
 
 
+@pytest.mark.parametrize("client", [InternetData, AsyncInternetData])
+@pytest.mark.parametrize("timeout", [0, -1, 0.0, float("nan"), float("inf"), "30", True])
+def test_a_timeout_no_attempt_can_meet_is_refused_when_the_client_is_built(
+    client: type[InternetData | AsyncInternetData], timeout: Any
+) -> None:
+    """Accepted, each of these failed every call instead, after the retries' backoff."""
+    with pytest.raises(ValueError, match="timeout"):
+        client(API_KEY, timeout=timeout)
+
+
+@pytest.mark.parametrize("timeout", [None, 0.25, 1, 30])
+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())
+
+
 # Refused before the network, and never retried: a typo is the caller's, not a failure of
 # the server's to wait out.
 def test_an_unpublished_format_is_refused_before_any_request(make_client: ClientFactory) -> None:
@@ -346,6 +508,13 @@ def _assert_timed_out(outcome: Any) -> None:
 
 
 def _assert_one_bound(elapsed: float) -> None:
-    assert TIMEOUT - 0.05 <= elapsed < TIMEOUT + SLACK, (
-        f"gave up after {elapsed:.2f}s against a {TIMEOUT}s bound"
+    _assert_bounded_by(elapsed, TIMEOUT)
+
+
+def _assert_bounded_by(elapsed: float, bound: float) -> None:
+    """One bound's worth of waiting, with an UPPER and a LOWER limit: without the upper a
+    call that gave up at some other bound passes, and without the lower one abandoned at
+    its first chunk does."""
+    assert bound - 0.05 <= elapsed < bound + SLACK, (
+        f"gave up after {elapsed:.2f}s against a {bound}s bound"
     )

{internetdata-2.1.0 → internetdata-2.3.0}/tests/test_conformance.py

@@ -19,7 +19,7 @@ from helpers import (
     database,
 )
 
-from internetdata import InternetDataError
+from internetdata import DATABASE_FORMATS, LICENSE_TYPES, STANDINGS, InternetDataError
 
 # One live grant, one that has run out, and one never bought. Between them these cover
 # every value the corpus pins for `standing` and `license_type`.
@@ -65,21 +65,32 @@ def test_every_error_shape_maps_to_the_same_kind_in_every_language(
             assert err.retry_after_seconds == expect["retryAfterSeconds"], name
 
 
-# The one that has caught three of four bindings: 404 is a CLIENT error. Mapping
-# 400/401/403/429 by name and letting the rest fall through to a retryable server_error
-# means an unknown database id is asked for three times before failing.
-def test_a_404_is_never_retried(make_client: ClientFactory) -> None:
-    for case in TESTDATA["errors"]:
-        if case["status"] != 404:
-            continue
-        stub = Stub({METADATA_PATH: {"status": 404, "body": case["body"]}})
+# The one that has caught three of four bindings: every 4xx but a 429 carrying Retry-After
+# is the CALLER's, and classifying by an enumerated list lets the rest (the corpus's 422)
+# fall through to a retryable server_error. Asserted with retries ON and by counting
+# requests: with retries off, one request is guaranteed and a wrong classifier passes.
+def test_no_client_error_is_ever_retried(make_client: ClientFactory) -> None:
+    cases = [case for case in TESTDATA["errors"] if not case["expect"]["retryable"]]
+    assert any(case["name"] == "unlisted-4xx-is-not-retryable" for case in cases)
+
+    for case in cases:
+        stub = Stub(
+            {
+                METADATA_PATH: {
+                    "status": case["status"],
+                    "body": case["body"],
+                    "headers": case["headers"],
+                }
+            }
+        )
         client = make_client(transport=stub.transport, retries=3)
 
         with pytest.raises(InternetDataError) as caught:
             client.database.metadata("nope_v1")
 
-        assert caught.value.retryable is False, case["name"]
+        # The count first: a retried case also ends on an error, just a later one.
         assert len(stub.requests) == 1, f"{case['name']}: issued {len(stub.requests)} requests"
+        assert caught.value.kind == case["expect"]["kind"], case["name"]
 
 
 # Both arrive as 429 and the header is the only thing separating them, so a client that
@@ -118,7 +129,7 @@ def test_the_catalog_carries_every_standing_and_license_type_the_corpus_pins(
     assert served_rights <= set(TESTDATA["license_type"]), (
         f"undocumented license_type right in {served_rights}"
     )
-    # Null when there is no licence, which is a different answer from any of the three.
+    # Null when there is no license, which is a different answer from any of the three.
     assert [f.license_type for f in families][-1] is None
     for family in families:
         assert family.versions, f"{family.base} carries no versions"
@@ -128,6 +139,17 @@ def test_the_catalog_carries_every_standing_and_license_type_the_corpus_pins(
             )
 
 
+def test_the_runtime_vocabularies_are_the_pinned_specs() -> None:
+    """The staleness pin on three hand-written Literals.
+
+    `emit.mjs` reads the corpus's lists out of the pinned spec, so a re-pin that widens a
+    vocabulary turns this red instead of leaving a published value unnamed here.
+    """
+    assert sorted(DATABASE_FORMATS) == sorted(TESTDATA["formats"])
+    assert sorted(STANDINGS) == sorted(TESTDATA["standings"])
+    assert sorted(LICENSE_TYPES) == sorted(TESTDATA["license_type"])
+
+
 # The visibility contract. A private family is one commissioned for a single customer: the
 # server leaves it out of the listing entirely for anyone else, rather than including it
 # with standing 'unlicensed'. All this library has to do is not undo that, which is a real
@@ -161,7 +183,7 @@ def test_a_listing_is_never_reused_across_clients(make_client: ClientFactory) ->
     """Two keys are two organizations, and they do not see the same catalog.
 
     So there is no listing cache at all here, per instance or otherwise: a cached one
-    would be wrong the moment a licence is granted, and a shared one would show an
+    would be wrong the moment a license is granted, and a shared one would show an
     organization a family it is not allowed to know exists.
     """
     assert "a-listing-is-never-reused-across-clients" in TESTDATA["visibility"]["clientRules"]
@@ -172,12 +194,29 @@ def test_a_listing_is_never_reused_across_clients(make_client: ClientFactory) ->
     assert len(first.database.list()) == len(CATALOG)
     assert second.database.list() == [], "the second key answered from the first one's listing"
     assert len(stub.requests) == 2
-    # A repeat on the SAME client asks again too: a licence granted between two calls has
+    # A repeat on the SAME client asks again too: a license granted between two calls has
     # to show up.
     first.database.list()
     assert len(stub.requests) == 3
 
 
+# Each visibility rule the corpus names, and the test above that holds it. The three tests
+# each check that their own rule is still in the corpus; this checks the other direction,
+# so a rule added to the corpus fails here until something in this module holds it.
+VISIBILITY_RULES = {
+    "listing-is-returned-as-served": test_the_listing_is_returned_exactly_as_served,
+    "no-catalog-is-compiled-into-the-client": test_no_catalog_is_compiled_into_the_client,
+    "a-listing-is-never-reused-across-clients": test_a_listing_is_never_reused_across_clients,
+}
+
+
+def test_every_visibility_rule_in_the_corpus_is_held_here() -> None:
+    rules = TESTDATA["visibility"]["clientRules"]
+    assert rules, "the corpus pins no visibility rules"
+    unheld = sorted(set(rules) - set(VISIBILITY_RULES))
+    assert unheld == [], f"the corpus adds {unheld} and this suite does not check it"
+
+
 def test_checksums_unwrap_past_the_envelope(make_client: ClientFactory) -> None:
     """`checksums` nests under a key, beside `id` and `format`.
 
@@ -210,7 +249,7 @@ def test_the_api_key_reaches_the_wire_under_the_bearer_scheme(
 def test_a_keyless_client_sends_no_authorization_header(
     make_client: ClientFactory, api_key: str | None
 ) -> None:
-    """The key is optional because what this API serves without a licence is a product
+    """The key is optional because what this API serves without a license is a product
     decision, and a client that could not be built without one would have to change
     shape to follow it. What must never go out is `Bearer ` with nothing after it, which
     reads as a wrong key rather than as none.