Metadata-Version: 2.4
Name: dkist-header-validator
Version: 5.4.1rc1
Summary: DKIST data validator
Author-email: NSO / AURA <dkistdc@nso.edu>
License: BSD-3-Clause
Project-URL: Homepage, https://nso.edu/dkist/data-center/
Project-URL: Repository, https://bitbucket.org/dkistdc/dkist-header-validator
Project-URL: Help, https://nso.atlassian.net/servicedesk/customer/portals
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
Requires-Dist: astropy>=5.0
Requires-Dist: voluptuous<1.0.0,>=0.11.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: dkist-fits-specifications==4.29.0rc4
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: deepdiff; extra == "test"
Requires-Dist: tox; extra == "test"
Requires-Dist: dkist-data-simulator==5.9.0rc2; extra == "test"
Provides-Extra: cli
Requires-Dist: typer; extra == "cli"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-astropy; extra == "docs"
Requires-Dist: sphinx-changelog; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: pytest; extra == "docs"
Requires-Dist: towncrier; extra == "docs"
Requires-Dist: dkist-sphinx-theme; extra == "docs"

DKIST Data Validator
====================

|codecov|

An interface containing a validator and a spec translator for DKIST FITS specs SPEC122 and SPEC214:

- SPEC-0122: Data received from the summit

- SPEC-0214 l0: Data ingested and parsed by the Data Center

- SPEC-0214: Data published by the Data Center (incomplete)

The validator references a machine readable version of the DKIST Header Specifications which are
defined `here in the dkist-fits-specifications package <https://pypi.org/project/dkist-fits-specifications/>`__.
Unless otherwise specified, the latest version of ``dkist-fits-specifications`` package is installed along
with the validator.  Data can be validated against past revisions of the DKIST Header Specifications if a
previous version of the ``dkist-fits-specifications`` package is installed. If you are receiving validation
errors, please reference the version of the DKIST Header Specifications identified in the
``dkist-fits-specifications`` package to make sure that your headers are expected to be compliant with that version.


Features
--------

-  Uses `voluptuous <https://pypi.org/project/voluptuous/>`__ schemas to
   validate a given input header against dkist specifications

-  3 keyword validations: type validation, required-ness validation, and value validation

-  Failure exceptions include a dictionary of validation failure causes

-  SPEC-0122 to SPEC-0214 l0 translation


Installation
------------

.. code:: bash

   pip install dkist-header-validator


Usage
--------
Currently, this package can be used to validate SPEC122 data or SPEC214 data. Please import the
corresponding methods (``spec122_validator`` and ``Spec122ValidationException``, or ``spec214_validator`` and
``Spec214ValidationException``, or ``spec214_l0_validator`` and ``Spec214ValidationException``).

Input data can be one of:

- ``fits.Header`` object
- ``fits.PrimaryHDU`` or ``fits.ImageHDU`` or ``fits.CompImageHDU`` object
- ``HDUList`` object
- File path to an ``HDUList`` object

To validate an object in memory:

.. code:: python

    >>> from dkist_header_validator import spec122_validator, Spec122ValidationException
    >>> from astropy.io import fits
    >>> hdul = fits.open('dkist_rosa0181200000_observation.fits')
    >>> validated_hdul = spec122_validator.validate(hdul)
    >>> # or
    >>> validated_hdu = spec122_validator.validate(hdul[1])
    >>> # or
    >>> validated_header = spec122_validator.validate(hdul[1].header)

Or, validate an object on disk directly:

.. code:: python

    >>> from dkist_header_validator import spec122_validator, Spec122ValidationException
    >>> filepath = spec122_validator.validate('dkist_rosa0181200000_observation.fits')

Note that the return is just the input.  If no errors or exceptions are raised, the header is valid.  The validate
method also accepts the boolean flag ``extra``, which determines if extra keywords are allowed in the validation
schema. Default value is ``extra=True``.

The CLI can also be used to validate files:

.. code:: bash

    $ dkist-header-validator validate122 "path/to/file.fits"
    $ dkist-header-validator validate214 "path/to/file.fits"

In addition, this package can be used to translate headers from SPEC122 to SPEC214 l0:

.. code:: python

    >>> from dkist_header_validator import translate_spec122_to_spec214_l0
    >>> translated_hdul = translate_spec122_to_spec214_l0('dkist_rosa0181200000_observation.fits')

The return in this case is the an HDUList with a translated header and the original data.

This project is Copyright (c) AURA/NSO.

.. |codecov| image:: https://codecov.io/bb/dkistdc/dkist-header-validator/graph/badge.svg?token=OZK0ZPO2JH
 :target: https://codecov.io/bb/dkistdc/dkist-header-validator
