[namurphy]

Description

Replace the decommutator's hand-rolled log file, print calls, and sys.stdout.write progress display with the logging module, and add pyfaradaycup.configure_logging so that logging works the same way from Python and from pfc_decommutator.

• Each module has its own logger, and the pyfaradaycup logger has a NullHandler, so the package is silent from Python unless logging is configured.
• pyfaradaycup.configure_logging(level=..., log_file=..., file_level=..., file_mode=..., console=..., capture_warnings=...) adds a console handler and a log file handler to the pyfaradaycup logger only. It returns a LoggingConfiguration, which can be used in a with block or closed with close(). Log file timestamps are ISO 8601 in UTC.
• swp_spc_l0_to_l05.main no longer takes logdir or verbose. It logs provenance (software versions, host, working directory, the L0 file's size and SHA-256 checksum, and the kernels and skeletons used) and a summary, and returns a DecommutationResult with the CDF files written, the APIDs that failed and why, packet counts, and the same provenance.
• pfc_decommutator configures logging:
  • -v prints progress, -vv prints details, and -q prints only errors. Warnings are printed by default.
  • The log file always has every message, and is named like swp_spc_l0_to_l05_0523462910_4_EA_20261029T190014Z.log. It is opened with mode "x", so runs cannot overwrite each other's logs.
  • Python warnings and the warnings about options with no effect go to the log file too.
  • An unexpected error is logged with its traceback, and the exit code is 1. The exit code is also 1 when any APID could not be converted.
• Messages that were printed for every rejected packet are logged at the DEBUG level with the byte offset, and summarized once.
• Ruff's banned-api rule prevents adding logging handlers anywhere other than pyfaradaycup/_logging.py.

Motivation

The decommutator will have both a Python API and a CLI, and will run in a data pipeline. Logging needs to:

• leave the caller in control of where messages go,
• record enough provenance to trace each L0.5 file back to its inputs and software, and
• report failures through return values and exit codes rather than only in log text.

This addresses part of "Make it callable from Python" and "Give each run its own log file name" in the decommutator README.

Details

Behavior changes for reviewers to check:

1. The exit code is now 1 when an APID is skipped, including APID 0x07B, which is not implemented and only appears with --spacecraft. Previously these runs exited with 0.
2. Log file timestamps are in UTC rather than local time, and the log file name format has changed.
3. The Python API has changed: main no longer accepts logdir or verbose, and the private reader functions no longer accept verbose.
4. Errors for a failed APID are logged at ERROR (one was previously a warning). Per-packet IT+ST and APID 0x352 problems are now DEBUG messages, plus one WARNING summary per APID.
5. The progress display (% Complete) has been removed.

Not done here:

• The warnings.warn in _parse_ccsds_head is unchanged.
• Provenance is not yet written to CDF global attributes.
• configure_logging and LoggingConfiguration are not yet in the API docs, because sphinx.ext.apidoc skips private modules and pyfaradaycup/__init__.py has no __all__.
• The spacecraft housekeeping (--spacecraft) path still has no end-to-end test.

Tests cover configure_logging (levels, the file format and UTC timestamps, file modes, closing, replacement, propagation, and capturing warnings), packet rejection logging, the CLI's log file, its exit codes and -v/-q, and a Python API run that checks the result and that nothing is printed. They pass on Python 3.9 and 3.14.

🤖 Generated with Claude Code

[namurphy]

I'm wondering if this level of detail is necessary or would actually be helpful. 🤔