fix(spec): read numbers in drawn text as the text drawn

[Alpha9463]

Summary

The Python API draws a number given for drawn text, such as a description, reference or table cell, as text. The spec reader refused the same value with a SpecError, so to_dict() wrote a spec that from_dict() could not read. Drawn-text fields now read any scalar as the text the sheet draws. Names, settings and annotation titles must still be text. A float loop or instrument number, which drew as F-303.0, is now refused. No drawing changes.

Related Issues

Closes #534
Refs: #532, #533, #536

Changes

• Spec reader (pandid/spec.py): a new _drawn helper reads a drawn-text field through document._drawn_text, the same conversion the renderer uses, and refuses a list, tuple, set or mapping. It is used for:

  • the flowsheet name;
  • component formula;
  • unit, instrument and balloon description and reference;
  • stream-table section headings, and the table sheet's sheet_subtitle and sheet_drawing_number;
  • note items, annotation rows and cells, and table headers.

• Still strict (_text): unit, stream and component names; variant, display and label_pos; section keys, which are matched against property names; col_align; and annotation title (per to_dict() silently drops a stated value and the sheet is redrawn differently: a fractional number-start, and a falsey annotation title #533).

• Python API: Loop / add_loop() and Instrument raise TypeError for a loop number that is neither text nor a whole number. Any numbers.Integral, numpy.int64 included, is accepted.

• Tests: tests/test_stated_values.py adds 9 tests:

  • round trip of a sheet with numbers in its drawn-text fields, for both the diagram and the table sheet;
  • names, variant, annotation title and a list in drawn text are refused;
  • float loop numbers are refused, and numpy integers accepted.

  8 of the 9 fail on main.

• Docs: docs/api.md states the loop-number and drawn-text rules. CHANGELOG.md has [Unreleased] entries.

How to Test

python3 -m pytest -q tests/test_stated_values.py tests/test_spec.py
python3 -c "from pandid import Flowsheet; Flowsheet('x').add_loop('F', 303.0)"   # TypeError naming the loop number
python3 -m pytest -q
python3 -m ruff check .
python3 -m ruff format --check tests
python3 -m mypy pandid
python3 -m pyright pandid

Evidence

	Before	After
Number in drawn text: Python API	drawn as text	drawn as text
Number in drawn text: from_dict(to_dict())	SpecError	same SVG, diagram and table sheet
Number as a name, variant, col_align or annotation title	SpecError	SpecError
add_loop("F", 303.0), Instrument("LIC", 101.0)	drawn as F-303.0, LIC-101.0	TypeError
numpy.int64 loop number	drawn	drawn

• 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,564 passed, 188 skipped (Python 3.14).
• 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

• to_dict() still writes a numeric drawn-text value as the number given; the reader converts it.
• Stream property values are still read as numbers or text, unchanged from The spec reader refuses numpy and Decimal numbers the Python door accepts and draws #536.

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