kompressr-sdk 0.1.0__tar.gz

kompressr_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.venv/
+dist/
+build/
+*.egg-info/

kompressr_sdk-0.1.0/API.md

@@ -0,0 +1,109 @@
+# Python API reference
+
+The Python SDK follows JS SDK 1.0.0 and the shared API contract. Import `KompressrClient`, `PlatformClient`, `AsyncKompressrClient`, `AsyncPlatformClient`, `KompressrError`, `KompressrCancelledError` and `CancellationToken` from `kompressr`. Public response types are exported from that module too. Sync and async methods accept the same arguments and return the same typed dictionaries; async methods must be awaited. Async iteration uses `async for`.
+
+## Configuration
+
+Construct clients with keyword arguments:
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `api_key` | Required | Explicit project or scoped key; never persisted |
+| `project_id` | Omitted | File client only; UUID default for upload listing |
+| `api_base_url` | `https://kompressr.com` | Management origin |
+| `upload_base_url` | Derived | `https://uploads.kompressr.com` for the production management origin; otherwise the custom management origin |
+| `request_timeout` | `30` | Total management request budget in seconds |
+| `upload_timeout` | `600` | Total upload request budget in seconds |
+| `max_read_retries` | `2` | Additional eligible GET attempts, integer 0–5 |
+
+Origins must be absolute HTTP(S) origins without credentials, path, query or fragment. File clients expose resolved `api_base_url`, `upload_base_url` and `platform`. `resolve_endpoints(...)` and `ENDPOINTS` allow inspecting configuration without a request. For an alternate deployment, explicitly supply its management and upload origins. There is no environment-name switch.
+
+HTTPX verifies TLS certificates, does not follow redirects, has transport retries disabled and does not automatically read proxy settings from the environment. The SDK creates and closes a connection pool for each operation, including all retries. There is no persistent connection pool or client lifecycle method. No caller-supplied transport is accepted.
+
+DNS resolution shares a process-wide limit of eight daemon workers with no queued resolver jobs. Cancelling or timing out stops the caller promptly and prevents a late connection/write, even while an operating-system lookup remains blocked. That lookup keeps its slot until the OS returns; if all eight slots remain occupied, later hostname requests can time out waiting for admission. Numeric IP origins bypass DNS. A separate limit permits 64 live connections per process; waiting for either limit remains inside the request deadline.
+
+Resolved TCP addresses are tried sequentially in system order. Each receives a fair share of the **remaining** request budget divided by the remaining addresses, so a stalled first address leaves time for fallback. There is only one connection attempt per request at a time. This can take longer than Happy Eyeballs, which races address families, but avoids extra background connection attempts. DNS time is deducted before allocating those shares. The original hostname remains the HTTP Host and TLS SNI/certificate identity. Scoped IPv6 zone identifiers are unsupported.
+
+Every HTTP method supports keyword-only `timeout: float | None` and `cancel: CancellationToken | None`. Positive finite timeouts use seconds (maximum 2147483.647); constructor budgets apply when omitted. Deadlines include connection setup, upload writes, response reads and retry waits. File opening, validation and the snapshot of an in-memory buffer happen before the request budget. Standard local file reads occur in bounded chunks on the calling thread; filesystem I/O itself is subject to operating-system behavior. Arbitrary/custom stream readers, pipes and sockets are rejected.
+
+## Uploads and delivery
+
+| Method | Required arguments | Result |
+| --- | --- | --- |
+| `upload_file` | `path: str | PathLike[str]` | `UploadAccepted`; opens and closes a regular binary file |
+| `upload_bytes` | `content: bytes | bytearray | memoryview`, `filename` | `UploadAccepted`; snapshots the selected bytes when the operation starts |
+| `upload_stream` | `stream: BinaryIO`, `filename` | `UploadAccepted`; standard regular `FileIO`/`BufferedReader` or `BytesIO` only; rewinds to zero and leaves it open |
+| `get_upload_status` | `asset_id: int` | `UploadAsset` |
+| `wait_until_ready` | `asset_id: int` | Active, processed `UploadAsset` |
+| `generate_private_url` | `asset_id: int` | `PrivateUrl` |
+
+Upload keyword arguments: `visibility='public'|'private'` (server default if omitted), `quality='480p'|'720p'|'1080p'|'4k'` (video only), `data: CustomerData`, `private_url_expires_in: int` (60–604800 seconds). Metadata fields always precede the multipart file. Filenames must be nonempty, contain valid UTF-8 and have no control characters; directory components are removed. Stream subclasses/custom wrappers are unsupported because their reads can block cancellation or misreport length. File source contents must remain unchanged during upload.
+
+`CustomerData` is a dictionary of up to five scalar strings, finite numbers, booleans or `None`. Keys are trimmed, unique after trimming, nonempty and at most 64 UTF-8 bytes. String values support 512 UTF-8 bytes. Encoded upload data is limited to 4096 bytes; platform metadata to 8192.
+
+`wait_until_ready` accepts `timeout=120`, `poll_interval=2` (positive seconds, maximum 30) and `cancel`. A timeout raises `WAIT_TIMEOUT`; cancellation raises `WAIT_CANCELLED`. Both preserve `asset_id`. Failed, unprocessable or unknown processing raises `PROCESSING_FAILED`; nonactive deletion raises `ASSET_DELETED`. A processed public asset must have a delivery URL; a private one must be eligible to generate a link. Waiting never reuploads or signs automatically. The total wait deadline also bounds any in-flight status request and its retries. An earlier per-request deadline can surface as `REQUEST_TIMEOUT`, still with the saved asset ID.
+
+`generate_private_url` accepts `expires_in=3600` (60–604800 integer seconds), `variant='webp'|'avif'` (default `webp`), plus request options. The server rejects unprocessed/public assets or unavailable variants. Private URLs authorize access: do not place them in ordinary logs.
+
+`UploadAccepted` requires `id`, `status`, `deletion_status`, `visibility`, `original_name`, `original_size`, `asset_type`. The wire `asset_id` is normalized to `id`. Optional fields include delivery URLs, `private_url_expires_at`, `data`, `external_id`, `options`, `quality`, `warning`, `deletion_requested_at`.
+
+`UploadAsset` adds `kompressd_size`, `savings_percent`, `can_generate_private_url`; `original_name` is optional or empty for older records. Optional `input_format`, `output_format` and `created_at` may be returned. Sizes are bytes. Processing states are `pending`, `processing`, `processed`, `failed`, `unprocessable`, `unknown`; deletion is independent (`active`, `deleting`, `deleted`, `legacy_deleted`). Private assets cannot contain public URLs; nonactive assets cannot contain delivery URLs. A pending public URL does not prove readiness.
+
+`PrivateUrl` contains `asset_id`, `variant`, `private_url`, `expires_at`, `expires_in`.
+
+## Listing and lifecycle
+
+| Method | Arguments | Result |
+| --- | --- | --- |
+| `list_uploads` | Upload filters below | `Page[UploadAsset]` |
+| `iterate_uploads` | Same filters | Lazy sync iterator / async iterator of `UploadAsset` |
+| `list_assets` | `page=1`, `limit=20`, optional `deletion_status`, request options | `Page[AssetState]` |
+| `get_asset` | `asset_id`, request options | `AssetState` |
+| `delete_asset` | `asset_id`, request options | Accepted or completed deletion `AssetState` |
+| `bulk_delete_assets` | List of 1–100 explicit numeric IDs, request options | `BulkDeletion` |
+
+Upload filters are keyword-only `project_id` (required from constructor or call), `page=1`, `limit=20` (1–100), `visibility`, `external_id` (at most 512 UTF-8 bytes), `data` (up to five string-valued filters), `status` (pending/processing/processed/failed/unprocessable or integer 1–6), `deletion_status`, `timeout`, `cancel`. The server defaults deletion filtering to active. Status names are mapped to the numeric wire filter.
+
+`Page[T]` contains `data: list[T]`, `page`, `limit`, `total`. Iteration fetches only as needed, checks page progression and stops on an empty page or the reported total. Each page has a separate finite request deadline. Breaking iteration prevents further requests. Offset-based listings can change while files are added or deleted.
+
+`AssetState` requires `id`, `project_id`, `kind`, `source` (`upload`/`origin`), numeric `processing_status`, `deletion_status`, `storage_credited_mb`. Optional fields: `deletion_requested_at`, `accounting_status` (`pending`/`settled`/`unavailable`), `last_failure: {code, message, at}`. This lifecycle shape does not contain upload delivery metadata. List credits are zero; inspect detail for accounting.
+
+`BulkDeletion` preserves `results` (each `id`, HTTP-like `status`, `accepted`, optional `state`, `code`, `error`) and `counts` (`total`, `accepted`, `failed`). Duplicate input IDs count toward the input limit and are sent unchanged; response validation expects first-seen deduplication. Success of the HTTP request does not mean every item succeeded. Results and counts are validated together.
+
+Asset IDs must be positive integers no greater than 9007199254740991, retaining compatibility with the JS baseline. Booleans, strings and Python floats are rejected as ID inputs. Deletion is permanent and asynchronous; acceptance does not prove storage cleanup or cache expiry. There is no delete-by-URL, restore, implicit batch expansion or automatic mutation retry.
+
+## Platform administration
+
+Use `client.platform` or a standalone `PlatformClient`/`AsyncPlatformClient` with project authority. A scoped key cannot gain administration access by constructing a different client.
+
+| Method | Arguments | Result |
+| --- | --- | --- |
+| `list_users` | `page=1`, `limit=20`, request options | `ProjectUserPage` |
+| `create_user` | `customer_user_id`, optional `display_name`, `metadata`, request options | `{created, project_user}` |
+| `update_user` | `project_user_id`, optional `display_name`, `metadata`, request options | `ProjectUser` |
+| `suspend_user` | `project_user_id`, request options | `ProjectUser` |
+| `reactivate_user` | `project_user_id`, request options | `ProjectUser` |
+| `list_upload_keys` | `project_user_id`, `page=1`, `limit=20`, request options | `Page[UploadKey]` |
+| `create_upload_key` | `project_user_id`, `name`, optional policy below, request options | `IssuedKey` |
+| `rotate_upload_key` | `project_user_id`, key-record `key_id`, request options | `IssuedKey` |
+| `revoke_upload_key` | `project_user_id`, key-record `key_id`, request options | `None` |
+
+Project/user/key-record identifiers are UUID strings. Stable `customer_user_id` supports 1–256 UTF-8 bytes; the server finds or creates that identity. Display names support 120 bytes and can be cleared with `''`; omitted or `None` fields are not sent. Use `{}` to clear metadata.
+
+`create_upload_key` policy: optional `scopes: list[UploadScope]` drawn from `upload`, `status`, `list`, `private_url`, `delete`; `allowed_visibility='public'|'private'|'both'`; `allowed_asset_types: list[int]` (positive IDs; empty means all supported); `expires_at` (future ISO timestamp with timezone). Key names require 1–120 UTF-8 bytes. Omitted scopes (or `None`) use server defaults excluding delete; a nonempty explicit list replaces defaults. An explicitly empty list raises `INVALID_ARGUMENT` before any request: do not create a key when your permission filter selects no scopes. Issuing another key is not idempotent, and the SDK invents no spending limits.
+
+`ProjectUser` contains identity/project IDs, `customer_user_id`, `status` (`active`/`suspended`) and optional `display_name`, metadata, usage counters and activity timestamps. `ProjectUserPage` adds `project_active_count`, `org_active_count`, optional `usage_period: {start,end}` date strings. `UploadKey` contains `id`, `key_id`, project/user IDs, `name`, scopes, `allowed_visibility`, optional asset types and expiry/revocation/activity timestamps.
+
+`IssuedKey` contains `id`, `key_id`, `api_key` and optional `upload_key`. The raw key is returned once and must be stored or delivered securely; list methods do not recover it. Suspension revokes keys without deleting files. Reactivation does not restore revoked keys; issue a new key. Rotation replaces the secret.
+
+## Error and cancellation contract
+
+`KompressrError` exposes `kind`, `code`, optional `status`, `retry_after_ms`, `asset_id`, and boolean `may_have_succeeded`. `to_dict()` returns these safe fields and the message. Kinds: `validation`, `api`, `network`, `timeout`, `cancelled`, `invalid_response`, `processing`. Known credentials, bearer values, URLs and credential assignments are redacted from error messages; raw response bodies and one-time secrets are not attached. Do not log successful key or signed-URL result dictionaries.
+
+Eligible GET network errors and HTTP 429/502/503/504 retry with bounded backoff; `Retry-After` seconds/date or body `retry_after` is respected inside the total deadline. Other statuses, malformed successful responses and all writes have no automatic replay. Failed envelopes are handled even under HTTP 200. Responses above 2 MiB or malformed shapes raise `INVALID_RESPONSE`. Requests advertise `Accept-Encoding: identity`; other response content encodings are rejected before decompression. Successful compressed responses raise `INVALID_RESPONSE`; error responses retain their HTTP status and header retry delay without parsing the compressed body. Request timeouts and cancellation preserve the last known response status and retry delay, including while reading a body or waiting to retry. Starting a new attempt clears that prior response context.
+
+If a server rejects a large upload before reading its body and closes the connection, HTTPX can report a write/network error before exposing the HTTP response. The SDK then returns `NETWORK_ERROR` with `may_have_succeeded=True`, rather than the server's rejection status. Inspect the upload outcome before retrying; the SDK does not replay it automatically.
+
+A dispatched mutation can have succeeded despite timeout, network failure, task cancellation, rejected redirect, server failure, or invalid successful data. These errors set `may_have_succeeded=True`. Pre-dispatch cancellation and local validation set it false. A false value does not certify that replaying an entire application workflow is safe. Single-asset writes retain the requested ID. Upload recovery only trusts a positive safe numeric `data.asset_id` from a parsed successful envelope; broken JSON has no recoverable ID. Bulk errors never choose one arbitrary ID.
+
+`CancellationToken.cancel()` is thread-safe; pass the token as `cancel=`. Cancellation is checked before dispatch and during network activity/backoff with a small polling interval. Token cancellation raises `KompressrError`; native asyncio task cancellation raises `KompressrCancelledError`, retaining `asyncio.CancelledError` semantics and the same metadata. Catch native cancellation only for cleanup, then re-raise. Native task cancellation before a coroutine starts cannot attach SDK metadata because no SDK code has run. Standard local file errors may occur before a request and remain native Python exceptions.

