Skip to content

AGENTS.md

Latest commit

 

History

History
60 lines (44 loc) · 3.41 KB

AGENTS.md

File metadata and controls

60 lines (44 loc) · 3.41 KB
Raw

MSS (Mission Support System)

Setup

pixi shell          # activate dev environment (dev + docs features)

Python constraint: < 3.12 (pinned in pixi.toml).

Commands

pixi run -e dev lint            # flake8 over tracked .py files
pixi run -e dev lint-imports    # architectural import contracts (setup.cfg)
pixi run -e dev codespell       # spelling
pixi run -e dev test-fast       # plugins + utils + meta; no servers, fastest signal
pixi run -e dev test-msui       # GUI suite (offscreen Qt)
pixi run -e dev test-mscolab    # collaboration-server suite
pixi run -e dev test-mswms      # WMS-server suite
pixi run -e dev test            # full suite (~13 min)

# single test file
pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/_test_msui/test_topview.py -v

# coverage XML
pixi run -e dev coverage xml

Architecture

Start with ARCHITECTURE.md (package DAG, module index, invariants, verification ladder). Each package under mslib/ has its own CLAUDE.md card with layout, allowed imports, and how to verify changes there. Dependency direction is enforced by import-linter (setup.cfg).

Single package mslib with four main subpackages:

  • msui — PyQt5 desktop GUI (msui entrypoint). Main window: mslib.msui.msui_mainwindow.
  • mscolab — Flask collaborative server (mscolab entrypoint). Server: mslib.mscolab.server. DB models: mslib.mscolab.models.
  • mswms — WMS geospatial service (mswms entrypoint). Driver: mslib.mswms.mss_plot_driver.
  • utils — Shared utilities (config, auth, coordinate handling, netCDF tools).

CLI entrypoints (pixi env): msui, mscolab, mswms, msidp, mssautoplot, mss.

Testing notes

  • Each package's suite runs with only that package installed: root conftest.py holds only what every suite needs (temp config dirs via tests.constants, loading the test mscolab_settings so mslib.mscolab.conf never binds the real database, the server-fork hooks), and the shared test modules (tests/fixtures.py, tests/utils.py, tests/server_setup.py) import mslib.*, Qt, Flask etc. only inside the functions that use them. mscolab_settings / mswms_settings are generated by tests/server_setup.py, from the suite conftests and the server fixtures.
  • tests/fixtures.py provides the server fixtures (mscolab_server, mswms_server, mscolab_app, mscolab_managers); tests/msui_fixtures.py the client's (qtbot, fail_if_open_message_boxes_left, test keyring, msui config reset), loaded by the conftest.py of _test_msui and _test_plugins.
  • Qt tests require QT_QPA_PLATFORM=offscreen on headless machines.
  • Keyring is mocked via TestKeyring in tests/msui_fixtures.py — no real keyring needed.
  • The client suites clean the msui config after every test via the reset_config autouse fixture.
  • MSColab tests fork a real Flask-SocketIO server (multiprocessing fork, random port); the fork happens only in sessions that contain tests needing it.

Conventions

  • Flake8: max-line-length 120. Ignored: E124,E125,E402,W503,W504,A005. Excluded dirs: mslib/msui/qt5/, mslib/mscolab/migrations/.
  • Codespell: exceptions in codespell-ignored-lines.txt. Ignore list: PRES, degreeE, doubleClick, indexIn, socio-economic, EMAC, emac.
  • Qt UI files (qt5/ui_*.py) are generated from .ui — do not edit by hand.
  • No CRLF in git. Whitespace at EOL in tests/data/example.txt and docs/samples/flight-tracks/example.txt is intentional.