ds_protocol_soap_py_lib

File: __init__.py Region: ds-protocol-soap-py-lib

Description

A Python package from the ds-protocol-soap-py-lib library.

Example

from ds_protocol_soap_py_lib import __version__

print(f"Package version: {__version__}")

Submodules

• ds_protocol_soap_py_lib.dataset
• ds_protocol_soap_py_lib.enums
• ds_protocol_soap_py_lib.linked_service

Attributes

__version__

Classes

SoapDataset	Dataset for SOAP APIs.
SoapDatasetSettings	Settings for SOAP dataset.
SoapLinkedService	Linked service for SOAP APIs.
SoapLinkedServiceSettings	Settings for SOAP linked service connections.

Package Contents

ds_protocol_soap_py_lib.__version__

class ds_protocol_soap_py_lib.SoapDataset

Bases: ds_resource_plugin_py_lib.common.resource.dataset.TabularDataset[SoapLinkedServiceType, SoapDatasetSettingsType, ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer, ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer], Generic[SoapLinkedServiceType, 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.

linked_service: SoapLinkedServiceType

settings: SoapDatasetSettingsType

deserializer: ds_resource_plugin_py_lib.common.serde.deserialize.PandasDeserializer | None

property type: ds_protocol_soap_py_lib.enums.ResourceType

Get the type of the dataset.

_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.

Parameters:

error_cls – The error class to raise on failure (ReadError or CreateError).

Raises:

ReadError | CreateError – If the SOAP call fails.

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.

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.

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.

• NotSupportedError – If the provider does not support update.

See also

Full contract: docs/DATASET_CONTRACT.md – update()

delete() → NoReturn

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

Raises:

• DeleteError – If the operation fails.

• NotSupportedError – If the provider does not support delete.

See also

Full contract: docs/DATASET_CONTRACT.md – delete()

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.

• NotSupportedError – If the provider does not support upsert.

See also

Full contract: docs/DATASET_CONTRACT.md – upsert()

purge() → NoReturn

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

Raises:

• PurgeError – If the operation fails.

• NotSupportedError – If the provider does not support purge.

See also

Full contract: docs/DATASET_CONTRACT.md – purge()

list() → NoReturn

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

Raises:

• ListError – If the operation fails.

• NotSupportedError – If the provider does not support listing.

See also

Full contract: docs/DATASET_CONTRACT.md – list()

rename() → NoReturn

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

Raises:

• RenameError – If the operation fails.

• NotSupportedError – If the provider does not support renaming.

See also

Full contract: docs/DATASET_CONTRACT.md – rename()

close() → None

Close the linked service connection.

class ds_protocol_soap_py_lib.SoapDatasetSettings

Bases: ds_resource_plugin_py_lib.common.resource.dataset.DatasetSettings

Settings for SOAP dataset.

method: str

The SOAP method to call.

kwargs: dict[str, Any]

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

class ds_protocol_soap_py_lib.SoapLinkedService

Bases: ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService[SoapLinkedServiceSettingsType], Generic[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(...)

settings: SoapLinkedServiceSettingsType

_client: zeep.Client | None = None

_credential: str | None = None

property type: ds_protocol_soap_py_lib.enums.ResourceType

Get the type of the linked service.

Returns:

ResourceType

property connection: zeep.Client

Return the zeep Client established by connect().

Returns:

zeep.Client

Raises:

ConnectionError – If connect() has not been called.

property body_auth_params: 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).

_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.

_configure_basic_auth(client: zeep.Client) → None

Configure HTTP Basic authentication on the transport session.

Parameters:

client – The zeep Client to configure.

Raises:

LinkedServiceException – If basic auth settings are missing.

_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.

Parameters:

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.

_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.

Parameters:

client – The zeep Client (unused; present for dispatch-table consistency).

Raises:

LinkedServiceException – If parameter-based auth settings are missing.

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.

• LinkedServiceException – If auth settings are missing, auth_type is unsupported, or the connection test call fails (wrong credentials, method, or parameters).

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.

Return type:

tuple[bool, str]

close() → None

Close the underlying requests session, release the zeep Client, and clear the session credential.

Safe to call multiple times.

_build_body_auth_params() → dict[str, str]

Build the authentication parameter dict for parameter-based auth.

Returns:

dict[str, str]

class ds_protocol_soap_py_lib.SoapLinkedServiceSettings

Bases: 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

Example

>>> settings = SoapLinkedServiceSettings(
...     wsdl="https://api.example.com?WSDL",
...     auth_type=AuthType.BASIC,
...     auth_test_method="SomeHealthCheckMethod",
...     basic=BasicAuthSettings(
...         username="user",
...         password="pass",
...     ),
... )

wsdl: str

The WSDL endpoint URL.

auth_type: ds_protocol_soap_py_lib.enums.AuthType

The authentication type to use.

auth_test_method: str | None = 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.

auth_test_method_params: 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.

basic: BasicAuthSettings | None = None

Settings for Basic authentication. Required when auth_type=AuthType.BASIC.

basic_with_token_exchange: BasicWithTokenExchangeAuthSettings | None = None

Settings for Basic + token exchange authentication. Required when auth_type=AuthType.BASIC_WITH_TOKEN_EXCHANGE.

parameter_based: ParameterBasedAuthSettings | None = None

Settings for parameter-based authentication. Required when auth_type=AuthType.PARAMETER_BASED.

cache: zeep.cache.Base | None = None

Optional zeep cache backend. Defaults to no cache.

timeout: int | float = 300

Timeout in seconds for WSDL loading and SOAP calls. Defaults to 300.

operation_timeout: int | float | None = None

Timeout in seconds for individual SOAP operations. Defaults to timeout.

strict: bool = True

Raise errors on WSDL non-conformance. Defaults to True.

raw_response: bool = False

Return the raw requests response instead of parsed objects. Defaults to False.

forbid_dtd: bool = False

Forbid DTD in XML responses. Defaults to False.

forbid_entities: bool = True

Forbid external entity references in XML. Defaults to True.

forbid_external: bool = True

Forbid external resource access in XML. Defaults to True.

xml_huge_tree: bool = False

Enable lxml huge_tree option for very large XML responses. Defaults to False.

force_https: bool = True

Require HTTPS for SOAP calls. Defaults to True.

extra_http_headers: dict[str, str] | None = None

Additional HTTP headers to include in every request. Defaults to None.

xsd_ignore_sequence_order: bool = False

Ignore XSD sequence ordering constraints. Defaults to False.