libera_utils.l1a.ground_ccsds.scan_ground_ccsds_file#

libera_utils.l1a.ground_ccsds.scan_ground_ccsds_file(packet_file: PathLike | str, *, apid: int | None = None, skip_header_bytes: int = 0) → GroundCcsdsTimeSpan | None#

Scan one demuxed ground CCSDS file for its packet and science data time spans.

A data-time-indexed APID also gets science data times via extract_data_time_range_from_dataset. When those cannot be determined the packet-time span is still returned, with first_data_time/last_data_time None and degraded_reason set.

Parameters:

  • packet_file (PathLike | str) – Path to a demuxed ground CCSDS file.

  • apid (int | None, optional) – APID of the packets in the file. When None, taken from the basename.

  • skip_header_bytes (int) – Bytes to skip before each CCSDS primary header. Demuxed files need 0.

Returns:

Time spans for File Metadata ingest, or None if no packet-time span can be produced at all: the APID is not a LiberaApid member, has no packet configuration, the file does not parse for a reason other than resource exhaustion, holds no packets for the APID, or every packet time is implausible. The reason is logged. No searchable metadata is possible for such a file, so a caller should surface the None as its own error.

Return type:

GroundCcsdsTimeSpan | None

Raises:

  • ValueError – If apid is omitted and the basename is not a valid ground CCSDS filename.

  • MemoryError – If memory runs out while the file is read or parsed. It is not wrapped.

  • OSError – If reading the file, including downloading a cloud file to the local cache, fails with ENOSPC, EDQUOT, EMFILE or ENFILE (see libera_utils.io.smart_open.is_resource_exhaustion). It is not wrapped.