ds_protocol_soap_py_lib ======================= .. py:module:: ds_protocol_soap_py_lib .. autoapi-nested-parse:: **File:** ``__init__.py`` **Region:** ``ds-protocol-soap-py-lib`` Description ----------- A Python package from the ds-protocol-soap-py-lib library. .. rubric:: Example .. code-block:: python from ds_protocol_soap_py_lib import __version__ print(f"Package version: {__version__}") Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/ds_protocol_soap_py_lib/dataset/index /autoapi/ds_protocol_soap_py_lib/enums/index /autoapi/ds_protocol_soap_py_lib/linked_service/index Attributes ---------- .. autoapisummary:: ds_protocol_soap_py_lib.__version__ Classes ------- .. autoapisummary:: ds_protocol_soap_py_lib.SoapDataset ds_protocol_soap_py_lib.SoapDatasetSettings ds_protocol_soap_py_lib.SoapLinkedService ds_protocol_soap_py_lib.SoapLinkedServiceSettings Package Contents ---------------- .. py:data:: __version__ .. 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. .. py:class:: SoapLinkedService Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService`\ [\ :py:obj:`SoapLinkedServiceSettingsType`\ ], :py:obj:`Generic`\ [\ :py:obj:`SoapLinkedServiceSettingsType`\ ] Linked service for SOAP APIs. Wraps a ``zeep.Client`` and handles WSDL loading, transport setup, and authentication. The client is available via the ``connection`` property after ``connect()`` is called. Supports use as a context manager:: with linked_service: result = linked_service.connection.service.SomeMethod(...) .. py:attribute:: settings :type: SoapLinkedServiceSettingsType .. py:attribute:: _client :type: zeep.Client | None :value: None .. py:attribute:: _credential :type: str | None :value: None .. py:property:: type :type: ds_protocol_soap_py_lib.enums.ResourceType Get the type of the linked service. :returns: ResourceType .. py:property:: connection :type: zeep.Client Return the zeep Client established by ``connect()``. :returns: zeep.Client :raises ConnectionError: If ``connect()`` has not been called. .. py:property:: body_auth_params :type: dict[str, str] Return keyword authentication parameters for SOAP method calls. For BASIC_WITH_TOKEN_EXCHANGE auth, returns ``{credential_param_key: credential}``. For PARAMETER_BASED auth, returns the configured body parameters. :returns: dict[str, str] :raises ConnectionError: If auth_type is BASIC_WITH_TOKEN_EXCHANGE and no credential is set (i.e. ``connect()`` has not been called). .. py:method:: _init_client() -> zeep.Client Initialise the zeep Client from the WSDL and configured transport/settings. :returns: zeep.Client :raises ConnectionError: If the WSDL cannot be reached or parsed. .. py:method:: _configure_basic_auth(client: zeep.Client) -> None Configure HTTP Basic authentication on the transport session. :param client: The zeep Client to configure. :raises LinkedServiceException: If basic auth settings are missing. .. py:method:: _configure_basic_with_token_exchange_auth(client: zeep.Client) -> None Exchange credentials for a session token via a dedicated auth WSDL. Opens a temporary HTTP Basic Auth session against ``auth_wsdl``, calls ``auth_method`` to retrieve a session token, stores it in ``_credential``, then closes the auth session. The token is injected into all subsequent data calls via ``body_auth_params``. The ``client`` argument is unused — the data WSDL client is not involved in the exchange. :param client: Unused. Present for dispatch-table consistency with other auth handlers. :raises LinkedServiceException: If basic_with_token_exchange settings are missing or the credential exchange call fails. .. py:method:: _configure_parameter_based_auth(client: zeep.Client) -> None Validate that parameter-based auth settings are present. Parameters are not applied to the transport — they are passed per-call via ``body_auth_params``. :param client: The zeep Client (unused; present for dispatch-table consistency). :raises LinkedServiceException: If parameter-based auth settings are missing. .. py:method:: connect() -> None Load the WSDL and configure authentication. Stores the initialised ``zeep.Client`` internally so it is accessible via the ``connection`` property. Verifies the connection by calling ``auth_test_method`` before returning. Safe to call multiple times — re-connects on each call. :returns: None :raises ConnectionError: If the WSDL cannot be reached or parsed. :raises LinkedServiceException: If auth settings are missing, auth_type is unsupported, or the connection test call fails (wrong credentials, method, or parameters). .. py:method:: test_connection() -> tuple[bool, str] Verify the connection to the SOAP API by calling ``auth_test_method``. Does not raise on failure — returns ``(False, reason)`` instead. Returns ``(False, "No auth_test_method configured")`` if ``auth_test_method`` is not set. :returns: ``(True, "")`` on success, ``(False, reason)`` on failure. :rtype: tuple[bool, str] .. py:method:: close() -> None Close the underlying requests session, release the zeep Client, and clear the session credential. Safe to call multiple times. .. py:method:: _build_body_auth_params() -> dict[str, str] Build the authentication parameter dict for parameter-based auth. :returns: dict[str, str] .. py:class:: SoapLinkedServiceSettings Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedServiceSettings` Settings for SOAP linked service connections. Provide the appropriate auth settings object based on your auth_type: - ``AuthType.BASIC`` → ``basic`` - ``AuthType.BASIC_WITH_TOKEN_EXCHANGE`` → ``basic_with_token_exchange`` - ``AuthType.PARAMETER_BASED`` → ``parameter_based`` .. rubric:: Example >>> settings = SoapLinkedServiceSettings( ... wsdl="https://api.example.com?WSDL", ... auth_type=AuthType.BASIC, ... auth_test_method="SomeHealthCheckMethod", ... basic=BasicAuthSettings( ... username="user", ... password="pass", ... ), ... ) .. py:attribute:: wsdl :type: str The WSDL endpoint URL. .. py:attribute:: auth_type :type: ds_protocol_soap_py_lib.enums.AuthType The authentication type to use. .. py:attribute:: auth_test_method :type: str | None :value: None The SOAP operation name used to verify the connection during ``connect()`` and ``test_connection()``. Authentication in SOAP happens at call time, so a real method must be invoked to verify credentials. When ``None``, the connection test is skipped and credentials are not verified until the first real call. .. py:attribute:: auth_test_method_params :type: dict[str, Any] Optional parameters to include when calling the auth_test_method during connection testing. Useful if the method requires additional non-auth parameters. .. py:attribute:: basic :type: BasicAuthSettings | None :value: None Settings for Basic authentication. Required when auth_type=AuthType.BASIC. .. py:attribute:: basic_with_token_exchange :type: BasicWithTokenExchangeAuthSettings | None :value: None Settings for Basic + token exchange authentication. Required when auth_type=AuthType.BASIC_WITH_TOKEN_EXCHANGE. .. py:attribute:: parameter_based :type: ParameterBasedAuthSettings | None :value: None Settings for parameter-based authentication. Required when auth_type=AuthType.PARAMETER_BASED. .. py:attribute:: cache :type: zeep.cache.Base | None :value: None Optional zeep cache backend. Defaults to no cache. .. py:attribute:: timeout :type: int | float :value: 300 Timeout in seconds for WSDL loading and SOAP calls. Defaults to 300. .. py:attribute:: operation_timeout :type: int | float | None :value: None Timeout in seconds for individual SOAP operations. Defaults to ``timeout``. .. py:attribute:: strict :type: bool :value: True Raise errors on WSDL non-conformance. Defaults to True. .. py:attribute:: raw_response :type: bool :value: False Return the raw requests response instead of parsed objects. Defaults to False. .. py:attribute:: forbid_dtd :type: bool :value: False Forbid DTD in XML responses. Defaults to False. .. py:attribute:: forbid_entities :type: bool :value: True Forbid external entity references in XML. Defaults to True. .. py:attribute:: forbid_external :type: bool :value: True Forbid external resource access in XML. Defaults to True. .. py:attribute:: xml_huge_tree :type: bool :value: False Enable lxml huge_tree option for very large XML responses. Defaults to False. .. py:attribute:: force_https :type: bool :value: True Require HTTPS for SOAP calls. Defaults to True. .. py:attribute:: extra_http_headers :type: dict[str, str] | None :value: None Additional HTTP headers to include in every request. Defaults to None. .. py:attribute:: xsd_ignore_sequence_order :type: bool :value: False Ignore XSD sequence ordering constraints. Defaults to False.