Add debugger updates and improve development tooling

.github/workflows/pr-coverage.yml

@@ -0,0 +1,103 @@
+name: PR Coverage
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  python-version: "3.11"
+  ALLOWED_COVERAGE_DECREASE: 0
+  MIN_COVERAGE: 0.80
+  MIN_DIFF_COVERAGE: 0.85
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    outputs:
+      reference_percent_covered: ${{ steps.coverage_comment.outputs.reference_percent_covered }}
+      new_percent_covered: ${{ steps.coverage_comment.outputs.new_percent_covered }}
+      diff_total_percent_covered: ${{ steps.coverage_comment.outputs.diff_total_percent_covered }}
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Get MAD binaries
+        run: |
+          mkdir -p ./src/pymadng/bin
+          curl https://madx.web.cern.ch/releases/madng/1.1/mad-linux-1.1.11 -o ./src/pymadng/bin/mad_Linux
+          curl https://madx.web.cern.ch/releases/madng/1.1/mad-macos-1.1.11 -o ./src/pymadng/bin/mad_Darwin
+          chmod +x ./src/pymadng/bin/mad_Linux ./src/pymadng/bin/mad_Darwin
+
+      - name: Install package
+        run: uv sync --extra tfs --extra test
+
+      - name: Run coverage
+        run: uv run pytest tests --cov=src/pymadng --cov-report=xml --cov-report=term
+
+      - name: Coverage comment
+        id: coverage_comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+
+  check-coverage:
+    needs: coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check coverage decrease
+        env:
+          CURRENT_COVERAGE: ${{ needs.coverage.outputs.new_percent_covered }}
+          REF_COVERAGE: ${{ needs.coverage.outputs.reference_percent_covered }}
+        run: |
+          MIN_COVERAGE_DECR=$(echo "${REF_COVERAGE} - ${ALLOWED_COVERAGE_DECREASE}" | bc)
+          echo "Reference Coverage: ${REF_COVERAGE}"
+          echo "Current Coverage: ${CURRENT_COVERAGE}"
+          echo "Minimum Allowed Coverage: ${MIN_COVERAGE_DECR}"
+          if (( $(echo "${CURRENT_COVERAGE} < ${MIN_COVERAGE_DECR}" | bc -l) )); then
+            echo "Failed: coverage decreased (${CURRENT_COVERAGE} < ${MIN_COVERAGE_DECR})."
+            exit 1
+          fi
+          echo "Success: coverage did not decrease."
+
+      - name: Check total coverage
+        env:
+          CURRENT_COVERAGE: ${{ needs.coverage.outputs.new_percent_covered }}
+        run: |
+          echo "Current Coverage: ${CURRENT_COVERAGE}"
+          echo "Minimum Allowed Coverage: ${MIN_COVERAGE}"
+          if (( $(echo "${CURRENT_COVERAGE} < ${MIN_COVERAGE}" | bc -l) )); then
+            echo "Failed: coverage is below minimum (${CURRENT_COVERAGE} < ${MIN_COVERAGE})."
+            exit 1
+          fi
+          echo "Success: coverage meets minimum requirement."
+
+      - name: Check diff coverage
+        env:
+          CURRENT_DIFF_COVERAGE: ${{ needs.coverage.outputs.diff_total_percent_covered }}
+        run: |
+          echo "Current Diff Coverage: ${CURRENT_DIFF_COVERAGE}"
+          echo "Minimum Allowed Diff Coverage: ${MIN_DIFF_COVERAGE}"
+          if (( $(echo "${CURRENT_DIFF_COVERAGE} < ${MIN_DIFF_COVERAGE}" | bc -l) )); then
+            echo "Failed: diff coverage is below minimum (${CURRENT_DIFF_COVERAGE} < ${MIN_DIFF_COVERAGE})."
+            exit 1
+          fi
+          echo "Success: diff coverage meets minimum requirement."

.github/workflows/test-publish.yaml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v5
@@ -23,8 +23,8 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install pymadng[tfs]
+        python -m pip install pymadng[tfs] pytest
 
     - name: Test with python
       run: |
