Technical details

This page collects implementation and maintenance notes that are useful to developers, and the reasoning behind some non-obvious choices.

Supported Python and dependency versions

The package supports Python 3.12 and newer. Python 3.8 was the minimum until 2026, for old production machines at the telescope; it was raised to 3.12 because Python 3.8 to 3.10 have reached their end of life, and current releases of the scientific stack (numpy, scipy, astropy, matplotlib) all support 3.12.

The lower bounds of the dependencies in pyproject.toml are not guesses: they are the oldest versions that install from binary wheels on Python 3.12 and pass the test suite. They are exercised by the py312-test-oldestdeps tox environment, which uses uv with --resolution lowest-direct to install exactly the lower bound of every direct dependency.

Most bounds (numpy>=1.26, scipy>=1.11.2, astropy>=5.3.4, matplotlib>=3.7.3, h5py>=3.10, pyyaml>=6.0.1) are simply the first releases with wheels for Python 3.12, rather than requirements of the code. Matplotlib 3.8.0 is excluded because of a serious bug in that release.

Running the tests

The recommended way is through tox, with the tox-uv plugin:

$ pip install tox tox-uv
$ tox -e py313-test-alldeps     # latest versions, all optional dependencies
$ tox -e py312-test-oldestdeps  # oldest supported versions
$ tox -e py313-test-devdeps     # nightly builds of numpy, scipy, matplotlib, astropy
$ tox -e codestyle              # pre-commit checks (ruff, ...)

Tox installs the package in a separate environment and runs the tests from .tmp/<envname>, so that the source tree is not imported by mistake. On macOS, if tox picks up a “universal2” Python from python.org, the oldest versions of numpy will not install; UV_PYTHON_PREFERENCE=only-managed forces tox-uv to use a uv-managed Python instead.

The code style checks deliberately do not include codespell: with --write-changes it silently “corrected” the MBFITS header keyword HESE into THESE, and this code is full of FITS keywords and abbreviations that a spell checker cannot tell from typos.

Time limits on hung tests

The SDTmonitor tests start background threads and processes, and a hang there used to stall CI until GitHub cancelled the job after 6 hours, with no hint of which test was stuck. Now:

  • pytest-timeout (timeout = 600 in pyproject.toml) stops any single test running longer than 10 minutes. With timeout_method = "thread" it prints the stack of every thread and ends the pytest process: the rest of the run is lost, but the report shows where the background threads are blocked, and a teardown that would hang again cannot do so. Override locally with e.g. pytest -o timeout=0.

  • timeout-minutes: 60 on the CI test jobs cancels a job after one hour, as a backstop.

Warning policy in tests

DeprecationWarning is turned into an error only when it is attributed to srttools itself (filter error::DeprecationWarning:srttools.* in pyproject.toml). In practice, this catches calls from our code to deprecated APIs of numpy, scipy, astropy etc., while ignoring deprecation warnings raised between third-party packages (e.g. Pillow or pyparsing warnings triggered inside old matplotlib versions), which we cannot fix.

Dates and time zones

Dates given on the command line (e.g. SDTinspect --only-after 20250101-000000) are always interpreted as UTC, independent of the time zone of the machine. Tests force a non-UTC time zone to check this, because CI machines run in UTC and would not catch the problem otherwise.