ds_protocol_soap_py_lib.dataset
===============================

.. py:module:: ds_protocol_soap_py_lib.dataset

.. autoapi-nested-parse::

   **File:** ``__init__.py``
   **Region:** ``ds_protocol_soap_py_lib/dataset``

   SOAP Dataset

   This module implements a dataset for SOAP APIs.

   .. rubric:: Example

   >>> import uuid
   >>> from ds_protocol_soap_py_lib.dataset.soap import SoapDataset, SoapDatasetSettings
   >>> from ds_protocol_soap_py_lib.enums import AuthType
   >>> from ds_protocol_soap_py_lib.linked_service.soap import (
   ...     ParameterBasedAuthSettings,
   ...     SoapLinkedService,
   ...     SoapLinkedServiceSettings,
   ... )
   >>> linked_service = SoapLinkedService(
   ...     id=uuid.uuid4(),
   ...     name="example::linked_service",
   ...     version="1.0.0",
   ...     settings=SoapLinkedServiceSettings(
   ...         wsdl="https://example.com/service?wsdl",
   ...         auth_type=AuthType.PARAMETER_BASED,
   ...         auth_test_method="Ping",
   ...         parameter_based=ParameterBasedAuthSettings(
   ...             auth_param_key1="apiKey",
   ...             auth_param_value1="my-token",
   ...         ),
   ...     ),
   ... )
   >>> dataset = SoapDataset(
   ...     id=uuid.uuid4(),
   ...     name="example::dataset",
   ...     version="1.0.0",
   ...     settings=SoapDatasetSettings(method="GetRecords"),
   ...     linked_service=linked_service,
   ... )
   >>> dataset.read()
   >>> data = dataset.output



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_protocol_soap_py_lib/dataset/soap/index


Classes
-------

.. autoapisummary::

   ds_protocol_soap_py_lib.dataset.SoapDataset
   ds_protocol_soap_py_lib.dataset.SoapDatasetSettings


Package Contents
----------------

.. py:class:: SoapDataset

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.TabularDataset`\ [\ :py:obj:`SoapLinkedServiceType`\ , :py:obj:`SoapDatasetSettingsType`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer`\ ], :py:obj:`Generic`\ [\ :py:obj:`SoapLinkedServiceType`\ , :py:obj:`SoapDatasetSettingsType`\ ]


   Dataset for SOAP APIs.

   Calls a configured SOAP method via the linked service connection.
   Authentication parameters from the linked service are automatically
   injected into each call.

   ``read()`` fetches data from the SOAP endpoint and populates ``self.output``.
   ``create()`` sends data to the SOAP endpoint.
   All other operations raise ``NotSupportedError``.


   .. py:attribute:: linked_service
      :type:  SoapLinkedServiceType


   .. py:attribute:: settings
      :type:  SoapDatasetSettingsType


   .. py:attribute:: deserializer
      :type:  ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer | None


   .. py:property:: type
      :type: ds_protocol_soap_py_lib.enums.ResourceType


      Get the type of the dataset.


   .. py:method:: _invoke_method(error_cls: type[ds_resource_plugin_py_lib.common.resource.dataset.errors.ReadError | ds_resource_plugin_py_lib.common.resource.dataset.errors.CreateError]) -> Any

      Call the configured SOAP method and return the serialized response.

      Returns ``None`` if the SOAP response is empty.

      :param error_cls: The error class to raise on failure (``ReadError`` or ``CreateError``).

      :raises ReadError | CreateError: If the SOAP call fails.



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

      Call the configured SOAP method and populate ``self.output``.

      The zeep response is serialised to native Python types via
      ``zeep.helpers.serialize_object`` and normalised into a DataFrame.

      :raises ReadError: If the SOAP call fails or no deserializer is configured.



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

      Call the configured SOAP method to create an entity.

      Returns immediately if ``self.input`` is empty (no-op).
      Calls the SOAP method with auth params and ``settings.kwargs``.
      Sets ``self.output`` to the deserialized backend response, or a
      copy of ``self.input`` if the response is empty or no deserializer is configured.

      :raises CreateError: If the SOAP call fails.



   .. py:method:: update() -> NoReturn

      Update existing rows in the target matched by identity columns
      defined in ``self.settings``. Atomic. Must not insert new rows.

      :raises UpdateError: If the operation fails.
      :raises NotSupportedError: If the provider does not support update.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``update()``



   .. py:method:: delete() -> NoReturn

      Remove specific rows from the target matched by identity columns
      defined in ``self.settings``. Atomic. Idempotent.

      :raises DeleteError: If the operation fails.
      :raises NotSupportedError: If the provider does not support delete.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``delete()``



   .. py:method:: upsert() -> NoReturn

      Insert rows that do not exist, update rows that do, matched by
      identity columns defined in ``self.settings``. Atomic.

      :raises UpsertError: If the operation fails.
      :raises NotSupportedError: If the provider does not support upsert.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``upsert()``



   .. py:method:: purge() -> NoReturn

      Remove all content from the target. ``self.input`` is not used.
      Atomic. Idempotent.

      :raises PurgeError: If the operation fails.
      :raises NotSupportedError: If the provider does not support purge.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``purge()``



   .. py:method:: list() -> NoReturn

      Discover available resources and populate ``self.output`` with a
      DataFrame of resources and their metadata. Idempotent.

      :raises ListError: If the operation fails.
      :raises NotSupportedError: If the provider does not support listing.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``list()``



   .. py:method:: rename() -> NoReturn

      Rename the resource in the backend. Atomic. Not idempotent.

      :raises RenameError: If the operation fails.
      :raises NotSupportedError: If the provider does not support renaming.

      .. seealso:: Full contract: ``docs/DATASET_CONTRACT.md`` -- ``rename()``



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

      Close the linked service connection.



.. py:class:: SoapDatasetSettings

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.DatasetSettings`


   Settings for SOAP dataset.


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

      The SOAP method to call.


   .. py:attribute:: kwargs
      :type:  dict[str, Any]

      Additional keyword arguments to pass to the SOAP method alongside
      the auth parameters from the linked service.