fix(stations): name mirrored=False on an unplaced valve station

[Alpha9463]

Summary

add_valve_station() refuses the four run options (mirrored, gap, bypass_rise, drain_drop) on a station with no x/y, and its docs and error say every option given is named. mirrored defaulted to False, so mirrored=False could not be told from leaving it out. It was accepted, and left out of the names when another option was refused. mirrored now defaults to None, like the three distances. No drawing changes.

Related Issues

Closes #541
Refs: #527, #535

Changes

• pandid/flowsheet.py: add_valve_station(mirrored: bool | None = None). Any value given counts as stated and is refused by name without x/y. The value resolves to False once the run is drawn, both for the pinned run and for the recorded StationAssembly. The docstring and the comment beside the check are updated.

• place_valve_station_on(): unchanged. A station placed on a stream has a drawn run, so it still takes mirrored=False.

• Tests (tests/test_valve_station.py):

  • mirrored=False alone, and with gap, is refused by name;
  • a refused mirrored=False call leaves the sheet untouched;
  • a pinned station draws mirrored=False exactly as it draws the option left out;
  • place_valve_station_on(..., mirrored=False) is accepted.

  The two refusal tests fail on main. The module's documentation is rewritten to the NumPy style, with each test's docstring now a "Check that …" summary. Apart from the new and changed tests, the test code is unchanged: the files compare equal as syntax trees with docstrings removed.

• CHANGELOG.md: an [Unreleased] Fixed entry.

How to Test

python3 -m pytest -q tests/test_valve_station.py tests/test_station_assemblies.py
python3 -c "from pandid import Flowsheet; Flowsheet('x').add_valve_station('CV-1', mirrored=False)"   # ValueError naming mirrored=
python3 -m pytest -q
python3 -m ruff check .
python3 -m ruff format --check tests
python3 -m mypy pandid
python3 -m pyright pandid

Evidence

Call	Before	After
add_valve_station("CV-1", mirrored=False)	accepted	ValueError naming mirrored=
add_valve_station("CV-1", mirrored=False, gap=DEFAULT_GAP)	refusal names gap= only	refusal names mirrored=, gap=
add_valve_station("CV-1")	accepted	accepted
add_valve_station(..., x=300, y=400, mirrored=False)	drawn west to east	identical drawing
place_valve_station_on(run, "CV-1", mirrored=False)	accepted	accepted

• Drawings unchanged: frames, routes and validation findings are identical to main for 46 drawings (the 21 examples as authored and with placement stripped, plus four benchmark sheets).
• Full suite: 11,568 passed, 188 skipped (Python 3.14).
• Lint and types:
  • ruff, test formatting, mypy and git diff --check are clean;
  • pyright reports 0 errors on pandid/ plus the existing __all__ warning;
  • the test file has the same 61 existing optional-member diagnostics as on main, which tests/ carries 1044 pyright diagnostics, so the pyright CI gate covers pandid/ only #530 tracks; none were added.

Checklist

• Base branch is main and the branch is mergeable
• Commit subjects follow Conventional Commits; tracked work links its issue
• Self-reviewed the full diff on the Files changed tab
• Relevant local checks pass; all CI jobs pass before merge
• Documentation and examples updated if behaviour changed
• Before/after drawings included if rendered output changed (no rendered output changed)
• Blocking review feedback resolved, if review was requested

🤖 Generated with Claude Code