qforge-sdk 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.
- qforge_sdk-0.1.0/.github/workflows/ci.yml +24 -0
- qforge_sdk-0.1.0/.github/workflows/release.yml +24 -0
- qforge_sdk-0.1.0/.gitignore +8 -0
- qforge_sdk-0.1.0/LICENSE +21 -0
- qforge_sdk-0.1.0/PKG-INFO +144 -0
- qforge_sdk-0.1.0/README.md +114 -0
- qforge_sdk-0.1.0/pyproject.toml +55 -0
- qforge_sdk-0.1.0/src/qforge/__init__.py +45 -0
- qforge_sdk-0.1.0/src/qforge/_http.py +123 -0
- qforge_sdk-0.1.0/src/qforge/client.py +195 -0
- qforge_sdk-0.1.0/src/qforge/errors.py +77 -0
- qforge_sdk-0.1.0/src/qforge/models.py +302 -0
- qforge_sdk-0.1.0/src/qforge/py.typed +0 -0
- qforge_sdk-0.1.0/tests/__init__.py +0 -0
- qforge_sdk-0.1.0/tests/conftest.py +133 -0
- qforge_sdk-0.1.0/tests/test_client.py +97 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
fail-fast: false
|
|
13
|
+
matrix:
|
|
14
|
+
python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
- uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: ${{ matrix.python }}
|
|
20
|
+
- run: pip install -e ".[dev]"
|
|
21
|
+
- run: ruff check .
|
|
22
|
+
- run: mypy src
|
|
23
|
+
if: matrix.python != '3.9'
|
|
24
|
+
- run: pytest -q
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Push a tag like v0.1.0 to publish to PyPI. Uses trusted publishing: on
|
|
4
|
+
# pypi.org, add this repository and this workflow as a trusted publisher for
|
|
5
|
+
# the project "qforge-sdk" (no token needed).
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
tags: ["v*"]
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
publish:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
environment: pypi
|
|
14
|
+
permissions:
|
|
15
|
+
contents: read
|
|
16
|
+
id-token: write
|
|
17
|
+
steps:
|
|
18
|
+
- uses: actions/checkout@v4
|
|
19
|
+
- uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: "3.12"
|
|
22
|
+
- run: pip install build
|
|
23
|
+
- run: python -m build
|
|
24
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
qforge_sdk-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 QForge
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: qforge-sdk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for QForge: generate crystal structures with target properties.
|
|
5
|
+
Project-URL: Documentation, https://github.com/Hilbert-Forge/QForge-python#readme
|
|
6
|
+
Author: QForge
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: ase,crystal structures,generative models,materials,pymatgen
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Requires-Dist: httpx>=0.25
|
|
18
|
+
Provides-Extra: all
|
|
19
|
+
Requires-Dist: ase>=3.22; extra == 'all'
|
|
20
|
+
Requires-Dist: pymatgen>=2023.1; extra == 'all'
|
|
21
|
+
Provides-Extra: ase
|
|
22
|
+
Requires-Dist: ase>=3.22; extra == 'ase'
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
26
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
27
|
+
Provides-Extra: pymatgen
|
|
28
|
+
Requires-Dist: pymatgen>=2023.1; extra == 'pymatgen'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# qforge-sdk
|
|
32
|
+
|
|
33
|
+
Python client for QForge: generate crystal structures with the properties you want, then work with them in pymatgen or ASE.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install qforge-sdk # the client
|
|
37
|
+
pip install "qforge-sdk[pymatgen]" # + Material.to_pymatgen()
|
|
38
|
+
pip install "qforge-sdk[ase]" # + Material.to_ase()
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The package installs as `qforge-sdk` and imports as `qforge`.
|
|
42
|
+
|
|
43
|
+
## Setup
|
|
44
|
+
|
|
45
|
+
1. In QForge, open **Developers → API keys** and create a key.
|
|
46
|
+
- Give it only the scopes it needs. "Run" spends credits.
|
|
47
|
+
- Set a monthly credit cap.
|
|
48
|
+
2. Set two environment variables:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
export QFORGE_API_KEY=qfk_…
|
|
52
|
+
export QFORGE_URL=https://your-qforge # the address you open QForge at
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
You can also pass them in code: `QForge(api_key=..., base_url=...)`.
|
|
56
|
+
|
|
57
|
+
## Generate
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from qforge import QForge
|
|
61
|
+
|
|
62
|
+
qf = QForge()
|
|
63
|
+
|
|
64
|
+
job = qf.generate(
|
|
65
|
+
{"band_gap": 3.0}, # property ids: Developers → Properties
|
|
66
|
+
elements=["Fe", "O"],
|
|
67
|
+
n_structures=8,
|
|
68
|
+
model="frost", # "auto", a model id, or pinned: "frost@1"
|
|
69
|
+
check_novelty=True,
|
|
70
|
+
)
|
|
71
|
+
job.wait(on_progress=lambda j: print(j.status, j.progress))
|
|
72
|
+
|
|
73
|
+
for m in job.materials:
|
|
74
|
+
print(m.formula, m.space_group, m.e_above_hull, m.novelty)
|
|
75
|
+
m.save() # FeO.cif
|
|
76
|
+
s = m.to_pymatgen() # pymatgen Structure
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The **code builder** in QForge (Developers → Code builder) writes this call for any query you build in the browser.
|
|
80
|
+
|
|
81
|
+
## Campaigns
|
|
82
|
+
|
|
83
|
+
A campaign keeps generating until it finds enough materials that meet a goal, or it hits a credit or batch limit.
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
c = qf.campaign(
|
|
87
|
+
"Wide-gap oxides",
|
|
88
|
+
{"band_gap": 4.0},
|
|
89
|
+
goal={"count": 5, "novel": True, "stable": True},
|
|
90
|
+
max_credits=30,
|
|
91
|
+
max_batches=10,
|
|
92
|
+
)
|
|
93
|
+
c.wait()
|
|
94
|
+
print(c.status, [m.formula for m in c.materials])
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Library and DFT
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
for m in qf.library(search="Fe-O", favourite=True):
|
|
101
|
+
print(m.formula, m.library_id)
|
|
102
|
+
|
|
103
|
+
check = qf.verify_dft(m, max_credits=20) # starts at the quoted price, never above 20
|
|
104
|
+
check.wait() # DFT takes hours; poll every minute
|
|
105
|
+
print(check.verdict, check.e_above_hull)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Errors and retries
|
|
109
|
+
|
|
110
|
+
- **Every API error is a `qforge.QForgeError`**, with `.status`, `.code` and `.request_id`. Quote the request id to support.
|
|
111
|
+
- **Specific error classes:**
|
|
112
|
+
- `AuthenticationError` (401)
|
|
113
|
+
- `InsufficientCredits` (402)
|
|
114
|
+
- `PermissionDenied` (403, the key lacks a scope)
|
|
115
|
+
- `NotFound` (404)
|
|
116
|
+
- `Conflict` (409)
|
|
117
|
+
- `RateLimited` (429)
|
|
118
|
+
- `ServerError` (5xx)
|
|
119
|
+
- `JobFailed` (a run, campaign or DFT check failed; failed runs are refunded)
|
|
120
|
+
- `Timeout` (`wait(timeout=…)` ran out)
|
|
121
|
+
- **Automatic retries:** busy (429) and unavailable (502, 503, 504) responses are retried with backoff, honouring `Retry-After`.
|
|
122
|
+
- **No double charges:** calls that spend credits send an `Idempotency-Key`, so a retry is never charged twice.
|
|
123
|
+
|
|
124
|
+
## Development
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
128
|
+
.venv/bin/pytest
|
|
129
|
+
.venv/bin/ruff check . && .venv/bin/mypy src
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The tests use an in-memory fake server and never call a real one.
|
|
133
|
+
|
|
134
|
+
### Releasing
|
|
135
|
+
|
|
136
|
+
1. Bump `version` in `pyproject.toml` and `src/qforge/__init__.py`.
|
|
137
|
+
2. Tag `vX.Y.Z` and push the tag.
|
|
138
|
+
3. GitHub Actions builds the package and publishes it to PyPI. This uses trusted publishing: add this repo and the `release.yml` workflow as a trusted publisher for `qforge-sdk` on PyPI first.
|
|
139
|
+
|
|
140
|
+
Until it's on PyPI, install from the repo:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pip install "git+https://github.com/Hilbert-Forge/QForge-python.git"
|
|
144
|
+
```
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# qforge-sdk
|
|
2
|
+
|
|
3
|
+
Python client for QForge: generate crystal structures with the properties you want, then work with them in pymatgen or ASE.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pip install qforge-sdk # the client
|
|
7
|
+
pip install "qforge-sdk[pymatgen]" # + Material.to_pymatgen()
|
|
8
|
+
pip install "qforge-sdk[ase]" # + Material.to_ase()
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The package installs as `qforge-sdk` and imports as `qforge`.
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
1. In QForge, open **Developers → API keys** and create a key.
|
|
16
|
+
- Give it only the scopes it needs. "Run" spends credits.
|
|
17
|
+
- Set a monthly credit cap.
|
|
18
|
+
2. Set two environment variables:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
export QFORGE_API_KEY=qfk_…
|
|
22
|
+
export QFORGE_URL=https://your-qforge # the address you open QForge at
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
You can also pass them in code: `QForge(api_key=..., base_url=...)`.
|
|
26
|
+
|
|
27
|
+
## Generate
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from qforge import QForge
|
|
31
|
+
|
|
32
|
+
qf = QForge()
|
|
33
|
+
|
|
34
|
+
job = qf.generate(
|
|
35
|
+
{"band_gap": 3.0}, # property ids: Developers → Properties
|
|
36
|
+
elements=["Fe", "O"],
|
|
37
|
+
n_structures=8,
|
|
38
|
+
model="frost", # "auto", a model id, or pinned: "frost@1"
|
|
39
|
+
check_novelty=True,
|
|
40
|
+
)
|
|
41
|
+
job.wait(on_progress=lambda j: print(j.status, j.progress))
|
|
42
|
+
|
|
43
|
+
for m in job.materials:
|
|
44
|
+
print(m.formula, m.space_group, m.e_above_hull, m.novelty)
|
|
45
|
+
m.save() # FeO.cif
|
|
46
|
+
s = m.to_pymatgen() # pymatgen Structure
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The **code builder** in QForge (Developers → Code builder) writes this call for any query you build in the browser.
|
|
50
|
+
|
|
51
|
+
## Campaigns
|
|
52
|
+
|
|
53
|
+
A campaign keeps generating until it finds enough materials that meet a goal, or it hits a credit or batch limit.
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
c = qf.campaign(
|
|
57
|
+
"Wide-gap oxides",
|
|
58
|
+
{"band_gap": 4.0},
|
|
59
|
+
goal={"count": 5, "novel": True, "stable": True},
|
|
60
|
+
max_credits=30,
|
|
61
|
+
max_batches=10,
|
|
62
|
+
)
|
|
63
|
+
c.wait()
|
|
64
|
+
print(c.status, [m.formula for m in c.materials])
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Library and DFT
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
for m in qf.library(search="Fe-O", favourite=True):
|
|
71
|
+
print(m.formula, m.library_id)
|
|
72
|
+
|
|
73
|
+
check = qf.verify_dft(m, max_credits=20) # starts at the quoted price, never above 20
|
|
74
|
+
check.wait() # DFT takes hours; poll every minute
|
|
75
|
+
print(check.verdict, check.e_above_hull)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Errors and retries
|
|
79
|
+
|
|
80
|
+
- **Every API error is a `qforge.QForgeError`**, with `.status`, `.code` and `.request_id`. Quote the request id to support.
|
|
81
|
+
- **Specific error classes:**
|
|
82
|
+
- `AuthenticationError` (401)
|
|
83
|
+
- `InsufficientCredits` (402)
|
|
84
|
+
- `PermissionDenied` (403, the key lacks a scope)
|
|
85
|
+
- `NotFound` (404)
|
|
86
|
+
- `Conflict` (409)
|
|
87
|
+
- `RateLimited` (429)
|
|
88
|
+
- `ServerError` (5xx)
|
|
89
|
+
- `JobFailed` (a run, campaign or DFT check failed; failed runs are refunded)
|
|
90
|
+
- `Timeout` (`wait(timeout=…)` ran out)
|
|
91
|
+
- **Automatic retries:** busy (429) and unavailable (502, 503, 504) responses are retried with backoff, honouring `Retry-After`.
|
|
92
|
+
- **No double charges:** calls that spend credits send an `Idempotency-Key`, so a retry is never charged twice.
|
|
93
|
+
|
|
94
|
+
## Development
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
|
98
|
+
.venv/bin/pytest
|
|
99
|
+
.venv/bin/ruff check . && .venv/bin/mypy src
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The tests use an in-memory fake server and never call a real one.
|
|
103
|
+
|
|
104
|
+
### Releasing
|
|
105
|
+
|
|
106
|
+
1. Bump `version` in `pyproject.toml` and `src/qforge/__init__.py`.
|
|
107
|
+
2. Tag `vX.Y.Z` and push the tag.
|
|
108
|
+
3. GitHub Actions builds the package and publishes it to PyPI. This uses trusted publishing: add this repo and the `release.yml` workflow as a trusted publisher for `qforge-sdk` on PyPI first.
|
|
109
|
+
|
|
110
|
+
Until it's on PyPI, install from the repo:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
pip install "git+https://github.com/Hilbert-Forge/QForge-python.git"
|
|
114
|
+
```
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.24"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "qforge-sdk"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Python client for QForge: generate crystal structures with target properties."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "QForge" }]
|
|
13
|
+
keywords = ["materials", "crystal structures", "generative models", "pymatgen", "ase"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Science/Research",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Topic :: Scientific/Engineering :: Chemistry",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Physics",
|
|
21
|
+
]
|
|
22
|
+
dependencies = ["httpx>=0.25"]
|
|
23
|
+
|
|
24
|
+
[project.optional-dependencies]
|
|
25
|
+
pymatgen = ["pymatgen>=2023.1"]
|
|
26
|
+
ase = ["ase>=3.22"]
|
|
27
|
+
all = ["pymatgen>=2023.1", "ase>=3.22"]
|
|
28
|
+
dev = ["pytest>=7", "ruff>=0.5", "mypy>=1.8"]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Documentation = "https://github.com/Hilbert-Forge/QForge-python#readme"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/qforge"]
|
|
35
|
+
|
|
36
|
+
[tool.pytest.ini_options]
|
|
37
|
+
testpaths = ["tests"]
|
|
38
|
+
|
|
39
|
+
[tool.ruff]
|
|
40
|
+
line-length = 110
|
|
41
|
+
target-version = "py39"
|
|
42
|
+
|
|
43
|
+
[tool.ruff.lint]
|
|
44
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
45
|
+
|
|
46
|
+
[tool.ruff.lint.per-file-ignores]
|
|
47
|
+
"tests/*" = ["E501"]
|
|
48
|
+
|
|
49
|
+
[tool.mypy]
|
|
50
|
+
strict = true
|
|
51
|
+
python_version = "3.10"
|
|
52
|
+
|
|
53
|
+
[[tool.mypy.overrides]]
|
|
54
|
+
module = ["pymatgen.*", "ase.*"]
|
|
55
|
+
ignore_missing_imports = true
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""QForge: generate crystal structures with target properties, from Python.
|
|
2
|
+
|
|
3
|
+
from qforge import QForge
|
|
4
|
+
|
|
5
|
+
qf = QForge() # QFORGE_API_KEY and QFORGE_URL from the environment
|
|
6
|
+
job = qf.generate({"band_gap": 2.5}, elements=["Fe", "O"], n_structures=4)
|
|
7
|
+
for m in job.wait().materials:
|
|
8
|
+
print(m.formula, m.e_above_hull)
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
__version__ = "0.1.0"
|
|
12
|
+
|
|
13
|
+
from .client import QForge # noqa: E402
|
|
14
|
+
from .errors import ( # noqa: E402
|
|
15
|
+
AuthenticationError,
|
|
16
|
+
Conflict,
|
|
17
|
+
InsufficientCredits,
|
|
18
|
+
JobFailed,
|
|
19
|
+
NotFound,
|
|
20
|
+
PermissionDenied,
|
|
21
|
+
QForgeError,
|
|
22
|
+
RateLimited,
|
|
23
|
+
ServerError,
|
|
24
|
+
Timeout,
|
|
25
|
+
)
|
|
26
|
+
from .models import Campaign, DftCheck, Job, Material # noqa: E402
|
|
27
|
+
|
|
28
|
+
__all__ = [
|
|
29
|
+
"QForge",
|
|
30
|
+
"Job",
|
|
31
|
+
"Material",
|
|
32
|
+
"Campaign",
|
|
33
|
+
"DftCheck",
|
|
34
|
+
"QForgeError",
|
|
35
|
+
"AuthenticationError",
|
|
36
|
+
"PermissionDenied",
|
|
37
|
+
"InsufficientCredits",
|
|
38
|
+
"NotFound",
|
|
39
|
+
"Conflict",
|
|
40
|
+
"RateLimited",
|
|
41
|
+
"ServerError",
|
|
42
|
+
"JobFailed",
|
|
43
|
+
"Timeout",
|
|
44
|
+
"__version__",
|
|
45
|
+
]
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
"""HTTP layer: auth, retries with backoff, idempotency keys, error mapping."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import random
|
|
6
|
+
import time
|
|
7
|
+
import uuid
|
|
8
|
+
from collections.abc import Iterator
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
import httpx
|
|
12
|
+
|
|
13
|
+
from . import __version__
|
|
14
|
+
from .errors import QForgeError, error_for
|
|
15
|
+
|
|
16
|
+
RETRY_STATUSES = {429, 502, 503, 504}
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class Http:
|
|
20
|
+
def __init__(
|
|
21
|
+
self,
|
|
22
|
+
base_url: str,
|
|
23
|
+
api_key: str,
|
|
24
|
+
*,
|
|
25
|
+
timeout: float = 30.0,
|
|
26
|
+
max_retries: int = 3,
|
|
27
|
+
transport: httpx.BaseTransport | None = None,
|
|
28
|
+
) -> None:
|
|
29
|
+
self.max_retries = max_retries
|
|
30
|
+
self._client = httpx.Client(
|
|
31
|
+
base_url=base_url.rstrip("/") + "/api",
|
|
32
|
+
timeout=timeout,
|
|
33
|
+
transport=transport,
|
|
34
|
+
headers={
|
|
35
|
+
"Authorization": f"Bearer {api_key}",
|
|
36
|
+
"User-Agent": f"qforge-sdk-python/{__version__}",
|
|
37
|
+
"Accept": "application/json",
|
|
38
|
+
},
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
def close(self) -> None:
|
|
42
|
+
self._client.close()
|
|
43
|
+
|
|
44
|
+
def request(
|
|
45
|
+
self,
|
|
46
|
+
method: str,
|
|
47
|
+
path: str,
|
|
48
|
+
*,
|
|
49
|
+
params: dict[str, Any] | None = None,
|
|
50
|
+
json: Any = None,
|
|
51
|
+
idempotent: bool = False,
|
|
52
|
+
) -> Any:
|
|
53
|
+
"""One API call. POSTs that spend credits send an Idempotency-Key, kept
|
|
54
|
+
across retries, so a retry never charges twice."""
|
|
55
|
+
headers: dict[str, str] = {"X-Request-ID": f"py-{uuid.uuid4().hex[:12]}"}
|
|
56
|
+
if idempotent:
|
|
57
|
+
headers["Idempotency-Key"] = uuid.uuid4().hex
|
|
58
|
+
params = {k: v for k, v in (params or {}).items() if v is not None}
|
|
59
|
+
attempt = 0
|
|
60
|
+
while True:
|
|
61
|
+
try:
|
|
62
|
+
res = self._client.request(method, path, params=params, json=json, headers=headers)
|
|
63
|
+
except httpx.TransportError as exc:
|
|
64
|
+
if attempt >= self.max_retries:
|
|
65
|
+
raise QForgeError(f"Couldn't reach QForge: {exc}") from exc
|
|
66
|
+
attempt += 1
|
|
67
|
+
time.sleep(_backoff(attempt))
|
|
68
|
+
continue
|
|
69
|
+
if res.status_code in RETRY_STATUSES and attempt < self.max_retries:
|
|
70
|
+
attempt += 1
|
|
71
|
+
time.sleep(_retry_after(res) or _backoff(attempt))
|
|
72
|
+
continue
|
|
73
|
+
return _result(res)
|
|
74
|
+
|
|
75
|
+
def get(self, path: str, **params: Any) -> Any:
|
|
76
|
+
return self.request("GET", path, params=params)
|
|
77
|
+
|
|
78
|
+
def pages(
|
|
79
|
+
self, path: str, params: dict[str, Any] | None = None, page_size: int = 50
|
|
80
|
+
) -> Iterator[dict[str, Any]]:
|
|
81
|
+
"""Every item of a paginated list, fetching pages as needed."""
|
|
82
|
+
page = 1
|
|
83
|
+
while True:
|
|
84
|
+
data = self.get(path, **(params or {}), page=page, page_size=page_size)
|
|
85
|
+
items = data.get("results", []) if isinstance(data, dict) else data
|
|
86
|
+
yield from items
|
|
87
|
+
if not isinstance(data, dict) or not data.get("next") or not items:
|
|
88
|
+
return
|
|
89
|
+
page += 1
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _backoff(attempt: int) -> float:
|
|
93
|
+
return min(30.0, 0.5 * 2.0**attempt) * (0.75 + random.random() / 2)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _retry_after(res: httpx.Response) -> float | None:
|
|
97
|
+
value = res.headers.get("Retry-After")
|
|
98
|
+
try:
|
|
99
|
+
return min(60.0, float(str(value))) if value else None
|
|
100
|
+
except ValueError:
|
|
101
|
+
return None
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _result(res: httpx.Response) -> Any:
|
|
105
|
+
if res.status_code == 204 or not res.content:
|
|
106
|
+
if res.is_success:
|
|
107
|
+
return None
|
|
108
|
+
try:
|
|
109
|
+
body = res.json()
|
|
110
|
+
except ValueError:
|
|
111
|
+
body = res.text
|
|
112
|
+
if res.is_success:
|
|
113
|
+
return body
|
|
114
|
+
detail = body.get("detail") if isinstance(body, dict) else None
|
|
115
|
+
code = body.get("code") if isinstance(body, dict) else None
|
|
116
|
+
message = detail if isinstance(detail, str) else f"HTTP {res.status_code}"
|
|
117
|
+
raise error_for(res.status_code)(
|
|
118
|
+
message,
|
|
119
|
+
status=res.status_code,
|
|
120
|
+
code=code,
|
|
121
|
+
request_id=res.headers.get("X-Request-ID"),
|
|
122
|
+
body=body,
|
|
123
|
+
)
|