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 = 600inpyproject.toml) stops any single test running longer than 10 minutes. Withtimeout_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: 60on 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.