Follow-up to PR #83 review feedback from @TimothyWillard.
Type-richness sweep
The reorganisation in PR #83 left many internal helpers returning bare tuples or freeform dict[str, Any] payloads. Per the PR review, anywhere we return a tuple of more than one type or a loose dict could benefit from a richer type — modeled on flepimop2._utils._module.ParsedShorthand (NamedTuple + colocated from_* classmethod).
Concrete first targets:
_axes.py: per-axis dict (name/type/coords/size/deltas/...) → _NormalizedAxis (NamedTuple) with from_mapping classmethod.
_constraints.py: _ConstraintRule already exists; align by adding from_mapping classmethod that absorbs the per-rule validation currently in _validate_constraint_axes / _resolve_constraint_mode / _validate_constraint_rule.
_normalize.py: tuples returned by _split_* / _parse_* selector helpers (e.g. (base, axes_map)).
_templates.py: expand_selector returns list[tuple[str, dict[str, str]]]; could be list[_ExpandedSelector].
compile.py: anywhere a tuple of (values, kwargs) or similar is returned.
Naming convention for these records is captured in docs/development/code-style.md (added in PR #83): NamedTuple by default, frozen dataclass when behaviour beyond a value record is needed, parser colocated as from_* classmethod, underscore-prefixed when scoped to an internal module.
Shareable-utilities discussion
Aside raised by @joshuamacdonald during PR #83 review: we don't want to require plugin developers to depend on flepimop2-core, but we want to encourage consistent configuration standards. A lot of the parsing utilities currently in op_system\._* (axis parsing, bracket selector parsing, constraint validation) would be useful to engine/parameter plugin authors.
Options to evaluate:
- Status quo — keep utilities private to
op_system; plugin authors copy or re-implement.
flepimop2-utils package — factor a tiny standalone utilities package that both op_system and plugin authors can depend on without pulling in core.
- Public
op_system.utils namespace — re-export a curated subset of the current internal helpers via a public module with a documented stability contract.
Decision should be informed by:
- How much of the parsing surface plugin authors actually want.
- Whether stability commitments are realistic given the current rate of change.
- Coordination with the parameter / engine plugin work (
flepimop2#255).
Follow-up to PR #83 review feedback from @TimothyWillard.
Type-richness sweep
The reorganisation in PR #83 left many internal helpers returning bare tuples or freeform
dict[str, Any]payloads. Per the PR review, anywhere we return a tuple of more than one type or a loose dict could benefit from a richer type — modeled onflepimop2._utils._module.ParsedShorthand(NamedTuple + colocatedfrom_*classmethod).Concrete first targets:
_axes.py: per-axis dict (name/type/coords/size/deltas/...) →_NormalizedAxis(NamedTuple) withfrom_mappingclassmethod._constraints.py:_ConstraintRulealready exists; align by addingfrom_mappingclassmethod that absorbs the per-rule validation currently in_validate_constraint_axes/_resolve_constraint_mode/_validate_constraint_rule._normalize.py: tuples returned by_split_*/_parse_*selector helpers (e.g.(base, axes_map))._templates.py:expand_selectorreturnslist[tuple[str, dict[str, str]]]; could belist[_ExpandedSelector].compile.py: anywhere a tuple of(values, kwargs)or similar is returned.Naming convention for these records is captured in
docs/development/code-style.md(added in PR #83): NamedTuple by default, frozen dataclass when behaviour beyond a value record is needed, parser colocated asfrom_*classmethod, underscore-prefixed when scoped to an internal module.Shareable-utilities discussion
Aside raised by @joshuamacdonald during PR #83 review: we don't want to require plugin developers to depend on flepimop2-core, but we want to encourage consistent configuration standards. A lot of the parsing utilities currently in
op_system\._*(axis parsing, bracket selector parsing, constraint validation) would be useful to engine/parameter plugin authors.Options to evaluate:
op_system; plugin authors copy or re-implement.flepimop2-utilspackage — factor a tiny standalone utilities package that bothop_systemand plugin authors can depend on without pulling in core.op_system.utilsnamespace — re-export a curated subset of the current internal helpers via a public module with a documented stability contract.Decision should be informed by:
flepimop2#255).