ds_provider_xledger_py_lib.linked_service.xledger
=================================================

.. py:module:: ds_provider_xledger_py_lib.linked_service.xledger

.. autoapi-nested-parse::

   Xledger linked service implementation.

   This module provides a linked service for the Xledger GraphQL API. It
   reuses the shared HTTP protocol provider for retries, timeouts, and
   rate limiting, while exposing a provider-specific settings model.

   .. rubric:: Example

   >>> linked_service = XledgerLinkedService(
   ...     settings=XledgerLinkedServiceSettings(
   ...         host="https://demo.xledger.net/graphql",
   ...         token="my-token",
   ...         timeout=60,
   ...     ),
   ... )
   >>> linked_service.connect()
   >>> linked_service.connection.post(
   ...     linked_service.settings.host,
   ...     json={"query": "query { __typename }"},
   ... )



Attributes
----------

.. autoapisummary::

   ds_provider_xledger_py_lib.linked_service.xledger.XledgerLinkedServiceSettingsType


Classes
-------

.. autoapisummary::

   ds_provider_xledger_py_lib.linked_service.xledger.XledgerLinkedServiceSettings
   ds_provider_xledger_py_lib.linked_service.xledger.XledgerLinkedService


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

.. py:class:: XledgerLinkedServiceSettings

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedServiceSettings`


   Connection settings for Xledger GraphQL API.

   .. attribute:: host

      Full GraphQL endpoint URL.

   .. attribute:: token

      API token used for Xledger ``Authorization`` header.

   .. attribute:: headers

      Optional additional default headers.

   .. attribute:: timeout

      Default request timeout in seconds.


   .. py:attribute:: host
      :type:  str
      :value: 'https://demo.xledger.net/graphql'



   .. py:attribute:: token
      :type:  str


   .. py:attribute:: headers
      :type:  dict[str, str] | None
      :value: None



   .. py:attribute:: timeout
      :type:  int | float
      :value: 60



.. py:data:: XledgerLinkedServiceSettingsType

.. py:class:: XledgerLinkedService

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService`\ [\ :py:obj:`XledgerLinkedServiceSettingsType`\ ], :py:obj:`Generic`\ [\ :py:obj:`XledgerLinkedServiceSettingsType`\ ]


   Linked service for Xledger GraphQL API.


   .. py:attribute:: settings
      :type:  XledgerLinkedServiceSettingsType


   .. py:attribute:: _http
      :type:  ds_protocol_http_py_lib.utils.http.provider.Http | None
      :value: None



   .. py:property:: type
      :type: ds_provider_xledger_py_lib.enums.ResourceType


      Return the resource type for this linked service.

      :returns: The linked-service resource identifier enum.
      :rtype: ResourceType


   .. py:property:: connection
      :type: ds_protocol_http_py_lib.utils.http.provider.Http


      Return the established HTTP provider instance.

      :returns: Configured HTTP provider used by datasets.
      :rtype: Http

      :raises ConnectionError: If ``connect()`` has not been called.


   .. py:method:: _init_http() -> ds_protocol_http_py_lib.utils.http.provider.Http

      Build the internal HTTP provider.

      :returns: A configured HTTP provider instance with retry and
                token-bucket rate limiting enabled.
      :rtype: Http



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

      Connect to Xledger by preparing an authenticated HTTP session.

      This method is idempotent. It initializes the HTTP provider on
      first use and updates default headers with bearer authentication.

      :raises AuthenticationError: If the token is missing or blank.



   .. py:method:: test_connection() -> tuple[bool, str]

      Run a lightweight GraphQL probe to verify connectivity.

      :returns: ``(True, "")`` on success, otherwise
                ``(False, error_message)``.
      :rtype: tuple[bool, str]



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

      Close and clear the underlying HTTP provider.

      This method is safe to call multiple times.