ds_provider_xledger_py_lib.utils.introspection
==============================================

.. py:module:: ds_provider_xledger_py_lib.utils.introspection

.. autoapi-nested-parse::

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

   Description
   -----------
   Metadata loading helpers for dataset operation contracts.



Classes
-------

.. autoapisummary::

   ds_provider_xledger_py_lib.utils.introspection.MetaField
   ds_provider_xledger_py_lib.utils.introspection.MetaData
   ds_provider_xledger_py_lib.utils.introspection.EntryPointMetaData
   ds_provider_xledger_py_lib.utils.introspection.IntrospectionService


Functions
---------

.. autoapisummary::

   ds_provider_xledger_py_lib.utils.introspection._load_entrypoint_metadata
   ds_provider_xledger_py_lib.utils.introspection._load_operation_metadata
   ds_provider_xledger_py_lib.utils.introspection._read_operation_assets
   ds_provider_xledger_py_lib.utils.introspection._read_operation_asset_texts


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

.. py:class:: MetaField

   Bases: :py:obj:`ds_common_serde_py_lib.serializable.Serializable`


   Single field definition from an operation metadata asset.


   .. py:attribute:: name
      :type:  str


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


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: required
      :type:  bool
      :value: False



   .. py:attribute:: default
      :type:  bool
      :value: False



.. py:class:: MetaData

   Bases: :py:obj:`ds_common_serde_py_lib.serializable.Serializable`


   Operation-level metadata plus packaged GraphQL query template.


   .. py:attribute:: name
      :type:  str


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


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: fields
      :type:  list[MetaField]


   .. py:attribute:: query
      :type:  str


   .. py:attribute:: supportPagination
      :type:  bool
      :value: False



.. py:class:: EntryPointMetaData

   Container for all loaded operations for one entrypoint.


   .. py:attribute:: entrypoint
      :type:  str


   .. py:attribute:: operations
      :type:  dict[ds_provider_xledger_py_lib.enums.OperationType, MetaData]


   .. py:method:: get(*, operation: ds_provider_xledger_py_lib.enums.OperationType) -> MetaData

      Return metadata for a specific operation.

      :param operation: Operation to resolve.

      :returns: Metadata for the requested operation.

      :raises NotSupportedError: If metadata for the operation is unavailable.



   .. py:property:: read
      :type: MetaData | None


      Metadata for read operation, when available.


   .. py:property:: create
      :type: MetaData | None


      Metadata for create operation, when available.


   .. py:property:: update
      :type: MetaData | None


      Metadata for update operation, when available.


   .. py:property:: delete
      :type: MetaData | None


      Metadata for delete operation, when available.


.. py:class:: IntrospectionService

   Load and cache entrypoint metadata for dataset lifecycle reuse.


   .. py:attribute:: entrypoint
      :type:  str


   .. py:attribute:: _metadata
      :type:  EntryPointMetaData | None
      :value: None



   .. py:property:: metadata
      :type: EntryPointMetaData


      Loaded entrypoint metadata.

      :returns: Cached metadata snapshot for the configured entrypoint.


   .. py:method:: load() -> EntryPointMetaData

      Load metadata snapshot if needed and return cached value.

      :returns: Cached metadata snapshot for the configured entrypoint.



   .. py:method:: load_metadata(*, operation: ds_provider_xledger_py_lib.enums.OperationType) -> MetaData

      Return metadata for a single operation.

      :param operation: Operation to resolve.

      :returns: Metadata for the requested operation.



.. py:function:: _load_entrypoint_metadata(entrypoint: str) -> EntryPointMetaData

   Load all available operations for an entrypoint from packaged assets.

   :param entrypoint: Dataset entrypoint (supports nested paths).

   :returns: EntryPointMetaData containing all discovered operations.

   :raises ValidationError: If entrypoint is missing.
   :raises NotSupportedError: If the entrypoint is unsupported.


.. py:function:: _load_operation_metadata(*, entrypoint: str, operation: ds_provider_xledger_py_lib.enums.OperationType) -> MetaData | None

   Load metadata and query template for one operation.

   :param entrypoint: Dataset entrypoint.
   :param operation: Operation to load.

   :returns: Parsed MetaData when assets exist, otherwise ``None``.

   :raises ValidationError: If payload is malformed.


.. py:function:: _read_operation_assets(*, entrypoint: str, operation: ds_provider_xledger_py_lib.enums.OperationType) -> tuple[dict[str, Any], str] | None

   Read raw metadata and query files from package assets.

   :param entrypoint: Dataset entrypoint.
   :param operation: Operation to load.

   :returns: Tuple of (metadata_json_dict, query_graphql_text) when found,
             otherwise ``None``.


.. py:function:: _read_operation_asset_texts(*, entrypoint: str, operation: ds_provider_xledger_py_lib.enums.OperationType) -> tuple[str, str] | None

   Read raw metadata/query text files with process-local memoization.

   :param entrypoint: Dataset entrypoint.
   :param operation: Operation to load.

   :returns: Tuple of (metadata_json_text, query_graphql_text) when found,
             otherwise ``None``.