About maser-tools

maser-tools is part of the MASER Python libraries, with maser4py, maser-data and maser-plot. It offers programs to support radio data format (e.g., CDF) and time (e.g. leap seconds and time conversion handling):

• maser.tools.cdf.serializer: conversions between master binary CDF (.cdf), skeleton table (.skt) and Excel (.xlsx) files, as follows:

  Excel (.xlsx) <--> binary CDF (.cdf) <--> skeleton table (.skt)
  

• maser.tools.cdf.cdfcompare: comparison of two CDF files

• maser.tools.cdf.cdfinfo: display of the metadata of a CDF file

• maser.tools.cdf.validator: validation of a CDF file against a model (e.g. ISTP)

• maser.tools.time: leap seconds and time conversions (UTC, TT2000, Julian days)

Read main documentation for details.

Installation

To install the package, run the following command:

pip install maser-tools

or, with uv:

uv add maser-tools        # in a uv project
uv tool install maser-tools  # to only use the maser-tools and cdfinfo commands

Requirements

• Python 3.10 or later
• The CDF files are read and written with spacepy.pycdf, which relies on the NASA CDF library (see spacepy installation if it is not found).
• The conversions between binary CDF and skeleton table call the skeletoncdf and skeletontable programs of the NASA CDF software. They are searched in the $CDF_BIN directory, then in the $PATH.

Usage

Command line interface

The programs can be run from a terminal with the maser-tools command (or python -m maser.tools):

maser-tools --help
maser-tools skeletoncdf --help

Available sub-commands are:

The metadata of a CDF file (options, global and variable attributes) can be displayed with the cdfinfo command:

cdfinfo my_file.cdf
cdfinfo --no-option --no-variable --gattrs Project Mission_group -- my_file.cdf
cdfinfo --csv my_file.cdf > my_file.csv  # or --asciidoc for an AsciiDoc table

For instance, to make a master CDF from an Excel file, then save it back as a skeleton table and an Excel file in the build folder:

maser-tools skeletoncdf -o build my_master.xlsx
maser-tools skeletontable --to-xlsx -o build/skt build/my_master.cdf

An example of Excel file is provided in src/maser/tools/support/cdf/converter_example.xlsx.

Python

from maser.tools.cdf.serializer import xlsx2cdf, cdf2xlsx

cdf_file = xlsx2cdf("my_master.xlsx", output_dir="build", overwrite=True)
xlsx_file = cdf2xlsx("build/my_master.cdf", output_dir="build", overwrite=True)

Development

To contribute to the development of the package, clone the repository:

git clone https://gitlab.obspm.fr/maser/maser-tools.git
cd maser-tools

The project is managed with uv. Its requirements are detailed in the pyproject.toml file, and pinned in the uv.lock file.

Installing a local copy of maser-tools

Run the following command to create the virtual environment (.venv) and install the package (in editable mode) with its development dependencies:

uv sync

Then run the programs from this environment with uv run, e.g.:

uv run maser-tools --help

The binary files (e.g. Excel files) are stored with Git LFS: run git lfs install once before cloning the repository.

Code quality

The code is linted and formatted with ruff, through pre-commit hooks. Install them once with:

uv run pre-commit install

They can also be run on all the files with:

uv run pre-commit run --all-files

Tests

Run the tests with:

uv run pytest

The tests calling the skeletoncdf and skeletontable programs are skipped when they are not found.

Continuous integration

The GitLab CI pipeline runs the tests with the minimum and latest supported Python versions. It is not run on push: start it from the GitLab web interface (Build > Pipelines > Run pipeline), or with the glab CLI:

glab ci run -b develop

Publish maser-tools on PyPI

maser-tools is published on PyPI by the GitLab CI pipeline, once the tests have passed, for a tag on the main branch. The tag must be the version of pyproject.toml, with or without a v prefix:

uv version 0.4.0  # update the version in pyproject.toml and uv.lock
git commit -am "Release 0.4.0"
git checkout main && git merge develop
git tag v0.4.0
git push origin main v0.4.0

The PyPI API token must be defined in the masked and protected UV_PUBLISH_TOKEN CI/CD variable of the GitLab project (the tags must then be protected).

License

maser-tools is distributed under the CeCILL-B free software license (see the LICENSE file).