Skip to content

Type-richness sweep: replace tuple/dict returns with named records, plus shareable utilities discussion #85

@jc-macdonald

Description

@jc-macdonald

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:

  1. Status quo — keep utilities private to op_system; plugin authors copy or re-implement.
  2. flepimop2-utils package — factor a tiny standalone utilities package that both op_system and plugin authors can depend on without pulling in core.
  3. 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions