API#

The PyMetKit API provides a Pythonic interface to metkit’s MARS request model. A MarsRequest is a verb together with a MarsSelection — a type alias for a user-supplied key-value mapping. Values are normalised at construction time (scalars wrapped, collections stringified) and stored directly in the underlying C++ object. Operations that require the MARS language engine (expansion, validation, equality, merging and parsing) are delegated to metkit through the pybind11 bindings layer. Splitting is a structural operation and does not require the language engine.

MarsRequest#

class MarsRequest(verb: str, selection: MarsSelection | None = None, /)#

A MARS request: a verb and a MarsSelection.

Values are normalised on construction (scalars wrapped, numbers stringified, /-separated strings split). The C++ _MarsRequest is the sole backing store.

Parameters:

  • verb – Request verb, e.g. "retrieve".

  • selection – Initial parameter values.

Examples

>>> request = MarsRequest("retrieve", {"class": "od", "date": "20200101/20200102", "param": [151, 129]})
>>> request.verb()
'retrieve'
>>> request["class"]
'od'
>>> request["date"]
['20200101', '20200102']
>>> request["param"]
['151', '129']
expand(inherit: bool = True, strict: bool = False) → MarsRequest#

Return the expanded request.

Prefer expand() for multiple requests.

Parameters:

  • inherit – Populate missing keys with MARS defaults.

  • strict – Raise on invalid values instead of warning.

Raises:

MetKitException – If the request is incompatible with the MARS language definition.

keys() → collections.abc.Iterator[str]#

Iterate over parameter names.

merge(other: MarsRequest) → MarsRequest#

Merge other into this request and return a new object.

Neither input is modified. self’s values take precedence; missing values from other are appended. The result is validated.

Parameters:

other – Request to merge with.

Raises:

  • ValueError – If the parameter sets differ.

  • MetKitException – If the merged result is invalid.

num_values(param: str) → int#

Return the number of values for param. Raises KeyError if absent.

split(keys: list[str]) → list[MarsRequest]#

Return one request per value combination across keys.

Structural operation — does not require the MARS language definitions.

Parameters:

keys – Parameters to split on.

validate() → None#

Validate against the MARS language definition without inheriting defaults.

Raises:

MetKitException – If any value is invalid.

verb() → str#

Return the verb.

Expansion#

expand(mars_requests: list[MarsRequest] | MarsRequest, inherit: bool = True, strict: bool = False) → list[MarsRequest] | MarsRequest#

Expand one or more requests against the MARS language definition.

Internal language checks are performed once for the whole batch rather than once per request. Pass a list whenever expanding more than one request.

A single MarsRequest may also be passed directly; the return type matches the input shape.

Parameters:

  • mars_requests (MarsRequest | list[MarsRequest]) – The request or requests to expand.

  • inherit (bool) – If True, populate the result with default values for missing parameters.

  • strict (bool) – If True, raise on invalid values instead of issuing a warning.

Returns:

The expanded request(s). A single input returns a single output.

Return type:

MarsRequest | list[MarsRequest]

Raises:

MetKitException – If a request is incompatible with the MARS language definition.

Examples

>>> requests = [
...     MarsRequest("retrieve", {"class": "od", "date": "-1", "param": "130"}),
...     MarsRequest("retrieve", {"class": "od", "date": "-1", "param": "131"}),
... ]
>>> expanded = expand(requests)
>>> len(expanded)
2

Parsing#

parse_mars_request(file_or_str: IO | str, strict: bool = False) → list[pymetkit.pymetkit.MarsRequest]#

Parse one or more MARS requests from a string or file-like object.

Parameters:

  • file_or_str (str | IO) – MARS request text, or an open file containing it.

  • strict (bool) – If True, raise on invalid values instead of discarding them.

Returns:

The parsed requests, in the order they appear in the input.

Return type:

list[MarsRequest]

Raises:

MetKitException – If the input cannot be parsed.

MarsSelection#

MarsSelection#

User-facing selection. Values may be scalars, collections, or /-separated strings.

Exceptions#

exception pymetkit.MetKitException#

Raised when the underlying metkit library reports an error, for example when expand() or validate() encounters a request that is incompatible with the MARS language definition. Subclasses RuntimeError.