hypersr 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hypersr-0.1.0/.gitignore +78 -0
- hypersr-0.1.0/CHANGELOG.md +19 -0
- hypersr-0.1.0/PKG-INFO +162 -0
- hypersr-0.1.0/README.md +128 -0
- hypersr-0.1.0/examples/multiple_scenes.py +45 -0
- hypersr-0.1.0/examples/quickstart.py +44 -0
- hypersr-0.1.0/examples/rasterio_metadata.py +17 -0
- hypersr-0.1.0/pyproject.toml +72 -0
- hypersr-0.1.0/src/hypersr/__init__.py +67 -0
- hypersr-0.1.0/src/hypersr/_version.py +3 -0
- hypersr-0.1.0/src/hypersr/client.py +573 -0
- hypersr-0.1.0/src/hypersr/exceptions.py +69 -0
- hypersr-0.1.0/src/hypersr/models.py +221 -0
- hypersr-0.1.0/src/hypersr/py.typed +0 -0
- hypersr-0.1.0/tests/test_client.py +459 -0
- hypersr-0.1.0/uv.lock +1033 -0
hypersr-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Local folders and files
|
|
2
|
+
instructions
|
|
3
|
+
AGENTS.md
|
|
4
|
+
/human/
|
|
5
|
+
|
|
6
|
+
# Operating systems and editors
|
|
7
|
+
.DS_Store
|
|
8
|
+
Thumbs.db
|
|
9
|
+
.idea/
|
|
10
|
+
.vscode/
|
|
11
|
+
*.swp
|
|
12
|
+
*.swo
|
|
13
|
+
*~
|
|
14
|
+
|
|
15
|
+
# Secrets and local configuration
|
|
16
|
+
.env
|
|
17
|
+
.env.*
|
|
18
|
+
!.env.example
|
|
19
|
+
*.pem
|
|
20
|
+
*.key
|
|
21
|
+
|
|
22
|
+
# Logs and temporary files
|
|
23
|
+
*.log
|
|
24
|
+
logs/
|
|
25
|
+
tmp/
|
|
26
|
+
.cache/
|
|
27
|
+
|
|
28
|
+
# JavaScript / TypeScript
|
|
29
|
+
node_modules/
|
|
30
|
+
.npm/
|
|
31
|
+
.next/
|
|
32
|
+
.next-e2e-local/
|
|
33
|
+
.next-e2e-admin/
|
|
34
|
+
.nuxt/
|
|
35
|
+
.turbo/
|
|
36
|
+
dist/
|
|
37
|
+
build/
|
|
38
|
+
coverage/
|
|
39
|
+
*.tsbuildinfo
|
|
40
|
+
|
|
41
|
+
# Python
|
|
42
|
+
__pycache__/
|
|
43
|
+
*.py[cod]
|
|
44
|
+
.venv/
|
|
45
|
+
venv/
|
|
46
|
+
.pytest_cache/
|
|
47
|
+
.mypy_cache/
|
|
48
|
+
.ruff_cache/
|
|
49
|
+
.coverage
|
|
50
|
+
htmlcov/
|
|
51
|
+
*.egg-info/
|
|
52
|
+
|
|
53
|
+
# Cloud tooling and infrastructure
|
|
54
|
+
.wrangler/
|
|
55
|
+
.dev.vars
|
|
56
|
+
.dev.vars.*
|
|
57
|
+
.terraform/
|
|
58
|
+
*.tfstate
|
|
59
|
+
*.tfstate.*
|
|
60
|
+
*.tfplan
|
|
61
|
+
|
|
62
|
+
# HyperSR generated local data and frontend adapters
|
|
63
|
+
*.db
|
|
64
|
+
*.db-shm
|
|
65
|
+
*.db-wal
|
|
66
|
+
.astro/
|
|
67
|
+
.open-next/
|
|
68
|
+
.pnpm-store/
|
|
69
|
+
backups/
|
|
70
|
+
artifacts/
|
|
71
|
+
playwright-report/
|
|
72
|
+
test-results/
|
|
73
|
+
|
|
74
|
+
# Selected model weights are exported locally; their hashes and recipe are tracked.
|
|
75
|
+
/models/hypersr_v1/**/*.ckpt
|
|
76
|
+
/models/hypersr_v1/**/*.safetensor
|
|
77
|
+
/models/hypersr_v1/**/*.safetensors
|
|
78
|
+
/services/worker/.venv-inference/
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First HyperSR Python client release for Python 3.11 and newer.
|
|
6
|
+
|
|
7
|
+
- Typed authentication, model discovery, quotes, idempotent job submission,
|
|
8
|
+
status polling, cancellation and paginated history.
|
|
9
|
+
- Streamed artifact downloads with size/checksum verification and atomic writes;
|
|
10
|
+
API credentials stay separate from signed storage requests.
|
|
11
|
+
- Credits and expiry metadata, account summaries, saved areas, notification
|
|
12
|
+
preferences, key management and server-configured billing discovery.
|
|
13
|
+
- Job history filters and downloads selected by stable product role.
|
|
14
|
+
- Typed scene discovery by area and target date before quote/confirmation.
|
|
15
|
+
- Bounded retries, HTTP and polling timeouts, typed exceptions, PEP 561 typing
|
|
16
|
+
information and optional Rasterio examples.
|
|
17
|
+
|
|
18
|
+
This version packages the API client. Hosted service availability, scientific
|
|
19
|
+
model acceptance and commercial launch have their own acceptance requirements.
|
hypersr-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hypersr
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Typed Python client for the HyperSR multispectral super-resolution API.
|
|
5
|
+
Project-URL: Homepage, https://hypersr.com
|
|
6
|
+
Project-URL: Documentation, https://github.com/HyperalisLabs/hypersr/blob/main/packages/sdk-python/README.md
|
|
7
|
+
Project-URL: Repository, https://github.com/HyperalisLabs/hypersr
|
|
8
|
+
Project-URL: Issues, https://github.com/HyperalisLabs/hypersr/issues
|
|
9
|
+
Author: Hyperalis Labs
|
|
10
|
+
License-Expression: LicenseRef-Proprietary
|
|
11
|
+
Keywords: api-client,geospatial,satellite,sentinel-2,super-resolution
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Requires-Dist: httpx<1,>=0.27
|
|
25
|
+
Requires-Dist: pydantic<3,>=2.7
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
|
|
31
|
+
Provides-Extra: rasterio
|
|
32
|
+
Requires-Dist: rasterio<2,>=1.3; extra == 'rasterio'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# HyperSR Python SDK
|
|
36
|
+
|
|
37
|
+
`hypersr` is a typed, synchronous Python client for the HyperSR asynchronous
|
|
38
|
+
Sentinel-2 super-resolution API. It requires Python 3.11 or newer.
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
python -m pip install hypersr
|
|
44
|
+
# or, in a uv-managed project:
|
|
45
|
+
uv add hypersr
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Set an API key through the environment or a secret manager:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
export HYPERSR_API_KEY="hs_live_..."
|
|
52
|
+
export HYPERSR_SCENE_ID="<provider scene identifier>"
|
|
53
|
+
export HYPERSR_BBOX='[2.10, 41.30, 2.11, 41.31]'
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The default endpoint is `https://api.hypersr.com/v1`. Pass `base_url` to use a
|
|
57
|
+
local or staging API, for example `HyperSR(api_key=key,
|
|
58
|
+
base_url="http://localhost:8000/v1")`.
|
|
59
|
+
Replace the example bounding box with `[west, south, east, north]` coordinates
|
|
60
|
+
covered by your selected scene. Installing the client does not activate the
|
|
61
|
+
hosted service; a reachable API and an account with an API key are required.
|
|
62
|
+
|
|
63
|
+
## Discover, quote, submit, and poll
|
|
64
|
+
|
|
65
|
+
The server owns model availability and pricing. Discover enabled models first,
|
|
66
|
+
then request a quote for a provider scene and WGS84 bounding box. A quote
|
|
67
|
+
contains integer `required_credits`; the client never calculates or submits a
|
|
68
|
+
billable amount. Confirmation is an explicit `jobs.submit` call using the
|
|
69
|
+
quote ID and an idempotency key.
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import json
|
|
73
|
+
import os
|
|
74
|
+
from uuid import uuid4
|
|
75
|
+
|
|
76
|
+
from hypersr import HyperSR, HyperSRError
|
|
77
|
+
|
|
78
|
+
with HyperSR(
|
|
79
|
+
os.environ["HYPERSR_API_KEY"],
|
|
80
|
+
base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
|
|
81
|
+
) as client:
|
|
82
|
+
bbox = json.loads(os.environ["HYPERSR_BBOX"])
|
|
83
|
+
models = client.models()
|
|
84
|
+
model = next(item for item in models if item.slug == "hypersr_v1" and item.enabled)
|
|
85
|
+
quote = client.jobs.quote(
|
|
86
|
+
scene_id=os.environ["HYPERSR_SCENE_ID"],
|
|
87
|
+
bbox=bbox,
|
|
88
|
+
model=model.slug,
|
|
89
|
+
)
|
|
90
|
+
print(f"quote {quote.id}: {quote.required_credits} internal units")
|
|
91
|
+
try:
|
|
92
|
+
job = client.jobs.submit(quote_id=quote.id, idempotency_key=f"quickstart-{uuid4()}")
|
|
93
|
+
result = client.jobs.wait(job.id, timeout=1800)
|
|
94
|
+
except HyperSRError as exc:
|
|
95
|
+
print(f"HyperSR request failed: {exc}")
|
|
96
|
+
else:
|
|
97
|
+
print(result.status, result.error_code, result.error_message)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`wait` returns all service terminal outcomes: `completed`, `failed`, and
|
|
101
|
+
`cancelled`. It raises `hypersr.TimeoutError` when its deadline expires. A
|
|
102
|
+
failed or cancelled queued job does not consume the reserved processing
|
|
103
|
+
credits. One displayed credit equals **1,000 internal units**; for example,
|
|
104
|
+
`client.credits().available / 1000` gives the displayed balance. Credit expiry
|
|
105
|
+
is available through `credit_lots` and `next_expiry` on the balance response.
|
|
106
|
+
|
|
107
|
+
## Download the product bundle
|
|
108
|
+
|
|
109
|
+
Completed jobs expose four typed artifacts: `reflectance`, `scl`, `cloud_mask`,
|
|
110
|
+
and `provenance`. Each has its own signed URL and checksum. The URLs are
|
|
111
|
+
short-lived bearer capabilities; do not log or share them.
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
import os
|
|
115
|
+
from pathlib import Path
|
|
116
|
+
|
|
117
|
+
from hypersr import HyperSR
|
|
118
|
+
|
|
119
|
+
with HyperSR(
|
|
120
|
+
os.environ["HYPERSR_API_KEY"],
|
|
121
|
+
base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
|
|
122
|
+
) as client:
|
|
123
|
+
job = client.jobs.get(os.environ["HYPERSR_JOB_ID"])
|
|
124
|
+
if job.status == "completed":
|
|
125
|
+
output_dir = Path("hypersr-output")
|
|
126
|
+
for role in ("reflectance", "scl", "cloud_mask", "provenance"):
|
|
127
|
+
suffix = ".json" if role == "provenance" else ".tif"
|
|
128
|
+
client.jobs.download_role(job.id, role, output_dir / f"{role}{suffix}")
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Set `HYPERSR_JOB_ID` to the ID returned by submission. Downloads use a separate
|
|
132
|
+
HTTP client without the API key, stream to a temporary file, verify available
|
|
133
|
+
size/SHA-256 metadata and replace the destination only after success.
|
|
134
|
+
|
|
135
|
+
Rasterio is optional. Install `hypersr[rasterio]` to inspect a downloaded
|
|
136
|
+
reflectance COG; see `examples/rasterio_metadata.py`.
|
|
137
|
+
|
|
138
|
+
## Retries, errors, and service limits
|
|
139
|
+
|
|
140
|
+
Safe reads retry transient HTTP failures. Mutations retry only when an
|
|
141
|
+
idempotency key is present and the server operation supports replay; reuse the
|
|
142
|
+
same key when retrying a submission. Key creation and saved-area creation are
|
|
143
|
+
never automatically retried because their secrets/results cannot be replayed.
|
|
144
|
+
`HyperSRError` is the common exception, with typed `APIError` subclasses for
|
|
145
|
+
authentication, validation, not-found, conflict, and rate-limit responses.
|
|
146
|
+
Retries are bounded (`max_retries=2` by default), and each `wait` call has a
|
|
147
|
+
deadline.
|
|
148
|
+
|
|
149
|
+
The service validates scene identifiers, WGS84 boxes, supported bands, model
|
|
150
|
+
availability, quote expiry, area and queue limits. It may reject a well-formed
|
|
151
|
+
request when a model or provider scene is unavailable. The initial release is
|
|
152
|
+
asynchronous and supports Sentinel-2 Level-2A scenes covered by an enabled
|
|
153
|
+
model; a 2.5 m output grid is reconstructed output spacing, not a native 2.5 m
|
|
154
|
+
observation. See the repository API guide for the current contract and
|
|
155
|
+
`examples/` for runnable scripts.
|
|
156
|
+
|
|
157
|
+
The client also exposes saved AOIs (`aois`, `get_aoi`, `create_aoi`,
|
|
158
|
+
`update_aoi`, `delete_aoi`), notification preferences, account summaries,
|
|
159
|
+
server-configured billing packages, and filtered/paginated job history.
|
|
160
|
+
Use `client.scenes.search(bbox=bbox, target_date="2026-11-01")` to discover
|
|
161
|
+
provider acquisitions before requesting a quote. Search returns a selected
|
|
162
|
+
scene plus candidates and does not create a job or reserve credits.
|
hypersr-0.1.0/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# HyperSR Python SDK
|
|
2
|
+
|
|
3
|
+
`hypersr` is a typed, synchronous Python client for the HyperSR asynchronous
|
|
4
|
+
Sentinel-2 super-resolution API. It requires Python 3.11 or newer.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
python -m pip install hypersr
|
|
10
|
+
# or, in a uv-managed project:
|
|
11
|
+
uv add hypersr
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Set an API key through the environment or a secret manager:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
export HYPERSR_API_KEY="hs_live_..."
|
|
18
|
+
export HYPERSR_SCENE_ID="<provider scene identifier>"
|
|
19
|
+
export HYPERSR_BBOX='[2.10, 41.30, 2.11, 41.31]'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The default endpoint is `https://api.hypersr.com/v1`. Pass `base_url` to use a
|
|
23
|
+
local or staging API, for example `HyperSR(api_key=key,
|
|
24
|
+
base_url="http://localhost:8000/v1")`.
|
|
25
|
+
Replace the example bounding box with `[west, south, east, north]` coordinates
|
|
26
|
+
covered by your selected scene. Installing the client does not activate the
|
|
27
|
+
hosted service; a reachable API and an account with an API key are required.
|
|
28
|
+
|
|
29
|
+
## Discover, quote, submit, and poll
|
|
30
|
+
|
|
31
|
+
The server owns model availability and pricing. Discover enabled models first,
|
|
32
|
+
then request a quote for a provider scene and WGS84 bounding box. A quote
|
|
33
|
+
contains integer `required_credits`; the client never calculates or submits a
|
|
34
|
+
billable amount. Confirmation is an explicit `jobs.submit` call using the
|
|
35
|
+
quote ID and an idempotency key.
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
import json
|
|
39
|
+
import os
|
|
40
|
+
from uuid import uuid4
|
|
41
|
+
|
|
42
|
+
from hypersr import HyperSR, HyperSRError
|
|
43
|
+
|
|
44
|
+
with HyperSR(
|
|
45
|
+
os.environ["HYPERSR_API_KEY"],
|
|
46
|
+
base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
|
|
47
|
+
) as client:
|
|
48
|
+
bbox = json.loads(os.environ["HYPERSR_BBOX"])
|
|
49
|
+
models = client.models()
|
|
50
|
+
model = next(item for item in models if item.slug == "hypersr_v1" and item.enabled)
|
|
51
|
+
quote = client.jobs.quote(
|
|
52
|
+
scene_id=os.environ["HYPERSR_SCENE_ID"],
|
|
53
|
+
bbox=bbox,
|
|
54
|
+
model=model.slug,
|
|
55
|
+
)
|
|
56
|
+
print(f"quote {quote.id}: {quote.required_credits} internal units")
|
|
57
|
+
try:
|
|
58
|
+
job = client.jobs.submit(quote_id=quote.id, idempotency_key=f"quickstart-{uuid4()}")
|
|
59
|
+
result = client.jobs.wait(job.id, timeout=1800)
|
|
60
|
+
except HyperSRError as exc:
|
|
61
|
+
print(f"HyperSR request failed: {exc}")
|
|
62
|
+
else:
|
|
63
|
+
print(result.status, result.error_code, result.error_message)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`wait` returns all service terminal outcomes: `completed`, `failed`, and
|
|
67
|
+
`cancelled`. It raises `hypersr.TimeoutError` when its deadline expires. A
|
|
68
|
+
failed or cancelled queued job does not consume the reserved processing
|
|
69
|
+
credits. One displayed credit equals **1,000 internal units**; for example,
|
|
70
|
+
`client.credits().available / 1000` gives the displayed balance. Credit expiry
|
|
71
|
+
is available through `credit_lots` and `next_expiry` on the balance response.
|
|
72
|
+
|
|
73
|
+
## Download the product bundle
|
|
74
|
+
|
|
75
|
+
Completed jobs expose four typed artifacts: `reflectance`, `scl`, `cloud_mask`,
|
|
76
|
+
and `provenance`. Each has its own signed URL and checksum. The URLs are
|
|
77
|
+
short-lived bearer capabilities; do not log or share them.
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
import os
|
|
81
|
+
from pathlib import Path
|
|
82
|
+
|
|
83
|
+
from hypersr import HyperSR
|
|
84
|
+
|
|
85
|
+
with HyperSR(
|
|
86
|
+
os.environ["HYPERSR_API_KEY"],
|
|
87
|
+
base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
|
|
88
|
+
) as client:
|
|
89
|
+
job = client.jobs.get(os.environ["HYPERSR_JOB_ID"])
|
|
90
|
+
if job.status == "completed":
|
|
91
|
+
output_dir = Path("hypersr-output")
|
|
92
|
+
for role in ("reflectance", "scl", "cloud_mask", "provenance"):
|
|
93
|
+
suffix = ".json" if role == "provenance" else ".tif"
|
|
94
|
+
client.jobs.download_role(job.id, role, output_dir / f"{role}{suffix}")
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Set `HYPERSR_JOB_ID` to the ID returned by submission. Downloads use a separate
|
|
98
|
+
HTTP client without the API key, stream to a temporary file, verify available
|
|
99
|
+
size/SHA-256 metadata and replace the destination only after success.
|
|
100
|
+
|
|
101
|
+
Rasterio is optional. Install `hypersr[rasterio]` to inspect a downloaded
|
|
102
|
+
reflectance COG; see `examples/rasterio_metadata.py`.
|
|
103
|
+
|
|
104
|
+
## Retries, errors, and service limits
|
|
105
|
+
|
|
106
|
+
Safe reads retry transient HTTP failures. Mutations retry only when an
|
|
107
|
+
idempotency key is present and the server operation supports replay; reuse the
|
|
108
|
+
same key when retrying a submission. Key creation and saved-area creation are
|
|
109
|
+
never automatically retried because their secrets/results cannot be replayed.
|
|
110
|
+
`HyperSRError` is the common exception, with typed `APIError` subclasses for
|
|
111
|
+
authentication, validation, not-found, conflict, and rate-limit responses.
|
|
112
|
+
Retries are bounded (`max_retries=2` by default), and each `wait` call has a
|
|
113
|
+
deadline.
|
|
114
|
+
|
|
115
|
+
The service validates scene identifiers, WGS84 boxes, supported bands, model
|
|
116
|
+
availability, quote expiry, area and queue limits. It may reject a well-formed
|
|
117
|
+
request when a model or provider scene is unavailable. The initial release is
|
|
118
|
+
asynchronous and supports Sentinel-2 Level-2A scenes covered by an enabled
|
|
119
|
+
model; a 2.5 m output grid is reconstructed output spacing, not a native 2.5 m
|
|
120
|
+
observation. See the repository API guide for the current contract and
|
|
121
|
+
`examples/` for runnable scripts.
|
|
122
|
+
|
|
123
|
+
The client also exposes saved AOIs (`aois`, `get_aoi`, `create_aoi`,
|
|
124
|
+
`update_aoi`, `delete_aoi`), notification preferences, account summaries,
|
|
125
|
+
server-configured billing packages, and filtered/paginated job history.
|
|
126
|
+
Use `client.scenes.search(bbox=bbox, target_date="2026-11-01")` to discover
|
|
127
|
+
provider acquisitions before requesting a quote. Search returns a selected
|
|
128
|
+
scene plus candidates and does not create a job or reserve credits.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""Submit configured scenes with unique idempotency keys and poll them."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
from uuid import uuid4
|
|
6
|
+
|
|
7
|
+
from hypersr import HyperSR, HyperSRError
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main() -> None:
|
|
11
|
+
scenes = [item.strip() for item in os.environ["HYPERSR_SCENE_IDS"].split(",") if item.strip()]
|
|
12
|
+
if not scenes:
|
|
13
|
+
raise ValueError("HYPERSR_SCENE_IDS must contain at least one scene identifier")
|
|
14
|
+
bbox = tuple(json.loads(os.environ["HYPERSR_BBOX"]))
|
|
15
|
+
if len(bbox) != 4:
|
|
16
|
+
raise ValueError("HYPERSR_BBOX must be a JSON array of four WGS84 coordinates")
|
|
17
|
+
with HyperSR(
|
|
18
|
+
api_key=os.environ["HYPERSR_API_KEY"],
|
|
19
|
+
base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
|
|
20
|
+
) as client:
|
|
21
|
+
model = next(item for item in client.models() if item.slug == "hypersr_v1" and item.enabled)
|
|
22
|
+
jobs = []
|
|
23
|
+
for scene in scenes:
|
|
24
|
+
quote = client.jobs.quote(
|
|
25
|
+
scene_id=scene,
|
|
26
|
+
bbox=bbox,
|
|
27
|
+
model=model.slug,
|
|
28
|
+
)
|
|
29
|
+
jobs.append(client.jobs.submit(quote_id=quote.id, idempotency_key=f"batch-{uuid4()}"))
|
|
30
|
+
for job in jobs:
|
|
31
|
+
try:
|
|
32
|
+
result = client.jobs.wait(job.id, timeout=1800)
|
|
33
|
+
except HyperSRError as exc:
|
|
34
|
+
print(f"{job.id}: {exc}")
|
|
35
|
+
continue
|
|
36
|
+
if result.status == "completed":
|
|
37
|
+
print(f"{job.id}: completed; retrieve its four output roles")
|
|
38
|
+
elif result.status == "cancelled":
|
|
39
|
+
print(f"{job.id}: cancelled; no output download attempted")
|
|
40
|
+
else:
|
|
41
|
+
print(f"{job.id}: failed: {result.error_code}: {result.error_message}")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
if __name__ == "__main__":
|
|
45
|
+
main()
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Quote, explicitly submit, poll, and download one HyperSR product bundle."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from uuid import uuid4
|
|
7
|
+
|
|
8
|
+
from hypersr import HyperSR, HyperSRError
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def main() -> None:
|
|
12
|
+
api_key = os.environ["HYPERSR_API_KEY"]
|
|
13
|
+
scene_id = os.environ["HYPERSR_SCENE_ID"]
|
|
14
|
+
bbox = tuple(json.loads(os.environ["HYPERSR_BBOX"]))
|
|
15
|
+
if len(bbox) != 4:
|
|
16
|
+
raise ValueError("HYPERSR_BBOX must be a JSON array of four WGS84 coordinates")
|
|
17
|
+
base_url = os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1")
|
|
18
|
+
with HyperSR(api_key, base_url=base_url) as client:
|
|
19
|
+
model = next(item for item in client.models() if item.slug == "hypersr_v1" and item.enabled)
|
|
20
|
+
quote = client.jobs.quote(
|
|
21
|
+
scene_id=scene_id,
|
|
22
|
+
bbox=bbox,
|
|
23
|
+
model=model.slug,
|
|
24
|
+
)
|
|
25
|
+
print(f"quoted {quote.required_credits} internal credit units")
|
|
26
|
+
try:
|
|
27
|
+
job = client.jobs.submit(quote_id=quote.id, idempotency_key=f"quickstart-{uuid4()}")
|
|
28
|
+
result = client.jobs.wait(job.id, timeout=1800)
|
|
29
|
+
except HyperSRError as exc:
|
|
30
|
+
print(f"request failed: {exc}")
|
|
31
|
+
return
|
|
32
|
+
if result.status != "completed":
|
|
33
|
+
print(f"job {result.id} ended as {result.status}: {result.error_message or ''}")
|
|
34
|
+
return
|
|
35
|
+
output_dir = Path("hypersr-output")
|
|
36
|
+
output_dir.mkdir(exist_ok=True)
|
|
37
|
+
for role in ("reflectance", "scl", "cloud_mask", "provenance"):
|
|
38
|
+
suffix = ".json" if role == "provenance" else ".tif"
|
|
39
|
+
path = client.jobs.download_role(result.id, role, output_dir / f"{role}{suffix}")
|
|
40
|
+
print(f"downloaded {role}: {path}")
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
if __name__ == "__main__":
|
|
44
|
+
main()
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Inspect a downloaded reflectance COG (install ``hypersr[rasterio]`` first)."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
import rasterio
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def main() -> None:
|
|
10
|
+
path = Path(os.environ.get("HYPERSR_REFLECTANCE_PATH", "hypersr-output/reflectance.tif"))
|
|
11
|
+
with rasterio.open(path) as dataset:
|
|
12
|
+
print(dataset.crs, dataset.transform, dataset.count, dataset.res)
|
|
13
|
+
print(dataset.descriptions)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
if __name__ == "__main__":
|
|
17
|
+
main()
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "hypersr"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Typed Python client for the HyperSR multispectral super-resolution API."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "LicenseRef-Proprietary"
|
|
12
|
+
authors = [{ name = "Hyperalis Labs" }]
|
|
13
|
+
keywords = ["satellite", "sentinel-2", "geospatial", "super-resolution", "api-client"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Typing :: Typed",
|
|
26
|
+
]
|
|
27
|
+
dependencies = [
|
|
28
|
+
"httpx>=0.27,<1",
|
|
29
|
+
"pydantic>=2.7,<3",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
dev = [
|
|
34
|
+
"mypy>=1.11,<2",
|
|
35
|
+
"pytest>=9.0.3,<10",
|
|
36
|
+
"pytest-cov>=5,<6",
|
|
37
|
+
"ruff>=0.6,<1",
|
|
38
|
+
]
|
|
39
|
+
rasterio = ["rasterio>=1.3,<2"]
|
|
40
|
+
|
|
41
|
+
[project.urls]
|
|
42
|
+
Homepage = "https://hypersr.com"
|
|
43
|
+
Documentation = "https://github.com/HyperalisLabs/hypersr/blob/main/packages/sdk-python/README.md"
|
|
44
|
+
Repository = "https://github.com/HyperalisLabs/hypersr"
|
|
45
|
+
Issues = "https://github.com/HyperalisLabs/hypersr/issues"
|
|
46
|
+
|
|
47
|
+
[tool.hatch.version]
|
|
48
|
+
path = "src/hypersr/_version.py"
|
|
49
|
+
|
|
50
|
+
[tool.hatch.build.targets.sdist]
|
|
51
|
+
include = ["/src/hypersr", "/tests", "/examples", "/README.md", "/CHANGELOG.md", "/pyproject.toml", "/uv.lock"]
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.wheel]
|
|
54
|
+
packages = ["src/hypersr"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
addopts = "--strict-markers"
|
|
59
|
+
|
|
60
|
+
[tool.ruff]
|
|
61
|
+
target-version = "py311"
|
|
62
|
+
line-length = 100
|
|
63
|
+
src = ["src", "tests"]
|
|
64
|
+
|
|
65
|
+
[tool.ruff.lint]
|
|
66
|
+
select = ["E", "F", "I", "UP", "B", "SIM"]
|
|
67
|
+
|
|
68
|
+
[tool.mypy]
|
|
69
|
+
python_version = "3.11"
|
|
70
|
+
strict = true
|
|
71
|
+
packages = ["hypersr"]
|
|
72
|
+
mypy_path = "src"
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""Public API for the HyperSR Python SDK."""
|
|
2
|
+
|
|
3
|
+
from ._version import __version__
|
|
4
|
+
from .client import HyperSR
|
|
5
|
+
from .exceptions import (
|
|
6
|
+
APIError,
|
|
7
|
+
AuthenticationError,
|
|
8
|
+
ConflictError,
|
|
9
|
+
HyperSRError,
|
|
10
|
+
NotFoundError,
|
|
11
|
+
RateLimitError,
|
|
12
|
+
RequestError,
|
|
13
|
+
TimeoutError,
|
|
14
|
+
ValidationError,
|
|
15
|
+
)
|
|
16
|
+
from .models import (
|
|
17
|
+
Account,
|
|
18
|
+
AccountSummary,
|
|
19
|
+
APIKey,
|
|
20
|
+
APIKeyCreated,
|
|
21
|
+
BillingPackage,
|
|
22
|
+
CheckoutSession,
|
|
23
|
+
CreditBalance,
|
|
24
|
+
CreditTransaction,
|
|
25
|
+
Job,
|
|
26
|
+
JobOutput,
|
|
27
|
+
Model,
|
|
28
|
+
NotificationPreferences,
|
|
29
|
+
Page,
|
|
30
|
+
Payment,
|
|
31
|
+
Quote,
|
|
32
|
+
SavedAOI,
|
|
33
|
+
SceneSearchResponse,
|
|
34
|
+
SceneSearchResult,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"__version__",
|
|
39
|
+
"APIError",
|
|
40
|
+
"APIKey",
|
|
41
|
+
"APIKeyCreated",
|
|
42
|
+
"Account",
|
|
43
|
+
"AccountSummary",
|
|
44
|
+
"AuthenticationError",
|
|
45
|
+
"BillingPackage",
|
|
46
|
+
"ConflictError",
|
|
47
|
+
"CheckoutSession",
|
|
48
|
+
"CreditBalance",
|
|
49
|
+
"CreditTransaction",
|
|
50
|
+
"HyperSR",
|
|
51
|
+
"HyperSRError",
|
|
52
|
+
"Job",
|
|
53
|
+
"JobOutput",
|
|
54
|
+
"Model",
|
|
55
|
+
"NotFoundError",
|
|
56
|
+
"NotificationPreferences",
|
|
57
|
+
"Page",
|
|
58
|
+
"Payment",
|
|
59
|
+
"Quote",
|
|
60
|
+
"RateLimitError",
|
|
61
|
+
"RequestError",
|
|
62
|
+
"SavedAOI",
|
|
63
|
+
"SceneSearchResponse",
|
|
64
|
+
"SceneSearchResult",
|
|
65
|
+
"TimeoutError",
|
|
66
|
+
"ValidationError",
|
|
67
|
+
]
|