python3-damaris/AGENTS.md

# python3-damaris

## GUI Purpose and Operation
This is the front end part of GUI for controlling NMR spectrometers. On "Start", the experiment script executes and creates XML job files. A backend, not in this code, executes these jobs sequentially adn writes the results as XML files. The front end consumes these result files using the result script.

## Guidelines
1. Prefer the system python and notify the user if libraries and packages are missing. Use uv for the python3 environment only if system packages are missing and the user does not want to install the needed packages.
2. Old code was ported from gtk2 and python2.7. This code has to work on python 3.11 and above, as well as GTK3
3. Be aware the targeted Debian versions are bookworm, trixie, and forky.
4. Only use packages and libraries available in Debian bookworm, trixie, and forky. Make sure that the code is compatible with all of these versions.
5. Do not commit changes (with git) or write commit messages without asking the user.
6. Try to minimize code changes, do not use elaborate checks for defensive programming. Ask the user if something should be tested with unit tests.
7. Use the python unittest module for unit tests, not pytest
8. Functions for the experiment script belong to the src/damaris/experiments/Experiment.py file
9. Functions for the result script belong in the files in the src/damaris/data/ folder
10. The gitea workflow can be found at .gitea/workflows/debian-build.yml
11. Do not edit anything in "build", it is regenerated
12. Use sphinx for documentation, autodoc and autosummary is used for references of all classes, functions and modules. 
13. If a new function/method is created document a short usage and an example in the doc string. Add a longer explanation in doc/manual.rst in the command list. Use Sphinx autodoc and autosummary grammar to describe it. Use "timesignal" as ADC_Result object and "accu" as Accumulation object.
14. Doxygen is not used anymore!