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.
@@ -0,0 +1,8 @@
1
+ dist/
2
+ .venv/
3
+ __pycache__/
4
+ *.py[cod]
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ *.egg-info/
8
+ .coverage
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.
@@ -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).