internetdata 2.8.0__tar.gz → 2.9.0__tar.gz

{internetdata-2.8.0 → internetdata-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.8.0
+Version: 2.9.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
@@ -223,6 +223,20 @@ tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.v
 
 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`.
 
+### Register a client
+
+An app with no client ID, and no client metadata document to use as one, registers itself and signs in with the `client_id` it gets back:
+
+```python
+client = InternetData()
+registration = client.oauth.register(
+    ["http://127.0.0.1:8765/callback"], client_name="Your App"
+)
+# registration.client_id is the client ID for authorization_url and exchange_authorization_code.
+```
+
+Each redirect URI must be https on a public host name, or http on a loopback address, which then matches any port. Nothing is kept until a person approves the client, so an app with no client ID saved can simply register again.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, and Ruby. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.8.0 → internetdata-2.9.0}/README.md

@@ -189,6 +189,20 @@ tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.v
 
 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`.
 
+### Register a client
+
+An app with no client ID, and no client metadata document to use as one, registers itself and signs in with the `client_id` it gets back:
+
+```python
+client = InternetData()
+registration = client.oauth.register(
+    ["http://127.0.0.1:8765/callback"], client_name="Your App"
+)
+# registration.client_id is the client ID for authorization_url and exchange_authorization_code.
+```
+
+Each redirect URI must be https on a public host name, or http on a loopback address, which then matches any port. Nothing is kept until a person approves the client, so an app with no client ID saved can simply register again.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, and Ruby. See our GitHub at https://github.com/internetdata for more.

{internetdata-2.8.0 → internetdata-2.9.0}/src/internetdata/__init__.py

@@ -24,6 +24,7 @@ from .models import (
     DATABASE_FORMATS,
     LICENSE_TYPES,
     STANDINGS,
+    ClientRegistration,
     Database,
     DatabaseMetadata,
     DatabaseVersion,
@@ -39,7 +40,7 @@ from .models import (
     TokenResponse,
 )
 
-__version__ = "2.8.0"
+__version__ = "2.9.0"
 
 __all__ = [
     "DATABASE_FORMATS",
@@ -49,6 +50,7 @@ __all__ = [
     "AsyncDatabaseApi",
     "AsyncInternetData",
     "AsyncOauthApi",
+    "ClientRegistration",
     "Database",
     "DatabaseApi",
     "DatabaseMetadata",

{internetdata-2.8.0 → internetdata-2.9.0}/src/internetdata/_core.py

@@ -14,7 +14,7 @@ import os
 import secrets
 import threading
 import time
-from collections.abc import Callable, Iterator
+from collections.abc import Callable, Iterator, Sequence
 from pathlib import Path
 from types import ModuleType
 from typing import IO, Any, TypeVar, cast
@@ -36,6 +36,7 @@ OAUTH_DEVICE_AUTHORIZATION_PATH = "/oauth/device_authorization"
 OAUTH_TOKEN_PATH = "/oauth/token"
 OAUTH_REVOKE_PATH = "/oauth/revoke"
 OAUTH_AUTHORIZE_PATH = "/oauth/authorize"
+OAUTH_REGISTER_PATH = "/oauth/register"
 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
@@ -348,10 +349,13 @@ def oauth_request(
     path: str,
     form: dict[str, str] | None,
     bound: float | None,
+    body: dict[str, Any] | None = None,
 ) -> httpx.Response:
-    """One attempt at an OAuth endpoint, carrying no credential, its failure raised."""
+    """One attempt at an OAuth endpoint, carrying no credential, its failure raised. `body`
+    goes as JSON, for `register`; every other one sends a form or nothing."""
     http = client.get_httpx_client()
-    return oauth_checked(exchange(http, _oauth_build(http, method, path, form, bound), bound))
+    req = _oauth_build(http, method, path, form, bound, body)
+    return oauth_checked(exchange(http, req, bound))
 
 
 async def oauth_request_async(
@@ -360,13 +364,39 @@ async def oauth_request_async(
     path: str,
     form: dict[str, str] | None,
     bound: float | None,
+    body: dict[str, Any] | None = None,
 ) -> httpx.Response:
     """`oauth_request`, awaited."""
     http = client.get_async_httpx_client()
-    req = _oauth_build(http, method, path, form, bound)
+    req = _oauth_build(http, method, path, form, bound, body)
     return oauth_checked(await exchange_async(http, req, bound))
 
 
+def registration_body(redirect_uris: Sequence[str], client_name: str | None) -> dict[str, Any]:
+    """`register`'s JSON body: the redirect URIs in the order given, then `client_name`
+    unless it is None or empty. No URI at all, an empty one, or one with no UTF-8 (a lone
+    surrogate) is refused before anything is sent."""
+    if isinstance(redirect_uris, str) or not redirect_uris:
+        raise ValueError(f"redirect_uris must list at least one URI, not {redirect_uris!r}")
+    uris = list(redirect_uris)
+    for i, uri in enumerate(uris):
+        _check_text(f"redirect_uris[{i}]", uri)
+    body: dict[str, Any] = {"redirect_uris": uris}
+    if client_name:
+        _check_text("client_name", client_name)
+        body["client_name"] = client_name
+    return body
+
+
+def _check_text(name: str, value: Any) -> None:
+    if not isinstance(value, str) or value == "":
+        raise ValueError(f"{name} must be a non-empty string, not {value!r}")
+    try:
+        value.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"{name} has no UTF-8 to send: {value!r}") from exc
+
+
 def authorization_url(
     base_url: str,
     client_id: str,
@@ -571,8 +601,9 @@ def _oauth_build(
     path: str,
     form: dict[str, str] | None,
     bound: float | None,
+    body: dict[str, Any] | None = None,
 ) -> httpx.Request:
-    req = http.build_request(method, path, data=form, timeout=httpx.Timeout(bound))
+    req = http.build_request(method, path, data=form, json=body, timeout=httpx.Timeout(bound))
     req.headers.pop("authorization", None)
     return req
 

{internetdata-2.8.0 → internetdata-2.9.0}/src/internetdata/aio.py

@@ -10,9 +10,9 @@ from __future__ import annotations
 import asyncio
 import builtins
 import os
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Sequence
 from types import TracebackType
-from typing import Self, TypeVar
+from typing import Any, Self, TypeVar
 
 import httpx
 
@@ -24,6 +24,7 @@ from ._core import (
     DEVICE_CODE_GRANT,
     OAUTH_DEVICE_AUTHORIZATION_PATH,
     OAUTH_METADATA_PATH,
+    OAUTH_REGISTER_PATH,
     OAUTH_REVOKE_PATH,
     OAUTH_TOKEN_PATH,
     POLL_DEADLINE_CAP,
@@ -45,6 +46,7 @@ from ._core import (
     part_file,
     pkce_challenge,
     redirect_location,
+    registration_body,
     request_async,
     retry_delay,
     storage_refusal,
@@ -60,6 +62,7 @@ from ._generated.client import AuthenticatedClient
 from ._generated.models.database_format import DatabaseFormat
 from .errors import InternetDataError, OauthError, OauthExpiredTokenError
 from .models import (
+    ClientRegistration,
     Database,
     DatabaseMetadata,
     DeviceAuthorization,
@@ -68,6 +71,7 @@ from .models import (
     OauthMetadata,
     Pkce,
     TokenResponse,
+    to_client_registration,
     to_device_authorization,
     to_metadata,
     to_oauth_metadata,
@@ -434,6 +438,22 @@ class AsyncOauthApi:
         """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
         return pkce_challenge(verifier)
 
+    async def register(
+        self,
+        redirect_uris: Sequence[str],
+        *,
+        client_name: str | None = None,
+        timeout: float | None = None,
+    ) -> ClientRegistration:
+        """Register a client for the authorization code flow; see `OauthApi.register`."""
+        body = registration_body(redirect_uris, client_name)
+
+        async def call() -> ClientRegistration:
+            res = await self._send("POST", OAUTH_REGISTER_PATH, None, timeout, body)
+            return to_client_registration(oauth_body(res), res.status_code)
+
+        return await self._owner._retrying(call, self._owner._retries)
+
     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."""
 
@@ -480,7 +500,12 @@ class AsyncOauthApi:
         return await self._owner._retrying(call, 0)
 
     async def _send(
-        self, method: str, path: str, form: dict[str, str] | None, timeout: float | None
+        self,
+        method: str,
+        path: str,
+        form: dict[str, str] | None,
+        timeout: float | None,
+        body: dict[str, Any] | None = None,
     ) -> httpx.Response:
         bound = self._owner._bound(timeout)
-        return await oauth_request_async(self._owner._client, method, path, form, bound)
+        return await oauth_request_async(self._owner._client, method, path, form, bound, body)

{internetdata-2.8.0 → internetdata-2.9.0}/src/internetdata/client.py

@@ -5,9 +5,9 @@ from __future__ import annotations
 import builtins
 import os
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from types import TracebackType
-from typing import Self, TypeVar
+from typing import Any, Self, TypeVar
 
 import httpx
 
@@ -19,6 +19,7 @@ from ._core import (
     DEVICE_CODE_GRANT,
     OAUTH_DEVICE_AUTHORIZATION_PATH,
     OAUTH_METADATA_PATH,
+    OAUTH_REGISTER_PATH,
     OAUTH_REVOKE_PATH,
     OAUTH_TOKEN_PATH,
     POLL_DEADLINE_CAP,
@@ -40,6 +41,7 @@ from ._core import (
     part_file,
     pkce_challenge,
     redirect_location,
+    registration_body,
     request,
     retry_delay,
     storage_refusal,
@@ -55,6 +57,7 @@ from ._generated.client import AuthenticatedClient
 from ._generated.models.database_format import DatabaseFormat
 from .errors import InternetDataError, OauthError, OauthExpiredTokenError
 from .models import (
+    ClientRegistration,
     Database,
     DatabaseMetadata,
     DeviceAuthorization,
@@ -63,6 +66,7 @@ from .models import (
     OauthMetadata,
     Pkce,
     TokenResponse,
+    to_client_registration,
     to_device_authorization,
     to_metadata,
     to_oauth_metadata,
@@ -470,6 +474,31 @@ class OauthApi:
         """The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url."""
         return pkce_challenge(verifier)
 
+    def register(
+        self,
+        redirect_uris: Sequence[str],
+        *,
+        client_name: str | None = None,
+        timeout: float | None = None,
+    ) -> ClientRegistration:
+        """Register a client for the authorization code flow, for a program that cannot
+        serve a Client ID Metadata Document, and get its `client_id`.
+
+        Each redirect URI must be https on a public host name, or http on a loopback
+        address, which then matches on any port; the server refuses any other with the
+        `OauthError` `invalid_redirect_uri`. Nothing is kept until a person approves the
+        client, so registering again costs nothing, and this is retried like a lookup. No
+        URI at all, an empty one, or one with no UTF-8 raises `ValueError` before anything
+        is sent.
+        """
+        body = registration_body(redirect_uris, client_name)
+
+        def call() -> ClientRegistration:
+            res = self._send("POST", OAUTH_REGISTER_PATH, None, timeout, body)
+            return to_client_registration(oauth_body(res), res.status_code)
+
+        return self._owner._retrying(call, self._owner._retries)
+
     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."""
@@ -524,6 +553,12 @@ class OauthApi:
         return self._owner._retrying(call, 0)
 
     def _send(
-        self, method: str, path: str, form: dict[str, str] | None, timeout: float | None
+        self,
+        method: str,
+        path: str,
+        form: dict[str, str] | None,
+        timeout: float | None,
+        body: dict[str, Any] | None = None,
     ) -> httpx.Response:
-        return oauth_request(self._owner._client, method, path, form, self._owner._bound(timeout))
+        bound = self._owner._bound(timeout)
+        return oauth_request(self._owner._client, method, path, form, bound, body)

{internetdata-2.8.0 → internetdata-2.9.0}/src/internetdata/models.py

@@ -361,6 +361,26 @@ class TokenResponse:
     apikey: str | None = field(default=None, repr=False)
 
 
+@dataclass(frozen=True, slots=True)
+class ClientRegistration:
+    """A registered client, public and with no secret: it proves each sign-in with PKCE.
+
+    `client_id` goes to `authorization_url` and `exchange_authorization_code`.
+    `client_id_issued_at` is Unix seconds, and `client_name` the name the person will see,
+    a placeholder when none was given or none can be shown. `token_endpoint_auth_method` is
+    always `none`, and `scope` the most this client may be granted.
+    """
+
+    client_id: str
+    client_id_issued_at: int
+    client_name: str
+    redirect_uris: tuple[str, ...]
+    token_endpoint_auth_method: str
+    grant_types: tuple[str, ...] | None = None
+    response_types: tuple[str, ...] | None = None
+    scope: str | None = None
+
+
 def to_oauth_metadata(body: Any, status: int) -> OauthMetadata:
     return OauthMetadata(**_members(body, _OAUTH_METADATA, status))
 
@@ -373,6 +393,10 @@ def to_token_response(body: Any, status: int) -> TokenResponse:
     return TokenResponse(**_members(body, _TOKEN_RESPONSE, status))
 
 
+def to_client_registration(body: Any, status: int) -> ClientRegistration:
+    return ClientRegistration(**_members(body, _CLIENT_REGISTRATION, status))
+
+
 # A member's type on the wire, and whether a 2xx without it is malformed.
 _Member = tuple[Literal["str", "int", "bool", "strs"], bool]
 
@@ -412,6 +436,17 @@ _TOKEN_RESPONSE: dict[str, _Member] = {
     "apikey": ("str", False),
 }
 
+_CLIENT_REGISTRATION: dict[str, _Member] = {
+    "client_id": ("str", True),
+    "client_id_issued_at": ("int", True),
+    "client_name": ("str", True),
+    "redirect_uris": ("strs", True),
+    "token_endpoint_auth_method": ("str", True),
+    "grant_types": ("strs", False),
+    "response_types": ("strs", False),
+    "scope": ("str", False),
+}
+
 _WIRE_NAMES = {"apikey_id": "mslm:apikey_id", "apikey": "mslm:apikey"}