mundane.api.schemas
===================

.. py:module:: mundane.api.schemas

.. autoapi-nested-parse::

   Translate action JSON (a tagged union) into engine action dataclasses.

   Every action body carries a ``type`` discriminator, e.g.
   ``{"type": "play_card", "player": 0, "hand_index": 0}``. The tags are exactly the keys of the
   engine's canonical ``ACTION_TYPES`` registry, so the HTTP surface mirrors the engine and the
   round-trip ``action_to_dict`` -> :func:`parse_action` is the identity (covered by a test).

   A body that does not describe a valid action — unknown ``type``, missing field, wrong field type —
   is rejected with :class:`IllegalAction`, which the app maps to HTTP 422. No legality lives here; this
   is pure translation.



Functions
---------

.. autoapisummary::

   mundane.api.schemas._require_int
   mundane.api.schemas._optional_int
   mundane.api.schemas.parse_action


Module Contents
---------------

.. py:function:: _require_int(body: dict[str, object], key: str) -> int

   Return ``body[key]`` as an int, or reject the action if it is missing or not an integer.


.. py:function:: _optional_int(body: dict[str, object], key: str) -> int | None

   Return ``body[key]`` as an int, or None when it is absent or explicitly null.


.. py:function:: parse_action(body: dict[str, object]) -> mundane.engine.actions.Action

   Parse a tagged-union action body into the matching action dataclass.