kompressr_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Reject explicitly empty scoped-key permissions before dispatch; omission still uses server defaults.
+- Reject nonidentity response encodings before decompression to preserve bounded response memory and write-error context.
+- Retain known retry delays on request timeout and cancellation, clearing prior response metadata before another attempt.
+
+- Add typed sync and asyncio clients for uploads, readiness, private signing, listing and asset lifecycle operations.
+- Add complete project identity and scoped-key administration.
+- Bound DNS worker and connection resources, preserve TLS hostname verification and ensure slow resolver calls cannot delay cancellation or cause late writes.
+- Preserve bounded deadlines, read-only retries, cancellation, ambiguous-write context and credential-safe errors.
+- Add local HTTP regressions, package consumer verification, runnable examples and publishing guidance.

kompressr_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kompressr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kompressr_sdk-0.1.0/PARITY.md

@@ -0,0 +1,36 @@
+# Behavior and verification map
+
+Baseline: JS SDK 1.0.0 and the shared API contract. `tests/test_sdk.py` uses real loopback HTTP servers and synthetic credentials. The lifecycle fixture is copied from `contracts/fixtures/file-lifecycle.json` so source distributions can test independently.
+
+| JS surface / guarantee | Python surface | Regression evidence in `tests/test_sdk.py` |
+| --- | --- | --- |
+| uploadFile / uploadBytes / uploadBlob | upload_file / upload_bytes / upload_stream | real_file_multipart_separate_origins_and_polling; bytes_view_boundaries_and_snapshot; stream_reads_are_bounded_and_caller_retains_ownership; large_file_streaming_has_bounded_memory (32 MiB file, under 8 MiB traced allocations) |
+| getUploadStatus / waitUntilReady | get_upload_status / wait_until_ready | private_lifecycle_and_signing; optional_original_name; terminal_processing_states_with_url; readiness_requires_active_correct_delivery |
+| generatePrivateUrl | generate_private_url | private_lifecycle_and_signing; mutations_invalid_json_and_incomplete_shapes_keep_ambiguity |
+| listUploads / iterateUploads | list_uploads / iterate_uploads | pagination_filters_lazy_progression; invalid_pagination_and_empty_stop |
+| listAssets / getAsset / deleteAsset / bulkDeleteAssets | list_assets / get_asset / delete_asset / bulk_delete_assets | asset_listing_needs_no_project; deletion_states_and_per_item_bulk_results; mismatched_single_asset_response_retains_requested_id |
+| All nine platform methods | Same names in snake_case on platform | platform_all_routes_one_time_secrets_and_no_delete_default; platform_explicit_restrictions_and_counter_validation; empty_scopes_rejected_while_omission_keeps_defaults; empty_scopes_rejected_before_async_dispatch |
+| Total request and waiting budgets | timeout seconds | slow_response_body_has_total_request_deadline; slow_body_wait_deadline_preserves_id; slow_write_deadline_ambiguity_and_no_replay; retry_after_never_shortened_and_deadline_includes_delay |
+| Slow DNS, resolver saturation and TLS origins | Bounded shared DNS workers; sequential deadline-aware address fallback | tests/test_dns.py: sync_dns_timeout_returns_before_os_lookup_finishes_without_late_write; asyncio_run_exits_before_blocked_dns_finishes; dns_capacity_is_bounded_and_waiters_are_cancellable; stalled_first_address_leaves_time_for_healthy_fallback; https_keeps_original_host_sni_and_certificate_validation |
+| Cancellation before/after dispatch | CancellationToken and asyncio task cancellation | pre_cancel_sends_nothing; cancel_during_write_retains_sync_metadata; native_task_cancel_keeps_cancelled_semantics_and_write_context; native_wait_cancel_has_wait_code |
+| No blind write replay | Structured may_have_succeeded and asset_id | network_read_retries_but_writes_do_not; mutations_invalid_json_and_incomplete_shapes_keep_ambiguity (all eleven mutation families, broken/incomplete responses); unsafe_upload_ids_are_never_recovered |
+| Retry permissions and bounds | GET-only retries, no key substitution | eligible_read_retries_and_bounded_attempts; permission_and_non_retryable_errors_preserve_scope |
+| Retry metadata through interruptions | Preserve known delay; clear at the next attempt | retry_delay_survives_deadline_and_token_cancellation; native_cancellation_retains_retry_delay; new_attempt_clears_previous_retry_metadata |
+| Credential isolation | Redirect refusal, redacted structured errors | redirects_never_follow_or_leak_credentials; error_redaction_and_html_exclusion |
+| Input and response validation | Strict typed results and validation errors | invalid_inputs_rejected_before_network; response_size_limit_and_json_nonfinite; compression_bomb_is_rejected_before_expansion; compressed_responses_are_rejected_with_write_context; identity_response_and_compressed_http_error_metadata; readiness_requires_active_correct_delivery |
+| Installable distribution | Wheel and sdist, py.typed | scripts/verify.py installs a fresh consumer, checks types and repeats the HTTP suite |
+
+Test method names have the `test_` prefix. Parameterized scenarios use unittest subtests, so a test count does not equal the number of cases.
+
+## Intentional Python differences
+
+- Python uses snake_case methods/options and typed dictionaries. All deadlines and polling intervals use seconds; URL lifetimes remain integer seconds and retry metadata remains milliseconds.
+- Both sync and asyncio clients are provided. The sync adapter cannot be used inside an already running asyncio event loop. Native task cancellation remains a subclass of `asyncio.CancelledError`; cooperative cancellation tokens yield `KompressrError`.
+- Python has no Blob. `upload_stream` accepts standard regular binary files and BytesIO, rewinds to zero and retains caller ownership. Custom readers/subclasses, pipes and sockets are rejected before reading; arbitrary source code must not block the cancellation loop. File reads are bounded but ordinary filesystem operations can block at the operating-system level. `upload_file` opens/closes its own regular file.
+- Mutable bytes/memoryview inputs are snapshotted when the async operation begins executing. Merely creating a coroutine does not execute it. Keep source files unchanged until the upload completes.
+- DNS uses at most eight daemon workers; blocked OS lookups retain slots until completion while cancelled callers return promptly. Live connections are capped at 64. Address fallback is sequential, sharing the remaining deadline among remaining addresses, so fallback can be slower than Happy Eyeballs. Admission waiting is part of the request budget.
+- Request timeout options allow fractional seconds. Integer IDs and lifetimes reject Python booleans/floats; asset IDs retain the JS safe-integer ceiling. API keys require printable ASCII. Expiry input requires an explicit timezone. Filename validation rejects all control characters.
+- Optional response fields receive stricter validation when present (quality, warning, key timestamps and permitted asset types). Future incompatible shapes fail visibly rather than entering typed results.
+- HTTP pools live for one operation and all its retries, then close. This simplifies sync/async ownership and cross-thread use but does not reuse connections between separate operations. Environment proxy settings and caller-supplied HTTP transports are not supported.
+
+The suite establishes wire behavior against controlled HTTP fixtures. It does not establish current account entitlements, production scope enforcement, service availability or publishing ownership. Those are separate live/release checks.

