pymetkit#

Submodules#

Attributes#

MarsSelection

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

Classes#

MarsRequest

A MARS request: a verb and a MarsSelection.

Functions#

expand(→ list[MarsRequest] | MarsRequest)

Expand one or more requests against the MARS language definition.

parse_mars_request(→ list[pymetkit.pymetkit.MarsRequest])

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

Package Contents#

MarsSelection#

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

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']
_internal#
_to_internal() → pymetkit._internal._MarsRequest#
classmethod _from_internal(internal: pymetkit._internal._MarsRequest) → MarsRequest#
verb() → str#

Return the verb.

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

Iterate over parameter names.

num_values(param: str) → int#

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

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.

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.

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.

__iter__() → collections.abc.Iterator[tuple[str, str | list[str]]]#

Yield (name, value) pairs. Single-value parameters yield a scalar.

__getitem__(param: str) → str | list[str]#

Return the value(s) for param. Raises KeyError if absent.

__setitem__(param: str, values) → None#

Set param. Accepts the same value forms as the constructor.

__contains__(param: str) → bool#
__eq__(other: object) → bool#

Expand both sides and compare. Resolves MARS aliases.

__repr__() → str#
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
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.