API reference#

Load the packaged MUSE FITS keyword specifications.

Each level’s specification is a directory of small per-section YAML files under specs/<level>/ (DKIST-style layout): _meta.yml carries the spec-wide fields, and every other file holds one section’s keywords. The loader checks the spec files themselves against the field rules below, so a typo in a spec fails at load time, not silently during header validation.

Keyword fields:

  • required: the keyword must be present in a conforming header. Structural cards owned by the FITS library (tile-compression bookkeeping, checksums) and keywords with unresolved ICD questions are recorded but not required.

  • type: one of bool/int/float/str; omitted when the source document does not yet pin the type down. Omitted means no type check.

  • values: closed set of allowed values.

  • format: isot marks an ISO 8601 timestamp string.

  • source: the ISP mnemonic or other upstream source of the value.

  • example: an example value, verbatim from the source document.

The section name is not stored per keyword; it comes from the file the keyword lives in.

exception muse_fits_specifications.spec.SpecDefinitionError#

A packaged spec file violates the spec-file rules.

class muse_fits_specifications.spec.KeywordSpec(name: 'str', required: 'bool', type: 'str | None' = None, values: 'tuple[Any, ...] | None' = None, format: 'str | None' = None, source: 'str | None' = None, example: 'str | None' = None, comment: 'str' = '', section: 'str' = '')#
class muse_fits_specifications.spec.HduSpec(name: 'str', kind: 'str', compression: 'str | None' = None)#
class muse_fits_specifications.spec.Spec(name: 'str', version: 'int', title: 'str', source_document: 'str', hdus: 'tuple[HduSpec, ...]', keywords: 'Mapping[str, KeywordSpec]')#
muse_fits_specifications.spec.load_spec(level: str) → Spec#

Load one level’s specification, e.g. load_spec("level0").

muse_fits_specifications.spec.example_value(kw: KeywordSpec) → bool | int | float | str | None#

Parse the keyword’s source-document example into a typed header value.

Returns None when the spec records no example.

muse_fits_specifications.spec.example_header(spec: Spec, *, skip_sections: tuple[str, ...] = ('fits',)) → dict[str, bool | int | float | str]#

A complete conforming header for every required keyword.

Generators (simulators, fixture writers) start from this so their files conform to the same spec the validator enforces. Values are the source document’s examples where recorded; otherwise the first allowed value for closed sets, then a neutral typed placeholder (0/0.0/UNKNOWN, presence-only for untyped keywords). Structural cards (the fits section: checksums and tile-compression bookkeeping) are skipped because the FITS library computes them. The result passes validate().

Validate FITS headers against a loaded MUSE specification.

Keywords not in the spec are ignored: FITS headers legitimately carry structural and history cards the mission spec does not govern.

exception muse_fits_specifications.validation.HeaderValidationError(spec_name: str, errors: list[str])#
muse_fits_specifications.validation.validate(header: Mapping[str, Any], spec: Spec, *, skip_sections: tuple[str, ...] = ()) → list[str]#

Return every way header violates spec; empty means valid.

skip_sections excludes whole sections, e.g. the structural fits section whose cards (checksums, tile-compression bookkeeping) are owned and verified by the FITS library rather than header comparison.

muse_fits_specifications.validation.ensure_valid(header: Mapping[str, Any], spec: Spec) → None#

Raise HeaderValidationError if header violates spec.

Render the packaged specs as reStructuredText reference pages.

Regenerate after editing a spec YAML so the docs cannot drift from the spec.