FITSMangler

A minimal Python tool to mangle FITS files in a variety of ways for testing validation utilities such as ftverify. This repository contains an executable script ftmangle as well as library functions for programmatic use.

Features

• Create a new FITS file from scratch.
• Delete header keywords or assign bad values to them.
• Generate a series of example mangled FITS files demonstrating common failure modes.
• Operate on existing FITS files by applying one or more mangles.
• Includes automated tests covering the core behaviour.

Getting started

1. Clone the repository and change to its directory.

2. Create a virtual environment and install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Run the CLI using the module interface (python -m ftmangle.cli), or install the package after adding a console_scripts entry if desired.

Examples

# create a new file and corrupt a keyword
python -m ftmangle.cli new sample.fits --corrupt TEST BADVALUE

# mangle an existing file by deleting a header card
python -m ftmangle.cli mangle good.fits bad.fits --delete OBSERVER

# produce a directory of example failures
python -m ftmangle.cli series examples

Coding guidelines

• No local imports – import modules using absolute names to avoid ambiguous paths during packaging or testing. 3rd‑party libraries such as astropy are external dependencies.
• Strict type hints – every function and public method should include parameter and return type annotations.
• Tests use pytest and should exercise all public interfaces to catch regressions.
• Keep the project structure simple: ftmangle/ contains library code and cli.py; tests live in tests/.

Additional notes

The repository is intentionally minimal; additional mangling routines (e.g. corrupting the data area or modifying multiple HDUs) can be added later. The automated tests provide a safety net for future enhancements.