From cbc648b7f06e637f30ca282d83175a419eb9573b Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Tue, 6 Oct 2026 19:54:58 -0400 Subject: [PATCH] Add docstrings for read_file and read_file_sc Document the parameters, return value, exceptions, and behavior of the two public functions that read L0 files. Co-Authored-By: Claude Opus 5.5 --- .../decommutator/ccsds_reader_pipeline.py | 82 ++++++++++++++++++- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/src/pyfaradaycup/decommutator/ccsds_reader_pipeline.py b/src/pyfaradaycup/decommutator/ccsds_reader_pipeline.py index 2e6b9f7..d8214d6 100644 --- a/src/pyfaradaycup/decommutator/ccsds_reader_pipeline.py +++ b/src/pyfaradaycup/decommutator/ccsds_reader_pipeline.py @@ -225,7 +225,41 @@ def read_file( # ruff:ignore[C901] verbose: bool = False, # ruff:ignore[FBT001, FBT002] gzip: bool = False, # ruff:ignore[FBT001, FBT002] ) -> dict[int, dict[str, list]]: - """Read a CCSDS File and return data structure""" # ruff:ignore[D400] + """ + Read SPC instrument packets from an L0 file. + + Parameters + ---------- + path : str or path-like + Path to the L0 file to read. + + verbose : bool, optional + If `True`, print status messages, including why a packet was + skipped. + + gzip : bool, optional + If `True`, read the file as gzip-compressed. + + Returns + ------- + dict of int to dict of str to list + The decoded data, keyed by APID and then by mnemonic, with one + entry per packet. Only APIDs 0x351-0x354, 0x35E, and 0x35F are + read. If no packets are found, each list is empty. + + Raises + ------ + RuntimeError + If the file cannot be opened or read. + + Notes + ----- + Packets are found by searching the raw bytes for a SWEM wrapper + header (APID 0x348-0x350) followed by an SPC instrument header. + The packet layouts are read from ``sweap_tlm.blk`` in the package + data directory. Progress and a summary of the number of packets + found for each APID are written to standard output. + """ # make sure the file can be read path = _choose_file(path) @@ -321,7 +355,51 @@ def read_file_sc( # ruff:ignore[C901, PLR0912, PLR0915] ptp: bool = False, # ruff:ignore[FBT001, FBT002] gzip: bool = False, # ruff:ignore[FBT001, FBT002] ) -> dict[int, dict[str, list]]: - """Read a CCSDS File and return data structure""" # ruff:ignore[D400] + """ + Read spacecraft housekeeping packets from an L0 file. + + Parameters + ---------- + path : str or path-like + Path to the L0 file to read. + + verbose : bool, optional + If `True`, print status messages, including why a packet was + skipped. + + ptp : bool, optional + If `True`, the file is a PTP file, in which each packet is + preceded by a PTP header. + + gzip : bool, optional + If `True`, read the file as gzip-compressed. + + Returns + ------- + dict of int to dict of str to list + The decoded data, keyed by APID and then by mnemonic, with one + entry per packet. Only APIDs 0x07B, 0x081, 0x254, 0x256, 0x257, + and 0x262 are read. If no packets are found, each list is empty. + + Raises + ------ + RuntimeError + If the file cannot be opened or read. + + Notes + ----- + The packet layouts depend on the version of the spacecraft flight + software, so the spacecraft housekeeping definition (``.blk``) file + is chosen by date. The date is taken from the MET of the first + packet in the file. If that fails, it is taken from a + ``/`` part of ``path``, and if that also fails, + the newest definition file is used. The flight software versions + and their dates are listed in ``sc_hsk/L1/APID257_combined.txt`` in + the package data directory. + + Progress and a summary of the number of packets found for each + APID are written to standard output. + """ # make sure the file can be read path = _choose_file(path)