Satellite catalogue API#

Evidence-backed spacecraft and space-power component catalogues.

JSONL is canonical; Parquet and browser JSON are reproducible derived snapshots. No network requests, live positions, telemetry or model estimates are implicit.

exception orbitalpv.catalogue.CatalogueError[source]#

Invalid catalogue record, source or snapshot.

orbitalpv.catalogue.build_snapshot(output, root=None)[source]#

Build immutable typed Parquet tables, verified browser projections and manifest.

Requires orbital-pv[catalogue]. Same inputs and PyArrow version produce the same bytes; the manifest records PyArrow’s version. Output must not exist.

Parameters:
Return type:

dict

orbitalpv.catalogue.coverage(records=None)[source]#

Counts and completeness; deliberately no sum of unlike PV power ratings.

Parameters:

records (list[dict] | None)

Return type:

dict

orbitalpv.catalogue.load_records(entity_type=None, root=None)[source]#

Read canonical records, sorted by UUID. Unknown fields remain absent/null.

Parameters:
  • entity_type (str | None)

  • root (str | Path | None)

Return type:

list[dict]

orbitalpv.catalogue.load_schema()[source]#

Return the installed versioned field dictionary.

Return type:

dict

orbitalpv.catalogue.load_sources(root=None)[source]#

Return source IDs mapped to exact URLs and retrieval/reuse metadata.

Parameters:

root (str | Path | None)

Return type:

dict

orbitalpv.catalogue.merge_records(existing, incoming, *, now)[source]#

Fill unknowns only; any conflicting assertion leaves that record unchanged.

Pure operation: validate the complete result before writing it. Ratings and nested extensions are atomic, so a different EOL value cannot silently replace a BOL assertion. Identical observations do not churn timestamps.

Parameters:
Return type:

tuple[list[dict], list[dict]]

orbitalpv.catalogue.record_id(entity_type, identity_key)[source]#

Stable UUID5; preserve case, punctuation and explicit configuration identity.

Parameters:
  • entity_type (str)

  • identity_key (str)

Return type:

str

orbitalpv.catalogue.stage_omm(objects, *, source_id, now)[source]#

Stage identities from supplied CelesTrak/CCSDS OMM; never infer PV capacity.

Review against existing aliases/COSPAR IDs before admission. Exact source bytes, hash and provider terms belong in the caller’s source registry. This function makes no HTTP requests and does not write canonical data.

Parameters:
Return type:

list[dict]

orbitalpv.catalogue.validate_catalogue(root=None)[source]#

Validate packaged or custom canonical data and return coverage statistics.

Parameters:

root (str | Path | None)

Return type:

dict

orbitalpv.catalogue.validate_records(records, sources)[source]#

Validate types, units, identities, field evidence and cross-catalogue links.

Validates the complete proposed catalogue, including component references. Empty or unknown PV output is never replaced with zero or a bus-power rating.

Parameters:
Return type:

None