iota-hub 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.
- iota_hub-0.1.0/.gitignore +8 -0
- iota_hub-0.1.0/LICENSE +21 -0
- iota_hub-0.1.0/PKG-INFO +388 -0
- iota_hub-0.1.0/README.md +339 -0
- iota_hub-0.1.0/pyproject.toml +73 -0
- iota_hub-0.1.0/src/iota_hub/__init__.py +63 -0
- iota_hub-0.1.0/src/iota_hub/_http.py +222 -0
- iota_hub-0.1.0/src/iota_hub/_term.py +109 -0
- iota_hub-0.1.0/src/iota_hub/_version.py +8 -0
- iota_hub-0.1.0/src/iota_hub/cli.py +1944 -0
- iota_hub-0.1.0/src/iota_hub/client.py +478 -0
- iota_hub-0.1.0/src/iota_hub/config.py +285 -0
- iota_hub-0.1.0/src/iota_hub/errors.py +165 -0
- iota_hub-0.1.0/src/iota_hub/files.py +334 -0
- iota_hub-0.1.0/src/iota_hub/guide.md +400 -0
- iota_hub-0.1.0/src/iota_hub/models.py +469 -0
- iota_hub-0.1.0/src/iota_hub/workflow.py +691 -0
iota_hub-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Skyler Carlson
|
|
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.
|
iota_hub-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: iota-hub
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Client library and CLI for the IOTA Hub public API (occultation observation submission)
|
|
5
|
+
Project-URL: Homepage, https://github.com/skycarl/iota-hub-python
|
|
6
|
+
Project-URL: Documentation, https://iota-hub.com/developers
|
|
7
|
+
Project-URL: Source, https://github.com/skycarl/iota-hub-python
|
|
8
|
+
Author: IOTA Hub
|
|
9
|
+
License: MIT License
|
|
10
|
+
|
|
11
|
+
Copyright (c) 2026 Skyler Carlson
|
|
12
|
+
|
|
13
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
+
in the Software without restriction, including without limitation the rights
|
|
16
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
+
furnished to do so, subject to the following conditions:
|
|
19
|
+
|
|
20
|
+
The above copyright notice and this permission notice shall be included in all
|
|
21
|
+
copies or substantial portions of the Software.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
+
SOFTWARE.
|
|
30
|
+
License-File: LICENSE
|
|
31
|
+
Keywords: api-client,astronomy,cli,iota,occultation
|
|
32
|
+
Classifier: Development Status :: 3 - Alpha
|
|
33
|
+
Classifier: Environment :: Console
|
|
34
|
+
Classifier: Intended Audience :: Science/Research
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Programming Language :: Python :: 3
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
41
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
42
|
+
Requires-Python: >=3.10
|
|
43
|
+
Requires-Dist: httpx>=0.27
|
|
44
|
+
Requires-Dist: platformdirs>=4
|
|
45
|
+
Requires-Dist: pydantic>=2.6
|
|
46
|
+
Requires-Dist: tomli>=2; python_version < '3.11'
|
|
47
|
+
Requires-Dist: typer>=0.12
|
|
48
|
+
Description-Content-Type: text/markdown
|
|
49
|
+
|
|
50
|
+
# iota-hub
|
|
51
|
+
|
|
52
|
+
[IOTA Hub](https://iota-hub.com) is where observers of asteroid occultations send
|
|
53
|
+
their observations to IOTA: a report, a light curve, an instrument log, and
|
|
54
|
+
optionally a VizieR file, checked and reviewed in one place instead of by email.
|
|
55
|
+
`iota-hub` is the command-line tool and Python library for its public API v1 —
|
|
56
|
+
it creates the draft, uploads the files, runs the observer checks, and submits
|
|
57
|
+
when the checks are clean. It is meant for observers who want their submission
|
|
58
|
+
scripted or reduced to one command, and for AI agents acting on an observer's
|
|
59
|
+
behalf. There are three ways in, in the order you should try them: **the CLI
|
|
60
|
+
first**, the **Python library** second when you are building something of your
|
|
61
|
+
own, and the **raw HTTP API** last, documented at
|
|
62
|
+
<https://iota-hub.com/developers/api>.
|
|
63
|
+
|
|
64
|
+
## Quickstart (CLI)
|
|
65
|
+
|
|
66
|
+
No install needed if you have [uv](https://docs.astral.sh/uv/):
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
uvx iota-hub auth login # paste your API key when prompted
|
|
70
|
+
cd 20180305_9721_Doty_Observer_POS
|
|
71
|
+
uvx iota-hub submit
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Prefer it on your PATH: `uv tool install iota-hub`, or `pipx install iota-hub`,
|
|
75
|
+
and then run `iota-hub` instead of `uvx iota-hub`.
|
|
76
|
+
|
|
77
|
+
A clean run looks about like this (progress on stderr, the result on stdout):
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
Creating draft (4 files)...
|
|
81
|
+
Uploading report (1/4)...
|
|
82
|
+
Uploading lightcurve (2/4)...
|
|
83
|
+
Uploading log (3/4)...
|
|
84
|
+
Uploading attachment field_notes.png (4/4)...
|
|
85
|
+
Finalizing draft...
|
|
86
|
+
Waiting for checks...
|
|
87
|
+
|
|
88
|
+
Submitted obs_01HZY4A1K2QX
|
|
89
|
+
report 20180305_9721_Doty_Observer_POS.xlsx
|
|
90
|
+
lightcurve 20180305_9721_Doty_Observer_POS.csv
|
|
91
|
+
log 20180305_9721_Doty_Observer_POS_pyote_log.txt
|
|
92
|
+
attachment field_notes.png
|
|
93
|
+
checks complete, 0 open findings
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`submit` is the whole job: it creates a draft, uploads each file straight to
|
|
97
|
+
storage (files never travel through the API), finalizes, waits for the observer
|
|
98
|
+
check run, and submits the observation when — and only when — the draft comes
|
|
99
|
+
back `ready`. If the run leaves open findings, or something required is still
|
|
100
|
+
missing, it does not submit: the draft stays in your Drafts, the findings are
|
|
101
|
+
printed with the exact commands that resolve them, along with the draft's
|
|
102
|
+
`Web:` link to finish it in the browser, and the exit code is `4`. Nothing is
|
|
103
|
+
ever guessed and nothing is ever thrown away — a draft it could not submit is
|
|
104
|
+
recoverable in the web app. Submitting something that is already submitted is
|
|
105
|
+
not an error either: it reports `submitted`.
|
|
106
|
+
|
|
107
|
+
**Skipped checks are said out loud.** A check that could not run never blocks
|
|
108
|
+
submit, so after "Waiting for checks..." `submit` prints a `WARNING` block on
|
|
109
|
+
stderr naming every skipped check and why. The usual one is check 11 (near the
|
|
110
|
+
predicted time), which needs an Occult Watcher Cloud link: the Hub matches the
|
|
111
|
+
OWC event itself after the upload, and when it cannot choose (several
|
|
112
|
+
candidates, a mismatch, nothing found) the block lists the candidates and the
|
|
113
|
+
commands to settle it — `iota-hub drafts owc <id> --pick <owc_event_id>`,
|
|
114
|
+
`--link <url>` or `--none`. Use `submit --draft` if you want to settle it
|
|
115
|
+
before submitting.
|
|
116
|
+
|
|
117
|
+
Useful variations:
|
|
118
|
+
|
|
119
|
+
- `iota-hub submit --draft` — do everything except the final submit, so you can
|
|
120
|
+
review it in the web app first.
|
|
121
|
+
- `iota-hub submit --dry-run` — print the slot mapping, the file sizes and the
|
|
122
|
+
target, and call nothing.
|
|
123
|
+
- `iota-hub submit --json` — one JSON document on stdout, for scripts and agents.
|
|
124
|
+
- `iota-hub submit --no-wait` — return after the upload with the draft id and
|
|
125
|
+
its `Web:` link; `--timeout S` changes how long it waits (default 10 minutes).
|
|
126
|
+
|
|
127
|
+
Not sure whether an earlier run already created the draft? Ask before creating
|
|
128
|
+
a second one — it finds your own draft or submission by what it observed, or
|
|
129
|
+
says whether the event exists:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
iota-hub observations check --asteroid-id 9721 --asteroid-name Doty \
|
|
133
|
+
--star-id 1234-56789 --date 2018-03-05
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Which file goes where
|
|
137
|
+
|
|
138
|
+
`submit` takes a directory (the current one by default) and maps its files onto
|
|
139
|
+
the five slots by rules only. The observer naming convention
|
|
140
|
+
(`YYYYMMDD_<number>_<name>_<lastname>_POS|NEG[-X]`, see
|
|
141
|
+
<https://iota-hub.com/data-submission>) already carries enough signal, so there
|
|
142
|
+
is no classification and no content sniffing:
|
|
143
|
+
|
|
144
|
+
| Slot | Rule | Required |
|
|
145
|
+
| ----------------- | -------------------------------------------------------- | -------- |
|
|
146
|
+
| `report` | exactly one `.xlsx` / `.xls`, or a Tangra `.json` report | yes |
|
|
147
|
+
| `lightcurve` | exactly one `.csv` | yes |
|
|
148
|
+
| `log` | exactly one `.txt` whose name contains `log` | yes |
|
|
149
|
+
| `vizier` | at most one `.dat` | no |
|
|
150
|
+
| `aperture_record` | at most one Tangra `.lc` or PyMovie `.pymovie` | no |
|
|
151
|
+
|
|
152
|
+
The listing is non-recursive and skips subdirectories and dotfiles; extensions
|
|
153
|
+
match case-insensitively, so `.CSV` is a light curve.
|
|
154
|
+
|
|
155
|
+
The NA spreadsheet is still the primary report; a folder holding both a
|
|
156
|
+
spreadsheet and a `.json` is ambiguous, so name the one you mean with
|
|
157
|
+
`--report`. The aperture record has its own slot (up to 500 MB), so it is not
|
|
158
|
+
an attachment.
|
|
159
|
+
|
|
160
|
+
Anything the rules do not claim — `field_notes.txt`, a PyOTE `.png` — is
|
|
161
|
+
uploaded as an **attachment**, just like the web app's
|
|
162
|
+
"Optional Attachments". The web app's limits apply, and are checked before
|
|
163
|
+
anything is created, so a folder that breaks one fails whole (exit code `2`)
|
|
164
|
+
with every offending file named:
|
|
165
|
+
|
|
166
|
+
- at most **25** attachments per observation,
|
|
167
|
+
- at most **50 MB** each,
|
|
168
|
+
- no executables or scripts (`.exe`, `.bat`, `.cmd`, `.sh`, `.ps1`, `.js`,
|
|
169
|
+
`.py`, `.php`, `.pl`, `.rb`, `.jar`, `.msi`, `.dll`, `.so`).
|
|
170
|
+
|
|
171
|
+
`--no-attachments` uploads only the five slots and lists the rest as **not
|
|
172
|
+
uploaded**; `--attach PATH` (repeatable) adds a file from outside the folder.
|
|
173
|
+
`--dry-run` shows the attachments too. Afterwards,
|
|
174
|
+
`iota-hub drafts files add <id> attachment <path>` adds one and
|
|
175
|
+
`iota-hub drafts files rm <id> attachment <attachment_id>` removes one (the ids
|
|
176
|
+
are in `iota-hub drafts show <id>`).
|
|
177
|
+
|
|
178
|
+
**Ambiguity is an error, never a guess.** Two candidates for one slot, or none
|
|
179
|
+
for a required one, stops the command with the names of the files involved and
|
|
180
|
+
the flag that settles it. The overrides are `--report PATH`,
|
|
181
|
+
`--lightcurve PATH`, `--log PATH`, `--vizier PATH` and `--aperture-record PATH`;
|
|
182
|
+
each is checked only for the slot's extension. The "contains `log`" rule only
|
|
183
|
+
tells two `.txt` files in a folder apart, so `--log PATH` takes any `.txt` — a
|
|
184
|
+
Tangra fit log or `notes.txt` alike.
|
|
185
|
+
|
|
186
|
+
**Correcting a submitted observation** is the same command as fixing a draft:
|
|
187
|
+
`iota-hub drafts files add <id> <slot> <path>` replaces the file and marks the
|
|
188
|
+
observation `amended`. A replacement report must still describe the same
|
|
189
|
+
observation (otherwise `identity_changed`, exit code `2`, and nothing changes),
|
|
190
|
+
and once its event is in review the Hub refuses (`already_processed`, exit code
|
|
191
|
+
`1`) — ask a coordinator then.
|
|
192
|
+
|
|
193
|
+
## Getting a key
|
|
194
|
+
|
|
195
|
+
Sign in to IOTA Hub and open the **Developers** page (`/developers`); the
|
|
196
|
+
**API keys** section is there. The key is shown once, is stored hashed, and you
|
|
197
|
+
may have up to 10.
|
|
198
|
+
|
|
199
|
+
- **Scopes**, fixed when the key is created: `read` for every read,
|
|
200
|
+
`observations:write` for every write. A key missing the scope a call needs is
|
|
201
|
+
`403 insufficient_scope`.
|
|
202
|
+
- **Lifetime**, chosen when the key is created: 30 days, 90 days, 1 year (the
|
|
203
|
+
default), or never. An expired key is `401 expired_api_key`.
|
|
204
|
+
- A key **acts as its owner** — exactly what that account can do in the web app,
|
|
205
|
+
nothing more.
|
|
206
|
+
|
|
207
|
+
Give the key to the tool in one of two ways, never as a command-line argument
|
|
208
|
+
(it would land in your shell history and in `ps`):
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
iota-hub auth login # prompts with hidden input, stores it
|
|
212
|
+
export IOTA_HUB_API_KEY=... # the CI and agent path, no login step
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`iota-hub auth status` shows which profile is in use, the target base URL and
|
|
216
|
+
the identifying prefix of the key (`iotahub_<key_id>_...`, never the secret),
|
|
217
|
+
and makes one cheap read to say whether the key is actually valid.
|
|
218
|
+
`iota-hub auth logout` removes a stored profile.
|
|
219
|
+
|
|
220
|
+
Profiles keep a key **and** its base URL together, so a development key is never
|
|
221
|
+
sent to production or the reverse:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
iota-hub auth login --profile dev --base-url <dev base URL>
|
|
225
|
+
iota-hub submit --profile dev # or IOTA_HUB_PROFILE=dev
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
`--json`, `--profile` and `--base-url` are accepted after the subcommand, as
|
|
229
|
+
above, and before it (`iota-hub --profile dev submit`) — whichever reads better.
|
|
230
|
+
When both carry a value, the one after the subcommand wins.
|
|
231
|
+
|
|
232
|
+
Whenever the resolved target is not the production default, the CLI prints
|
|
233
|
+
`Target: <base URL>` on stderr before acting, so a test run is never mistaken
|
|
234
|
+
for a real submission. Settings resolve flag > environment > config file >
|
|
235
|
+
default, and the config file lives where the platform puts configuration:
|
|
236
|
+
|
|
237
|
+
| Platform | Path |
|
|
238
|
+
| -------- | -------------------------------------------------------- |
|
|
239
|
+
| Linux | `~/.config/iota-hub/config.toml` |
|
|
240
|
+
| macOS | `~/Library/Application Support/iota-hub/config.toml` |
|
|
241
|
+
| Windows | `%APPDATA%\iota-hub\config.toml` |
|
|
242
|
+
|
|
243
|
+
On POSIX the file is written `0600`. On Windows the protection is the ACL on
|
|
244
|
+
your user profile directory; the tool does not set permissions itself. There is
|
|
245
|
+
no OS keyring integration.
|
|
246
|
+
|
|
247
|
+
## For scripts and agents
|
|
248
|
+
|
|
249
|
+
- **`--json` works on every command**: exactly one JSON document on stdout and
|
|
250
|
+
nothing else. Errors are JSON too, on **stderr**, in the API's problem-details
|
|
251
|
+
shape plus the HTTP status, the retry wait and the exit code:
|
|
252
|
+
`{"code": "open_findings", "message": "...", "hint": "...", "details": {}, "status": 409, "retry_after": null, "exit_code": 4}`.
|
|
253
|
+
Branch on `code`, never on `message`. A bad invocation is JSON too, as
|
|
254
|
+
`usage_error` with exit code `2`.
|
|
255
|
+
- **Exit codes** — branch on these rather than parsing output:
|
|
256
|
+
|
|
257
|
+
| Code | Meaning | Typical cause |
|
|
258
|
+
| ---- | ------------------------ | ------------------------------------------------------------------------- |
|
|
259
|
+
| `0` | success | also `--draft`, `--dry-run` and `--no-wait`, which end where you asked |
|
|
260
|
+
| `1` | error | any other failure, including `5xx` and network failures |
|
|
261
|
+
| `2` | usage | bad flags, missing argument, an ambiguous or incomplete slot mapping, a replacement report for another observation (`identity_changed`) |
|
|
262
|
+
| `3` | auth | no key configured, or the API rejected it |
|
|
263
|
+
| `4` | open findings / not ready | findings to fix or dismiss, something required missing, or a wait timeout |
|
|
264
|
+
| `5` | rate limited | still rate limited after the built-in retries |
|
|
265
|
+
|
|
266
|
+
- **`iota-hub guide`** prints the full workflow guide, bundled in the package —
|
|
267
|
+
no network, and the same text an agent can read before acting.
|
|
268
|
+
- **[`SKILL.md`](https://github.com/skycarl/iota-hub-python/blob/main/SKILL.md)** in this repository is a ready-made skill for Claude
|
|
269
|
+
Code or any agent that reads `SKILL.md`. Point your agent at it.
|
|
270
|
+
- **Never prompts when stdin is not a TTY.** Destructive commands take `--yes`.
|
|
271
|
+
- On a terminal, output is colored and spaced for reading; it is plain, colorless
|
|
272
|
+
text when piped, under `--json` or when `NO_COLOR` is set, and is plain ASCII
|
|
273
|
+
by default so a non-UTF-8 Windows console survives it.
|
|
274
|
+
- The literal next command for every action the API says is available is
|
|
275
|
+
printed in human output and returned as `next_commands` in `submit --json`,
|
|
276
|
+
so neither a person nor an agent has to translate a verb into a command.
|
|
277
|
+
- `submit --json` also carries `skipped_checks` (every check that did not run,
|
|
278
|
+
with its reason) and `owc_commands` (the commands that settle an unresolved
|
|
279
|
+
OWC link; empty when there is nothing to settle). Neither changes the exit
|
|
280
|
+
code: they warn, they never block.
|
|
281
|
+
|
|
282
|
+
## Python library
|
|
283
|
+
|
|
284
|
+
The library is the same code the CLI is built on, importable on its own:
|
|
285
|
+
|
|
286
|
+
```python
|
|
287
|
+
import os
|
|
288
|
+
from iota_hub import Client
|
|
289
|
+
|
|
290
|
+
with Client(api_key=os.environ["IOTA_HUB_API_KEY"]) as client:
|
|
291
|
+
result = client.submit_folder("path/to/observation")
|
|
292
|
+
print(result.outcome, result.observation_id)
|
|
293
|
+
|
|
294
|
+
if result.outcome == "needs_attention":
|
|
295
|
+
checks = result.observation.checks
|
|
296
|
+
for finding in checks.findings if checks else []:
|
|
297
|
+
print(finding.fingerprint, finding.message, finding.how_to_fix)
|
|
298
|
+
# Fix one and the draft re-arms its checks:
|
|
299
|
+
client.replace_file(result.observation_id, "lightcurve", "fixed.csv")
|
|
300
|
+
|
|
301
|
+
for observation in client.iter_observations(submission_status="draft"):
|
|
302
|
+
print(observation.observation_id, observation.submission_status)
|
|
303
|
+
|
|
304
|
+
client.download_files("observation", result.observation_id, "downloads/")
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`result.outcome` is the vocabulary to branch on: `submitted` (also when it
|
|
308
|
+
already was), `ready` (clean but left a draft), `needs_attention` (findings,
|
|
309
|
+
something missing, or the run errored), or `draft` (`wait=False`, uploaded and
|
|
310
|
+
finalized but not waited on). `result.observation.web_url` is the observation in
|
|
311
|
+
the web app, and `result.observation.status` is the derived `draft` /
|
|
312
|
+
`submitted` / `amended` / `locked`. `client.check_observation(asteroid_name=...,
|
|
313
|
+
star_id=..., observed_date="YYYY-MM-DD", asteroid_id=...)` is the lookup before
|
|
314
|
+
a create.
|
|
315
|
+
|
|
316
|
+
Two layers, deliberately kept apart. The **transport** layer is one method per
|
|
317
|
+
public API operation (`create_draft`, `submit_draft`, `list_events`,
|
|
318
|
+
`list_observation_files`, ...), returning hand-written pydantic models. The
|
|
319
|
+
**workflow** layer is what the API cannot do for you: `submit_folder`,
|
|
320
|
+
`submit_files`, `wait_for_checks`, `replace_file`, `download_files`, and the
|
|
321
|
+
folder-to-slot mapping in `iota_hub.files`.
|
|
322
|
+
|
|
323
|
+
Retries (`429`/`5xx`, honouring `Retry-After`), one idempotency key per logical
|
|
324
|
+
call, and the base64 SHA-256 declared on every upload are all handled for you.
|
|
325
|
+
Errors are one exception type, `IotaHubError`, carrying `.code`, `.message`,
|
|
326
|
+
`.hint`, `.details`, `.status` and `.retry_after`; the subclasses `AuthError`,
|
|
327
|
+
`RateLimitError`, `NotFoundError`, `ConflictError`, `RequestError` and
|
|
328
|
+
`TransportError` group the codes by category, so you can catch broadly without
|
|
329
|
+
enumerating them. Models ignore fields they do not know, so an additive API
|
|
330
|
+
change never breaks an installed version.
|
|
331
|
+
|
|
332
|
+
## Environments
|
|
333
|
+
|
|
334
|
+
The default target is production, `https://api.iota-hub.com`. **The public API
|
|
335
|
+
is not live in production yet** — its release is pending, and until then the
|
|
336
|
+
development deployment is where third-party developers build: sign up there,
|
|
337
|
+
create a key, and use a `dev` profile. The development base URL is published on
|
|
338
|
+
that site's `/developers` page; no non-production URL is baked into this
|
|
339
|
+
package.
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
iota-hub auth login --profile dev --base-url <the dev base URL>
|
|
343
|
+
iota-hub observations list --profile dev
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
`--base-url` (and `IOTA_HUB_BASE_URL`) is the **API base**; the client appends
|
|
347
|
+
`/public/v1` itself. Local development against a checkout of the API is
|
|
348
|
+
`--base-url http://localhost:8000`.
|
|
349
|
+
|
|
350
|
+
## Under the hood: the HTTP API
|
|
351
|
+
|
|
352
|
+
Everything here is a client of one frozen, versioned HTTP surface, `/public/v1`,
|
|
353
|
+
which stays public for anyone the CLI and the library do not fit. It is the hard
|
|
354
|
+
way — presigned S3 uploads, polling, idempotency keys — which is exactly why
|
|
355
|
+
this package exists.
|
|
356
|
+
|
|
357
|
+
The raw-HTTP walkthrough is at <https://iota-hub.com/developers/api>
|
|
358
|
+
(interactive reference at `/developers/reference`, the raw workflow guide at
|
|
359
|
+
`/developers/guide.md`; keys are on `/developers`). Porting a client to another language starts from
|
|
360
|
+
[`spec/openapi.json`](https://github.com/skycarl/iota-hub-python/blob/main/spec/openapi.json), vendored here and checked against the
|
|
361
|
+
live document in CI, and
|
|
362
|
+
[`docs/client-conventions.md`](https://github.com/skycarl/iota-hub-python/blob/main/docs/client-conventions.md), which specifies
|
|
363
|
+
everything the API itself does not: configuration, retries, polling, folder
|
|
364
|
+
mapping, exit codes and output.
|
|
365
|
+
|
|
366
|
+
## Requirements
|
|
367
|
+
|
|
368
|
+
Python 3.10 or newer, on Windows, macOS or Linux. Runtime dependencies are
|
|
369
|
+
`httpx`, `pydantic`, `typer` and `platformdirs`.
|
|
370
|
+
|
|
371
|
+
## Versioning
|
|
372
|
+
|
|
373
|
+
Semantic versioning, `0.x` until the public API's production release. A
|
|
374
|
+
**major** bump is removing a command or a flag, or changing the shape of a
|
|
375
|
+
`--json` document. New commands, new optional flags and new fields in a `--json`
|
|
376
|
+
document are additive and are not.
|
|
377
|
+
|
|
378
|
+
## Contributing
|
|
379
|
+
|
|
380
|
+
Issues and pull requests about this client go to
|
|
381
|
+
[skycarl/iota-hub-python](https://github.com/skycarl/iota-hub-python). Issues
|
|
382
|
+
about the API itself — a wrong status code, a missing filter, an unclear
|
|
383
|
+
finding — go to [skycarl/iota-hub](https://github.com/skycarl/iota-hub) with the
|
|
384
|
+
label `drafts-and-api`.
|
|
385
|
+
|
|
386
|
+
## License
|
|
387
|
+
|
|
388
|
+
MIT. See [LICENSE](LICENSE).
|