pymetkit
========

.. py:module:: pymetkit


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/pymetkit/__main__/index
   /autoapi/pymetkit/experimental/index
   /autoapi/pymetkit/paramdb/index
   /autoapi/pymetkit/pymetkit/index
   /autoapi/pymetkit/pymetkit_batch/index
   /autoapi/pymetkit/pymetkit_type/index


Attributes
----------

.. autoapisummary::

   pymetkit.MarsSelection


Classes
-------

.. autoapisummary::

   pymetkit.MarsRequest


Functions
---------

.. autoapisummary::

   pymetkit.expand
   pymetkit.parse_mars_request


Package Contents
----------------

.. py:data:: MarsSelection

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

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

   A MARS request: a verb and a :data:`MarsSelection`.

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

   :param verb: Request verb, e.g. ``"retrieve"``.
   :param selection: Initial parameter values.

   .. rubric:: 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']


   .. py:attribute:: _internal


   .. py:method:: _to_internal() -> pymetkit._internal._MarsRequest


   .. py:method:: _from_internal(internal: pymetkit._internal._MarsRequest) -> MarsRequest
      :classmethod:



   .. py:method:: verb() -> str

      Return the verb.



   .. py:method:: keys() -> collections.abc.Iterator[str]

      Iterate over parameter names.



   .. py:method:: num_values(param: str) -> int

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



   .. py:method:: expand(inherit: bool = True, strict: bool = False) -> MarsRequest

      Return the expanded request.

      Prefer :func:`~pymetkit.pymetkit_batch.expand` for multiple requests.

      :param inherit: Populate missing keys with MARS defaults.
      :param strict: Raise on invalid values instead of warning.

      :raises MetKitException: If the request is incompatible with the MARS language definition.



   .. py:method:: split(keys: list[str]) -> list[MarsRequest]

      Return one request per value combination across *keys*.

      Structural operation — does not require the MARS language definitions.

      :param keys: Parameters to split on.



   .. py:method:: validate() -> None

      Validate against the MARS language definition without inheriting defaults.

      :raises MetKitException: If any value is invalid.



   .. py:method:: 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.

      :param other: Request to merge with.

      :raises ValueError: If the parameter sets differ.
      :raises MetKitException: If the merged result is invalid.



   .. py:method:: __iter__() -> collections.abc.Iterator[tuple[str, str | list[str]]]

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



   .. py:method:: __getitem__(param: str) -> str | list[str]

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



   .. py:method:: __setitem__(param: str, values) -> None

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



   .. py:method:: __contains__(param: str) -> bool


   .. py:method:: __eq__(other: object) -> bool

      Expand both sides and compare. Resolves MARS aliases.



   .. py:method:: __repr__() -> str


.. py:function:: 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 :class:`MarsRequest` may also be passed directly; the return type
   matches the input shape.

   :param mars_requests: The request or requests to expand.
   :type mars_requests: MarsRequest | list[MarsRequest]
   :param inherit: If True, populate the result with default values for missing parameters.
   :type inherit: bool
   :param strict: If True, raise on invalid values instead of issuing a warning.
   :type strict: bool

   :returns: The expanded request(s). A single input returns a single output.
   :rtype: MarsRequest | list[MarsRequest]

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

   .. rubric:: Examples

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


.. py:function:: 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.

   :param file_or_str: MARS request text, or an open file containing it.
   :type file_or_str: str | IO
   :param strict: If True, raise on invalid values instead of discarding them.
   :type strict: bool

   :returns: The parsed requests, in the order they appear in the input.
   :rtype: list[MarsRequest]

   :raises MetKitException: If the input cannot be parsed.