Skip to content

CLAUDE.md

Latest commit

 

History

History
65 lines (47 loc) · 3.9 KB

CLAUDE.md

File metadata and controls

65 lines (47 loc) · 3.9 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Setup

pixi shell -e dev          # 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       # api + 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
MSCOLAB_TEST_POSTGRES_URL=postgresql://postgres:postgres@localhost:5432 pixi run -e dev test-mscolab  # same on PostgreSQL (tests/database.py)
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 (coordinates, units, time, netCDF tools, the servers' basic auth); the client's config, keyring and Qt helpers are in mslib/msui/utils/.

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

Tests mirror the package structure under tests/ with subdirectories _test_api/, _test_mscolab/, _test_msui/, _test_mswms/, _test_plugins/, _test_utils/.

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.