pymetkit
========

.. py:module:: pymetkit


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/pymetkit/__main__/index
   /autoapi/pymetkit/pymetkit/index
   /autoapi/pymetkit/pymetkit_type/index


Attributes
----------

.. autoapisummary::

   pymetkit.MarsSelection


Classes
-------

.. autoapisummary::

   pymetkit.MarsRequest


Functions
---------

.. autoapisummary::

   pymetkit.parse_mars_request


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

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

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

   :param verb: The request verb, e.g. ``retrieve``.
   :type verb: str
   :param selection: Initial parameter values. Scalars are wrapped in a singleton list,
                     collections are stringified, and ``/``-separated strings are split.
   :type selection: MarsSelection, optional

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

   Iterating yields ``(name, value)`` pairs:

   >>> for key, value in request:
   ...     print(key, value)
   class od
   date ['20200101', '20200102']
   param ['151', '129']


   .. py:attribute:: _verb


   .. py:attribute:: selection
      :type:  pymetkit.pymetkit_type.InternalMarsSelection


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


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



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

      Return the request verb.



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

      Return an iterator over the parameter names in the request.



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

      Return the number of values for a parameter.



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

      Return the expanded request.

      :param inherit: If True, populate the expanded request with default values.
      :type inherit: bool
      :param strict: If True, raise an error instead of a warning for invalid values.
      :type strict: bool

      :returns: The request resulting from expansion.
      :rtype: MarsRequest



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



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

      :param other: The request to merge with self.
      :type other: MarsRequest

      :returns: The result of the merge.
      :rtype: MarsRequest

      :raises ValueError: If the parameters in the two requests do not match.
      :raises MetKitException: If the resulting request is not compatible with the MARS language definition.



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


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


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


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


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


   .. py:method:: __hash__() -> int


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


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

   :param file_or_str: A string or file-like object containing one or more MARS requests.
   :type file_or_str: str | IO
   :param strict: 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.
   :type strict: bool

   :rtype: list[MarsRequest]


.. py:data:: 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 :meth:`UserInputMapper.map_selection_to_internal`.

   :type: Selection part of a MARS request