internetdata 2.2.0__tar.gz → 2.4.0__tar.gz

{internetdata-2.2.0 → internetdata-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.2.0
+Version: 2.4.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
@@ -51,7 +51,7 @@ Requires Python 3.11 or newer. Type hints are included, and the package ships `p
 
 ## Usage
 
-Every call needs an API key carrying the `db.download` scope. Create one in the console, then:
+Every database call needs an API key carrying the `db.download` scope. Create one in the console, then:
 
 ```python
 import os
@@ -167,18 +167,42 @@ 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. Anything else that is not a number greater than 0 raises `ValueError` when the client is built:
+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.
 
+### Sign in with OAuth (device flow)
+
+A program running on someone's own machine can let them sign in with a browser and pick one of their API keys, instead of asking them to paste it:
+
+```python
+from internetdata import InternetData
+
+with InternetData() as signin:
+    device = signin.oauth.device_authorization(
+        "your-client-id", scope="account.read apikeys.read apikeys.reveal"
+    )
+    print(f"Open {device.verification_uri} and enter {device.user_code}")
+    tokens = signin.oauth.poll_device_token("your-client-id", device)
+
+if tokens.apikey is None:
+    raise SystemExit("No API key was picked")
+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.
+
 ## 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.2.0 → internetdata-2.4.0}/README.md

@@ -17,7 +17,7 @@ Requires Python 3.11 or newer. Type hints are included, and the package ships `p
 
 ## Usage
 
-Every call needs an API key carrying the `db.download` scope. Create one in the console, then:
+Every database call needs an API key carrying the `db.download` scope. Create one in the console, then:
 
 ```python
 import os
@@ -133,18 +133,42 @@ 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. Anything else that is not a number greater than 0 raises `ValueError` when the client is built:
+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.
 
+### Sign in with OAuth (device flow)
+
+A program running on someone's own machine can let them sign in with a browser and pick one of their API keys, instead of asking them to paste it:
+
+```python
+from internetdata import InternetData
+
+with InternetData() as signin:
+    device = signin.oauth.device_authorization(
+        "your-client-id", scope="account.read apikeys.read apikeys.reveal"
+    )
+    print(f"Open {device.verification_uri} and enter {device.user_code}")
+    tokens = signin.oauth.poll_device_token("your-client-id", device)
+
+if tokens.apikey is None:
+    raise SystemExit("No API key was picked")
+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.
+
 ## 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.2.0 → internetdata-2.4.0}/scripts/v2_subset.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-"""Narrows the pinned spec to the v2 API, for codegen only.
+"""Narrows the pinned spec to what this client generates from, for codegen only.
 
     python3 scripts/v2_subset.py spec/openapi.yaml /tmp/v2.yaml
 
@@ -11,6 +11,10 @@ rather than a bearer token), a different error vocabulary, and no `list`. Genera
 would ship dead modules and, worse, a second credential spelling that looks usable from
 this client and is not.
 
+Everything else is kept: the v2 database, IAM and OAuth, as the VPNDetection SDK generates
+them. IAM is generated and left unwrapped; the `oauth` accessor sends its own requests
+and never calls the generated authorization endpoints.
+
 So the narrowing happens here rather than in the pinned copy. Unreferenced components go
 with the paths, or the generator emits models for v1 envelopes nothing can reach.
 
@@ -25,7 +29,12 @@ from typing import Any
 
 from ruamel.yaml import YAML
 
-KEEP_PATH_PREFIX = "/api/v2/"
+KEEP_PATH_PREFIXES = (
+    "/api/v2/",
+    "/api/v1/iam/",
+    "/oauth/",
+    "/.well-known/oauth-authorization-server",
+)
 # v1's `?apikey=` credential. Dropped with v1 itself: leaving it in the spec would put a
 # second, unusable auth spelling in the generated client.
 DROP_SECURITY_SCHEMES = ("ApiKeyAuth",)
@@ -40,18 +49,18 @@ def main(source: str, destination: str) -> int:
         spec: dict[str, Any] = yaml.load(handle)
 
     paths = spec.get("paths", {})
-    dropped = [path for path in paths if not path.startswith(KEEP_PATH_PREFIX)]
+    dropped = [path for path in paths if not path.startswith(KEEP_PATH_PREFIXES)]
     for path in dropped:
         del paths[path]
-    if not paths:
-        raise SystemExit(f"no {KEEP_PATH_PREFIX} paths survived, so the spec moved under us")
+    if not any(path.startswith(KEEP_PATH_PREFIXES[0]) for path in paths):
+        raise SystemExit(f"no {KEEP_PATH_PREFIXES[0]} paths survived, so the spec moved under us")
 
     components = spec.get("components", {})
     for scheme in DROP_SECURITY_SCHEMES:
         components.get("securitySchemes", {}).pop(scheme, None)
-    # The document-level default is v1's; every v2 operation names BearerAuth itself, and
-    # leaving a scheme here that no longer exists is an invalid spec.
-    spec["security"] = [{"BearerAuth": []}]
+    # Every kept operation names its own security, so a document-level default could only
+    # name the dropped v1 scheme, which would leave the spec invalid.
+    spec.pop("security", None)
 
     reachable = resolve_refs(spec, components)
     for section in REF_SECTIONS:
@@ -65,7 +74,7 @@ def main(source: str, destination: str) -> int:
 
     with open(destination, "w") as handle:
         yaml.dump(spec, handle)
-    print(f"{destination} <- {source} ({len(paths)} v2 paths, dropped {len(dropped)})")
+    print(f"{destination} <- {source} ({len(paths)} paths kept, dropped {len(dropped)})")
     return 0