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 automatically to the internal dict[str, list[str]] representation used by the bindings layer. Operations that require the MARS language engine (expansion, validation, merging and parsing) are delegated to the underlying metkit library through the pybind11 bindings layer.

MarsRequest#

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

A MARS request: a verb (e.g. retrieve) together with a MarsSelection describing the parameters and their values.

Parameters:

  • verb (str) – The request verb, e.g. retrieve.

  • selection (MarsSelection, optional) – Initial parameter values. Scalars are wrapped in a singleton list, collections are stringified, and /-separated strings are split.

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']

Iterating yields (name, value) pairs:

>>> for key, value in request:
...     print(key, value)
class od
date ['20200101', '20200102']
param ['151', '129']
expand(inherit: bool = True, strict: bool = False) → MarsRequest#

Return the expanded request.

Parameters:

  • inherit (bool) – If True, populate the expanded request with default values.

  • strict (bool) – If True, raise an error instead of a warning for invalid values.

Returns:

The request resulting from expansion.

Return type:

MarsRequest

keys() → Iterator[str]#

Return an iterator over the parameter names in the request.

merge(other: MarsRequest) → MarsRequest#

Merge the values of another request into this one and return the result as a new request. Does not modify either input. Both requests must contain the same parameters and the result must be compatible with the MARS language definition.

Parameters:

other (MarsRequest) – The request to merge with self.

Returns:

The result of the merge.

Return type:

MarsRequest

Raises:

  • ValueError – If the parameters in the two requests do not match.

  • MetKitException – If the resulting request is not compatible with the MARS language definition.

num_values(param: str) → int#

Return the number of values for a parameter.

selection: pymetkit.pymetkit_type.InternalMarsSelection#
validate() → None#

Check that the request is valid against the MARS language definition. Does not inherit missing parameters.

Raises:

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

verb() → str#

Return the request verb.

Parsing#

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

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

Parameters:

  • file_or_str (str | IO) – A string or file-like object containing one or more MARS requests.

  • strict (bool) – Whether to raise an error (True) or a warning (False) when a request is not compatible with the MARS language definition. When False, the incompatible parameters are unset from the request.

Return type:

list[MarsRequest]

MarsSelection#

MarsSelection#

a mapping from MARS keys to user-supplied values.

Values may be a scalar (str, int, float) or a collection of those. A str containing / is treated as a MARS range/list expression and split on / by UserInputMapper.map_selection_to_internal().

Type:

Selection part of a MARS request

Exceptions#

exception pymetkit.MetKitException#

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