pelagos_py.utils.parameter_spec#

pelagos_py.utils.parameter_spec.is_required(spec: dict) → bool[source]#

Return whether a single parameter spec describes a required parameter.

pelagos_py.utils.parameter_spec.matches_type(spec: dict, value) → bool[source]#

Return whether value satisfies a single parameter spec’s type.

A spec with no type accepts anything. Special cases:

  • None is accepted when None is the declared default (a sentinel meaning e.g. “compute it”, as with dark_value).

  • bool is a subclass of int but is only accepted when bool is explicitly listed — so acceleration_threshold: no (YAML False) is rejected for a float parameter.

  • an int is accepted where a float is expected (e.g. 20 for a threshold), since YAML has no way to force a whole-number float.

pelagos_py.utils.parameter_spec.type_errors(schema: dict, params: dict) → list[str][source]#

Return "name (expected X, got Y)" messages for type-mismatched params.

Only user-supplied values present in schema are checked; omitted parameters and undeclared keys are out of scope here (defaults are trusted, and unknown keys are handled separately).

pelagos_py.utils.parameter_spec.resolve(schema: dict, params: dict, *, label: str = 'component', allowed_extra=()) → dict[source]#

Resolve user-supplied params against a schema.

Every parameter declared in schema is returned: user values are passed through, omitted optional parameters fall back to their default, and any omitted required parameter raises ValueError.

Unknown parameters — keys present in params but not declared in schema nor listed in allowed_extra — raise ValueError so config typos are caught early. allowed_extra exists for framework/mixin keys that a handler other than the schema consumes (e.g. qc_handling_settings).

Parameters:

  • schema (dict) – The component’s parameter_schema.

  • params (dict) – The user-supplied parameters for this component.

  • label (str, optional) – Name used in error messages (typically the step/QC name).

  • allowed_extra (iterable of str, optional) – Parameter names that are permitted even though they are not in schema.

Returns:

Resolved {name: value} for every parameter in schema.

Return type:

dict

Raises:

ValueError – If a required parameter is missing, or an unknown parameter is supplied.

pelagos_py.utils.parameter_spec.describe(schema: dict) → list[dict][source]#

Return a JSON-serialisable description of a schema.

This can be used to interface with a dashboard (or any external tool).