-        python -m unittest tests/*.py
+        python -m pytest tests

.github/workflows/test-pymadng.yml

@@ -22,14 +22,16 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v5
     - name: Set up Python ${{ matrix.python-version }} on ${{ matrix.os }}
       uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
     - name: Get MAD Binaries
       run: |
         mkdir ./src/pymadng/bin
@@ -38,8 +40,7 @@ jobs:
         chmod +x ./src/pymadng/bin/mad_Linux ./src/pymadng/bin/mad_Darwin
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        python -m pip install -e .[tfs]
+        uv sync --extra tfs --extra test
     - name: Test with python
       run: |
-        python -m unittest tests/*.py
+        uv run pytest tests

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/streetsidesoftware/cspell-cli
+    rev: v9.3.3
+    hooks:
+      - id: cspell
+        args: [--no-progress, --no-summary]
+        files: ^(README\.md|CHANGELOG\.md|docs/source/.*\.(md|rst))$

CHANGELOG.md

@@ -1,3 +1,9 @@
+0.10.0 (2026/03/11) \
+Major debug update: PyMAD-NG now exposes the MAD-NG debugger directly through `MAD.breakpoint()` and `MAD.pydbg()`, with MAD-side aliases (`breakpoint`, `pydbg`, and `python_breakpoint`) available inside executed code. \
+Debugger sessions now support scripted commands for tests and automation, plus improved interactive terminal handling with a stable Python-rendered prompt. \
+Quitting from the debugger now shuts down the current MAD session cleanly without leaving pipe state inconsistent. \
+Expanded debugger test coverage and documentation for Python-driven MAD debugging workflows.
+
 0.9.0 (2026/02/25) \
 Remove support for Python 3.10, now only supporting Python 3.11 and above. \
 Replaced incorrect Warning call with logging.warning for proper warning handling. \

README.md

@@ -28,9 +28,16 @@ Before diving into PyMAD-NG, we recommend you:
 ### Explore Key Examples
 
 - **[LHC Matching Example](https://pymadng.readthedocs.io/en/latest/ex-lhc-couplingLocal.html)** – Real-world optics matching with intermediate feedback.
-- **[Examples Page](https://pymadng.readthedocs.io/en/latest/examples.html)** - List of examples in an easy to read format. 
+- **[Examples Page](https://pymadng.readthedocs.io/en/latest/examples.html)** - List of examples in an easy to read format.
 - **[GitHub Examples Directory](https://github.com/MethodicalAcceleratorDesign/MAD-NG.py/blob/main/examples/)** – List of available examples on the repository
 
+### A Few Things To Know Early
+
+- `MAD()` launches a real MAD-NG subprocess immediately. Prefer `with MAD() as mad:` in normal use.
+- `mad["x"] = value` writes a variable inside MAD-NG. `mad.x = value` only changes the Python wrapper object.
+- Communication is explicit: tell MAD-NG to `py:send(...)` before calling `mad.recv()`, and tell MAD-NG to `py:recv()` before sending Python data.
+- Many high-level results are references to MAD-NG objects. Use `.eval()` or conversion helpers such as `.to_df()` when you want Python-side values.
+
 If anything seems unclear:
 - Refer to the [API Reference](https://pymadng.readthedocs.io/en/latest/pymadng.html#module-pymadng)
 - Check the [MAD-NG Docs](https://madx.web.cern.ch/releases/madng/html/)
@@ -59,7 +66,7 @@ Examples are stored in the `examples/` folder.
 Run any script with:
 
 ```bash
-python3 examples/ex-fodos.py
+python3 examples/ex-fodo/ex-fodos.py
 ```
 
 You can also batch-run everything using:
@@ -82,7 +89,7 @@ python3 runall.py
 
 ## 🤝 Contributing
 
-We welcome contributions! See [`CONTRIBUTING.md`](docs/source/contributing.md) or the [Contributing Guide](https://pymadng.readthedocs.io/en/latest/contributing.html) in the docs.
+We welcome contributions! See [the contributing guide](docs/source/contributing.md) or the [Contributing Guide](https://pymadng.readthedocs.io/en/latest/contributing.html) in the docs.
 
 Bug reports, feature requests, and pull requests are encouraged.
 

cspell.config.yaml

@@ -0,0 +1,68 @@
+version: "0.2"
+language: en-GB
+
+ignorePaths:
+  - .git
+  - .venv
+  - build
+  - dist
+
+words:
+  - addopts
+  - assertf
+  - automodule
+  - beamline
+  - cmatrix
+  - CTPSA
+  - currentmodule
+  - dataframe
+  - dataframes
+  - defexpr
+  - eval-rst
+  - fodo
+  - fodos
+  - gmath
+  - gphys
+  - imatrix
+  - initialise
+  - kwargs
+  - ipairs
+  - irange
+  - lhcb
+  - linenos
+  - linters
+  - literalinclude
+  - logrange
+  - MADX
+  - MADNG
+  - madp
+  - matplotlib
+  - mtable
+  - mtbl
+  - ndarray
+  - numpy
+  - knl
+  - pathlib
+  - pyplot
+  - pydbg
+  - pymad
+  - pymadng
+  - PyPI
+  - pyproject
+  - pytest
+  - runall
+  - rtrn
+  - seqfile
+  - stdout
+  - stderr
+  - sterr
+  - testpaths
+  - tonumber
+  - tostring
+  - TPSA
+  - tpsa
+  - twiss
+  - venv
+  - vars
+  - xlabel
+  - ylabel