Summary
Break specs.py (~1,950 lines) into focused, single-responsibility modules.
Problem
specs.py currently spans at least 6 concerns:
- Axis normalization —
_normalize_axes(), axis type inference
- Constraint parsing —
_validate_constraint_axes(), _resolve_constraint_mode(), _validate_constraint_rule(), _normalize_constraints()
- Template expansion —
_expand_state_templates(), _expand_alias_templates()
- Equation normalization —
normalize_expr_rhs()
- Transition normalization —
normalize_transitions_rhs(), _expand_single_transition()
- Symbol extraction —
_collect_symbols(), param detection
As the Pydantic models land (#20–28, #58), each model will pull validation logic out — but without a deliberate split, the file risks becoming a mix of old procedural code and new model imports, with increasing merge-conflict risk across parallel PRs.
Proposed Structure
src/op_system/
├── specs.py → slim facade: normalize_rhs(), public types
├── _axes.py → axis normalization
├── _constraints.py → constraint parsing/validation
├── _templates.py → state/alias/transition template expansion
├── _normalize.py → normalize_expr_rhs(), normalize_transitions_rhs()
└── _symbols.py → symbol collection and param extraction
Constraints
- All public exports must remain importable from
op_system and op_system.specs
- No behavioral changes — pure file reorganization
- Must pass
ruff check --preview and mypy --strict
Priority
Lower than Pydantic model issues. Best done either before or after the Pydantic batch — not during — to minimize conflicts.
Related
Summary
Break
specs.py(~1,950 lines) into focused, single-responsibility modules.Problem
specs.pycurrently spans at least 6 concerns:_normalize_axes(), axis type inference_validate_constraint_axes(),_resolve_constraint_mode(),_validate_constraint_rule(),_normalize_constraints()_expand_state_templates(),_expand_alias_templates()normalize_expr_rhs()normalize_transitions_rhs(),_expand_single_transition()_collect_symbols(), param detectionAs the Pydantic models land (#20–28, #58), each model will pull validation logic out — but without a deliberate split, the file risks becoming a mix of old procedural code and new model imports, with increasing merge-conflict risk across parallel PRs.
Proposed Structure
Constraints
op_systemandop_system.specsruff check --previewandmypy --strictPriority
Lower than Pydantic model issues. Best done either before or after the Pydantic batch — not during — to minimize conflicts.
Related
NormalizedRhsmodel that is discriminated union ofExprRhsandTransitionsRhs#20–28, AddConstraintPydantic model #58 (Pydantic models will touch these same code regions)