fix(spec): one number rule for the spec reader and the Python API

[Alpha9463]

Summary

Makes the spec reader and the Python API apply one rule to numbers. The reader accepted only exact int/float, so numpy.int64 from pandas was refused after the Python API had drawn a correct sheet from it. Meanwhile the Python API accepted values that crashed the render: Decimal geometry, non-text stream styles and numeric labels. Numpy numbers now round-trip; values layout cannot use are refused when set; numeric labels draw as text. No drawing changes.

Related Issues

Closes #536
Refs: #533, #534

Changes

• Shared rule: new pandid/_checks.py, with is_real (any numbers.Real except bool; Decimal is not one), is_whole (any numbers.Integral except bool), and check_real / check_whole raising TypeError with a float(value) hint for Decimal.
• Spec reader (pandid/spec.py):
  • Every numeric field reads any real number and every whole-number field any integer, returned unchanged (120 and 120.0 draw differently).
  • Decimal is accepted where a value is only displayed (line-number components, stream properties) and refused for geometry.
• Python API, values layout cannot use are refused when set:
  • Unit width/height, at construction and on assignment, Block included;
  • pin() coordinates; ranks must be whole numbers, so col=1.0 and row=True are refused;
  • Stream.via() waypoints;
  • Annotation/TableBox margin, width, font_size and position, at construction and on assignment;
  • Stream.color and dasharray must be text.
• Numeric labels draw as text: a numeric flag reference and the table sheet's sheet_drawing_number and sheet_subtitle, through document._drawn_text as title-block fields are.
• Tests: tests/test_stated_values.py, 54 tests in total for to_dict() silently drops a stated value and the sheet is redrawn differently: a fractional number-start, and a falsey annotation title #533 and The spec reader refuses numpy and Decimal numbers the Python door accepts and draws #536.
• Docs: docs/api.md states the number rules, restoring the to_dict() silently drops a stated value and the sheet is redrawn differently: a fractional number-start, and a falsey annotation title #533 sentence on integer number starts that was missing from that commit. CHANGELOG.md has [Unreleased] entries.

How to Test

python3 -m pytest -q tests/test_stated_values.py tests/test_spec.py
python3 -c "from decimal import Decimal; from pandid import units as U; U.Pump('P-1', width=Decimal(70))"   # TypeError naming width
python3 -m pytest -q
python3 -m ruff check .
python3 -m ruff format --check tests
python3 -m mypy pandid
python3 -m pyright pandid

Evidence

Every numeric field the spec reads was tried with numpy.int64, numpy.float64 and Decimal, through the Python API, to_svg, to_drawio, to_dict and from_dict.

	Before	After
numpy values: Python API	draws	draws
numpy values: reader	int64 refused on most fields	round-trips; the whole sheet's SVG is identical after to_dict/from_dict
Decimal in geometry	accepted, then TypeError mid-render	TypeError when set; refused by the reader
Decimal in components/properties	drawn, refused by the reader	drawn and round-trips
color=True, dasharray=4	render crash (SVG or draw.io)	TypeError when set
numeric reference, sheet_drawing_number, sheet_subtitle	render crash	drawn as text

• 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,548 passed, 188 skipped.
• Lint and types: ruff, test formatting, mypy and git diff --check are clean. Pyright reports 0 errors plus the existing __all__ warning, and 0 errors on the test file.

Not changed

• Decimal counts (trays, feed_stages, n_inlets) still fail at construction with Python's own TypeError.
• Decimal stream-table widths and font size draw through the Python API and are still refused by the reader.
• Numpy values written by to_dict() are not converted, so json.dumps of such a spec fails.

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