ds_provider_xledger_py_lib.utils.graphql
========================================

.. py:module:: ds_provider_xledger_py_lib.utils.graphql

.. autoapi-nested-parse::

   **File:** ``graphql.py``
   **Region:** ``ds_provider_xledger_py_lib/utils``

   Description
   -----------
   Helpers for normalizing GraphQL responses and errors.



Attributes
----------

.. autoapisummary::

   ds_provider_xledger_py_lib.utils.graphql.logger


Functions
---------

.. autoapisummary::

   ds_provider_xledger_py_lib.utils.graphql.raise_for_graphql_errors
   ds_provider_xledger_py_lib.utils.graphql.map_graphql_errors_to_exception
   ds_provider_xledger_py_lib.utils.graphql._build_exception
   ds_provider_xledger_py_lib.utils.graphql._parse_error
   ds_provider_xledger_py_lib.utils.graphql._extract_status_code


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

.. py:data:: logger

.. py:function:: raise_for_graphql_errors(*, body: Any) -> dict[str, Any]

   Raise typed DS exceptions for GraphQL payload errors.

   GraphQL servers may return HTTP 200 while reporting failures under an
   ``errors`` field in the response payload.

   :param body: The GraphQL response body to inspect.

   :returns: The original GraphQL response body when no error is present.


.. py:function:: map_graphql_errors_to_exception(*, errors: list[Any]) -> Exception

   Map GraphQL payload errors to typed Xledger dataset exceptions.

   :param errors: The GraphQL errors to map to exceptions.

   :returns: The mapped exception.


.. py:function:: _build_exception(exc_cls: type[Exception], *, message: str | None = None, status_code: int | None = None) -> Exception

   Instantiate an exception with explicit message and optional status code.

   :param exc_cls: The exception class to instantiate.
   :param message: Optional message to include in the exception.
   :param status_code: Optional HTTP-like status code. When omitted, the
                       exception class handles its own default status behavior.


.. py:function:: _parse_error(error: Any) -> tuple[str, str, str]

   Extract message/code metadata from a GraphQL error object.

   :param error: The GraphQL error to parse.

   :returns: A tuple containing the message, code, and extension code.


.. py:function:: _extract_status_code(error: Any) -> int | None

   Best-effort extraction of HTTP-like status code from GraphQL error.

   :param error: The GraphQL error to extract the status code from.

   :returns: The HTTP-like status code from the GraphQL error.