kompressr_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: kompressr-sdk
+Version: 0.1.0
+Summary: Typed synchronous and asynchronous Python clients for Kompressr
+Project-URL: Homepage, https://kompressr.com
+Project-URL: Repository, https://github.com/kompressrcdn/clients
+Project-URL: Issues, https://github.com/kompressrcdn/clients/issues
+Author: Kompressr
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpcore[asyncio]<2,>=1.0.9
+Requires-Dist: httpx<1,>=0.28.1
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: cryptography<51,>=45; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kompressr for Python
+
+Upload and manage files from Python backends, scripts and asyncio applications. Requires Python 3.11 or later.
+
+## Install
+
+```sh
+python -m pip install kompressr-sdk
+```
+
+Use `KompressrClient` for synchronous applications, including Django views and background workers. Use `AsyncKompressrClient` in FastAPI async handlers or Django async views. No framework adapter is required.
+
+## Upload a file
+
+Create a Kompressr project and put its API key in your server's `KOMPRESSR_API_KEY` environment variable. Keep project credentials on your backend. API uploads and file types depend on your [plan](https://kompressr.com/pricing).
+
+```python
+import os
+from kompressr import KompressrClient
+
+files = KompressrClient(api_key=os.environ['KOMPRESSR_API_KEY'])
+accepted = files.upload_file('image.png', visibility='public')
+# Persist accepted['id'] in your application's database before waiting.
+ready = files.wait_until_ready(accepted['id'])
+print(ready['cdn_url'])
+```
+
+Acceptance means the server has the upload; processing may still be running. Save the numeric asset ID before waiting. If a wait times out, use that saved ID to resume status checks. Reuploading can create another asset.
+
+For private files, use `visibility='private'`, wait for readiness, then call `files.generate_private_url(asset_id)`. The result's `private_url` is an expiring authorization link. Return it only to an authorized user and keep it out of logs. Private readiness does not automatically create a fresh link.
+
+The runnable [upload example](https://github.com/kompressrcdn/clients/blob/main/sdk-python/examples/upload.py) saves a receipt before waiting and supports `--resume` with no second upload:
+
+```sh
+python sdk-python/examples/upload.py image.png --receipt receipt.json
+python sdk-python/examples/upload.py --resume --receipt receipt.json
+```
+
+The example prints a delivery link to your terminal when successful. Treat terminal history and captured output accordingly. Choose `--public` only for files intended for public delivery.
+
+## Asyncio
+
+Use `AsyncKompressrClient` in async applications. Methods and results match the synchronous client; await each call and use `async for` with `iterate_uploads`.
+
+```python
+import asyncio
+import os
+from kompressr import AsyncKompressrClient
+
+async def main():
+    files = AsyncKompressrClient(api_key=os.environ['KOMPRESSR_API_KEY'])
+    accepted = await files.upload_file('image.png', visibility='public')
+    # Save accepted['id'] durably here before waiting.
+    ready = await files.wait_until_ready(accepted['id'])
+    print(ready['cdn_url'])
+
+asyncio.run(main())
+```
+
+The synchronous client cannot run inside an active asyncio event loop; use the async client there. Clients create and close an HTTP connection pool per operation, so no `close()` is required and a sync client can be reused across threads. Async clients require asyncio; Trio is not supported. Regular files are read in bounded chunks; brief local file reads happen on the calling event-loop thread.
+
+## Failures and recovery
+
+```python
+from kompressr import KompressrError
+
+try:
+    ready = files.wait_until_ready(saved_asset_id, timeout=60)
+except KompressrError as error:
+    if error.code == 'WAIT_TIMEOUT':
+        # Keep error.asset_id and resume checking it later.
+        pass
+    else:
+        raise
+```
+
+All timeout values are **seconds**. Management requests default to 30 seconds, uploads to 600 seconds and readiness waiting to 120 seconds. A request deadline includes body reads and retry delays. Eligible GET failures may retry twice; uploads, signing, deletion and administration writes are never automatically replayed. When a write fails with `may_have_succeeded=True`, inspect the saved asset or operation outcome before deciding what to do next. A safely recovered `error.asset_id` may be available even when an upload acceptance response is malformed. Unknown outcomes can require application reconciliation.
+
+Pass a `CancellationToken` using `cancel=` to stop sync or async work cooperatively. Calling `token.cancel()` is thread-safe. Native async task cancellation raises `KompressrCancelledError`, a subclass of `asyncio.CancelledError`, with the same recovery metadata. Catch it only to save necessary state, then re-raise so structured cancellation works. Cancelling an operation cannot roll back server work.
+
+## Scoped keys and administration
+
+A regular project key can operate across that project and administer identities. A scoped key is bound to an identity, allowed actions, visibility and file types. Kompressr enforces those restrictions; the SDK never substitutes a stronger key. Your application still authenticates its users, binds their keys to the correct session, stores keys securely and authorizes conversation access.
+
+Use `files.platform` with a project key to create identities and issue scoped keys. The [platform example](https://github.com/kompressrcdn/clients/blob/main/sdk-python/examples/platform.py) explains secure one-time key storage and explicit key rotation/revocation. Scoped keys require a plan and project type supporting them. Delete permission is opt-in; the SDK leaves omitted scopes to the server's non-destructive defaults. See the [chatbot guide](https://github.com/kompressrcdn/clients/blob/main/guides/chatbot-integration.md) for the application flow.
+
+## More operations
+
+See [API.md](https://github.com/kompressrcdn/clients/blob/main/sdk-python/API.md) for all file and platform methods, options and response fields; [PARITY.md](https://github.com/kompressrcdn/clients/blob/main/sdk-python/PARITY.md) maps behavior to tests. Results are typed dictionaries with API snake_case keys. File uploads stream from regular files; `upload_bytes` supports bytes, bytearray and selected memoryview slices. `upload_stream` supports a standard open regular binary file or BytesIO (custom readers/subclasses are rejected), rewinds to the beginning and leaves ownership with the caller.
+
+List uploads with `project_id` supplied to the constructor or call. `iterate_uploads` fetches pages lazily. Asset list/detail do not require a project ID: the server derives the project from the key. Deletion is permanent and asynchronous; an accepted deletion is not proof that storage cleanup or cache expiry has finished. Bulk deletion keeps each item's outcome even under HTTP 200.
+
+## Development
+
+```sh
+cd sdk-python
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python scripts/verify.py
+```
+
+Verification typechecks, runs local HTTP tests, builds wheel/source distributions, checks archive contents, installs the wheel in a fresh environment and repeats HTTP tests against that installed package. It uses synthetic credentials and no Kompressr account.
+
+MIT licensed. Report bugs through the repository's issue tracker and security concerns through [SECURITY.md](https://github.com/kompressrcdn/clients/blob/main/SECURITY.md).

kompressr_sdk-0.1.0/README.md

@@ -0,0 +1,105 @@
+# Kompressr for Python
+
+Upload and manage files from Python backends, scripts and asyncio applications. Requires Python 3.11 or later.
+
+## Install
+
+```sh
+python -m pip install kompressr-sdk
+```
+
+Use `KompressrClient` for synchronous applications, including Django views and background workers. Use `AsyncKompressrClient` in FastAPI async handlers or Django async views. No framework adapter is required.
+
+## Upload a file
+
+Create a Kompressr project and put its API key in your server's `KOMPRESSR_API_KEY` environment variable. Keep project credentials on your backend. API uploads and file types depend on your [plan](https://kompressr.com/pricing).
+
+```python
+import os
+from kompressr import KompressrClient
+
+files = KompressrClient(api_key=os.environ['KOMPRESSR_API_KEY'])
+accepted = files.upload_file('image.png', visibility='public')
+# Persist accepted['id'] in your application's database before waiting.
+ready = files.wait_until_ready(accepted['id'])
+print(ready['cdn_url'])
+```
+
+Acceptance means the server has the upload; processing may still be running. Save the numeric asset ID before waiting. If a wait times out, use that saved ID to resume status checks. Reuploading can create another asset.
+
+For private files, use `visibility='private'`, wait for readiness, then call `files.generate_private_url(asset_id)`. The result's `private_url` is an expiring authorization link. Return it only to an authorized user and keep it out of logs. Private readiness does not automatically create a fresh link.
+
+The runnable [upload example](https://github.com/kompressrcdn/clients/blob/main/sdk-python/examples/upload.py) saves a receipt before waiting and supports `--resume` with no second upload:
+
+```sh
+python sdk-python/examples/upload.py image.png --receipt receipt.json
+python sdk-python/examples/upload.py --resume --receipt receipt.json
+```
+
+The example prints a delivery link to your terminal when successful. Treat terminal history and captured output accordingly. Choose `--public` only for files intended for public delivery.
+
+## Asyncio
+
+Use `AsyncKompressrClient` in async applications. Methods and results match the synchronous client; await each call and use `async for` with `iterate_uploads`.
+
+```python
+import asyncio
+import os
+from kompressr import AsyncKompressrClient
+
+async def main():
+    files = AsyncKompressrClient(api_key=os.environ['KOMPRESSR_API_KEY'])
+    accepted = await files.upload_file('image.png', visibility='public')
+    # Save accepted['id'] durably here before waiting.
+    ready = await files.wait_until_ready(accepted['id'])
+    print(ready['cdn_url'])
+
+asyncio.run(main())
+```
+
+The synchronous client cannot run inside an active asyncio event loop; use the async client there. Clients create and close an HTTP connection pool per operation, so no `close()` is required and a sync client can be reused across threads. Async clients require asyncio; Trio is not supported. Regular files are read in bounded chunks; brief local file reads happen on the calling event-loop thread.
+
+## Failures and recovery
+
+```python
+from kompressr import KompressrError
+
+try:
+    ready = files.wait_until_ready(saved_asset_id, timeout=60)
+except KompressrError as error:
+    if error.code == 'WAIT_TIMEOUT':
+        # Keep error.asset_id and resume checking it later.
+        pass
+    else:
+        raise
+```
+
+All timeout values are **seconds**. Management requests default to 30 seconds, uploads to 600 seconds and readiness waiting to 120 seconds. A request deadline includes body reads and retry delays. Eligible GET failures may retry twice; uploads, signing, deletion and administration writes are never automatically replayed. When a write fails with `may_have_succeeded=True`, inspect the saved asset or operation outcome before deciding what to do next. A safely recovered `error.asset_id` may be available even when an upload acceptance response is malformed. Unknown outcomes can require application reconciliation.
+
+Pass a `CancellationToken` using `cancel=` to stop sync or async work cooperatively. Calling `token.cancel()` is thread-safe. Native async task cancellation raises `KompressrCancelledError`, a subclass of `asyncio.CancelledError`, with the same recovery metadata. Catch it only to save necessary state, then re-raise so structured cancellation works. Cancelling an operation cannot roll back server work.
+
+## Scoped keys and administration
+
+A regular project key can operate across that project and administer identities. A scoped key is bound to an identity, allowed actions, visibility and file types. Kompressr enforces those restrictions; the SDK never substitutes a stronger key. Your application still authenticates its users, binds their keys to the correct session, stores keys securely and authorizes conversation access.
+
+Use `files.platform` with a project key to create identities and issue scoped keys. The [platform example](https://github.com/kompressrcdn/clients/blob/main/sdk-python/examples/platform.py) explains secure one-time key storage and explicit key rotation/revocation. Scoped keys require a plan and project type supporting them. Delete permission is opt-in; the SDK leaves omitted scopes to the server's non-destructive defaults. See the [chatbot guide](https://github.com/kompressrcdn/clients/blob/main/guides/chatbot-integration.md) for the application flow.
+
+## More operations
+
+See [API.md](https://github.com/kompressrcdn/clients/blob/main/sdk-python/API.md) for all file and platform methods, options and response fields; [PARITY.md](https://github.com/kompressrcdn/clients/blob/main/sdk-python/PARITY.md) maps behavior to tests. Results are typed dictionaries with API snake_case keys. File uploads stream from regular files; `upload_bytes` supports bytes, bytearray and selected memoryview slices. `upload_stream` supports a standard open regular binary file or BytesIO (custom readers/subclasses are rejected), rewinds to the beginning and leaves ownership with the caller.
+
+List uploads with `project_id` supplied to the constructor or call. `iterate_uploads` fetches pages lazily. Asset list/detail do not require a project ID: the server derives the project from the key. Deletion is permanent and asynchronous; an accepted deletion is not proof that storage cleanup or cache expiry has finished. Bulk deletion keeps each item's outcome even under HTTP 200.
+
+## Development
+
+```sh
+cd sdk-python
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python scripts/verify.py
+```
+
+Verification typechecks, runs local HTTP tests, builds wheel/source distributions, checks archive contents, installs the wheel in a fresh environment and repeats HTTP tests against that installed package. It uses synthetic credentials and no Kompressr account.
+
+MIT licensed. Report bugs through the repository's issue tracker and security concerns through [SECURITY.md](https://github.com/kompressrcdn/clients/blob/main/SECURITY.md).

kompressr_sdk-0.1.0/examples/platform.py

@@ -0,0 +1,45 @@
+"""Provision an identity and store its one-time key in a new private file."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from kompressr import KompressrClient, KompressrError
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('customer_user_id', help='Stable identity from your authenticated application')
+    parser.add_argument('--key-file', required=True, help='New private output file outside the repository')
+    args = parser.parse_args()
+    key = os.environ.get('KOMPRESSR_API_KEY')
+    if not key:
+        parser.error('Set KOMPRESSR_API_KEY to your project credential on a trusted backend.')
+    files = KompressrClient(api_key=key, api_base_url=os.environ.get('KOMPRESSR_API_BASE_URL', 'https://kompressr.com'),
+        upload_base_url=os.environ.get('KOMPRESSR_UPLOAD_BASE_URL'))
+    # Reserve the secret destination before issuing a nonrecoverable raw key.
+    descriptor = os.open(args.key_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(descriptor, 'w') as destination:
+        user = files.platform.create_user(args.customer_user_id)['project_user']
+        issued = files.platform.create_upload_key(user['id'], 'Application runtime',
+            scopes=['upload', 'status', 'list', 'private_url'], allowed_visibility='private')
+        json.dump({'project_user_id': user['id'], 'key_record_id': issued['id'], 'api_key': issued['api_key']}, destination)
+        destination.flush()
+        os.fsync(destination.fileno())
+    print('Scoped key saved. Give it only to the authenticated runtime for this identity.')
+    # In production use an encrypted credential store instead of a local file.
+    # Later: rotated = files.platform.rotate_upload_key(user['id'], issued['id'])
+    # Persist rotated['api_key'] securely before switching the runtime to it.
+    # To revoke: files.platform.revoke_upload_key(user['id'], issued['id'])
+    # To suspend all keys: files.platform.suspend_user(user['id'])
+    # Reactivation does not restore revoked keys; create a new key afterwards.
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except KompressrError as error:
+        print(json.dumps(error.to_dict()), file=sys.stderr)
+        sys.exit(1)

kompressr_sdk-0.1.0/examples/upload.py

@@ -0,0 +1,63 @@
+"""Upload privately by default, save the ID, then print an authorized delivery link."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+from kompressr import KompressrClient, KompressrError
+
+
+def save(handle, client, asset_id, state):
+    handle.seek(0)
+    json.dump({'asset_id': asset_id, 'api_base_url': client.api_base_url, 'state': state}, handle)
+    handle.truncate()
+    handle.flush()
+    os.fsync(handle.fileno())
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('file', nargs='?', type=Path)
+    parser.add_argument('--receipt', required=True, type=Path, help='New receipt path for upload, existing path for resume')
+    parser.add_argument('--resume', action='store_true', help='Check the saved ID without uploading')
+    parser.add_argument('--public', action='store_true', help='Upload for public delivery instead of private delivery')
+    args = parser.parse_args()
+    if args.resume == bool(args.file):
+        parser.error('Supply a file for a new upload, or --resume with no file.')
+    key = os.environ.get('KOMPRESSR_API_KEY')
+    if not key:
+        parser.error('Set KOMPRESSR_API_KEY in your server environment.')
+    files = KompressrClient(api_key=key, api_base_url=os.environ.get('KOMPRESSR_API_BASE_URL', 'https://kompressr.com'),
+        upload_base_url=os.environ.get('KOMPRESSR_UPLOAD_BASE_URL'))
+    if args.resume:
+        receipt = json.loads(args.receipt.read_text())
+        asset_id = receipt.get('asset_id')
+        if type(asset_id) is not int or asset_id < 1 or receipt.get('api_base_url') != files.api_base_url:
+            parser.error('The receipt needs a saved asset ID and the same configured management origin.')
+    else:
+        # Reserve storage before a write so a receipt cannot overwrite an older upload.
+        descriptor = os.open(args.receipt, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(descriptor, 'w') as handle:
+            save(handle, files, None, 'not_accepted')
+            try:
+                accepted = files.upload_file(args.file, visibility='public' if args.public else 'private')
+            except KompressrError as error:
+                save(handle, files, error.asset_id, 'uncertain' if error.may_have_succeeded else 'failed')
+                raise
+            asset_id = accepted['id']
+            save(handle, files, asset_id, 'accepted')
+    ready = files.wait_until_ready(asset_id)
+    # This is intentional terminal output; do not route private links into routine logs.
+    link = files.generate_private_url(asset_id)['private_url'] if ready['visibility'] == 'private' else ready['cdn_url']
+    print(link)
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except KompressrError as error:
+        print(json.dumps(error.to_dict()), file=sys.stderr)
+        sys.exit(1)

kompressr_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kompressr-sdk"
+version = "0.1.0"
+description = "Typed synchronous and asynchronous Python clients for Kompressr"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Kompressr"}]
+dependencies = ["httpx>=0.28.1,<1", "httpcore[asyncio]>=1.0.9,<2"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://kompressr.com"
+Repository = "https://github.com/kompressrcdn/clients"
+Issues = "https://github.com/kompressrcdn/clients/issues"
+
+[project.optional-dependencies]
+dev = ["build>=1.2,<2", "mypy>=1.15,<2", "twine>=6,<7", "cryptography>=45,<51"]
+
+[tool.hatch.build.targets.wheel]
+core-metadata-version = "2.4"
+packages = ["src/kompressr"]
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+include = ["/src", "/tests", "/examples", "/scripts", "/README.md", "/API.md", "/PARITY.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/kompressr"]