server.web.utils.json_compat
============================

.. py:module:: server.web.utils.json_compat

.. autoapi-nested-parse::

   Utility functions for JSON compatibility between old and new client versions.



Attributes
----------

.. autoapisummary::

   server.web.utils.json_compat.JSON_COMPAT_CUTOFF_VERSION


Functions
---------

.. autoapisummary::

   server.web.utils.json_compat.deserialize_requested_resources
   server.web.utils.json_compat.normalize_node_ids
   server.web.utils.json_compat.ensure_json_compatible_format
   server.web.utils.json_compat.get_client_compatibility_mode
   server.web.utils.json_compat.normalize_node_ids_for_client


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

.. py:function:: deserialize_requested_resources(raw: Optional[str]) -> Any

   Parse a ``task_resources.requested_resources`` column value.

   New rows are ``json.dumps``'d by ``/task/bind_resources`` (lowercase
   ``true``/``false``/``null``). Older rows are Python ``repr``-style
   (``True``/``False``/``None``) from pre-FastAPI versions. Try JSON
   first, fall back to ``ast.literal_eval``.


.. py:data:: JSON_COMPAT_CUTOFF_VERSION
   :value: '3.4.23'


.. py:function:: normalize_node_ids(node_ids: Any) -> Optional[List[int]]

   Normalize node_ids to a list of integers, supporting both old and new formats.

   :param node_ids: Can be:
                    - None
                    - A list of integers (new format)
                    - A JSON string like "[1, 2, 3]" (old format)
                    - A string representation of a list like "[1, 2, 3]"

   :returns: List of integers or None if input is None/empty

   :raises ValueError: If the input cannot be parsed into a list of integers


.. py:function:: ensure_json_compatible_format(node_ids: Any) -> Any

   Ensure the node_ids are in a format that can be stored in the database.

   This function is used when storing data to ensure consistency.

   :param node_ids: The node_ids to format

   :returns: The node_ids in a format suitable for database storage


.. py:function:: get_client_compatibility_mode(client_version: Optional[str]) -> str

   Determine the compatibility mode based on client version.

   :param client_version: The client version string (e.g., "3.4.10", "3.4.24.dev1",
                          "3.4.24.stage1")

   :returns: "old", "new", or "unknown"
             - "new" for versions with "dev" or "stage" in them
             - "old" for versions <= JSON_COMPAT_CUTOFF_VERSION
             - "new" for versions > JSON_COMPAT_CUTOFF_VERSION
   :rtype: Compatibility mode


.. py:function:: normalize_node_ids_for_client(node_ids: Any, client_version: Optional[str] = None) -> Any

   Normalize node_ids based on client version compatibility.

   :param node_ids: The node_ids to normalize
   :param client_version: The client version string

   :returns:

             - For clients <= JSON_COMPAT_CUTOFF_VERSION: Returns quoted JSON string
               like "[1, 2]" (can be parsed with json.loads)
             - For clients > JSON_COMPAT_CUTOFF_VERSION: Returns unquoted JSON array
               like [1, 2]
   :rtype: The node_ids in the format expected by the client