ds_protocol_soap_py_lib.linked_service.soap

File: soap.py Region: ds_protocol_soap_py_lib/linked_service/soap

SOAP Linked Service

This module implements a linked service for SOAP APIs.

Four authentication types are supported:

• AuthType.BASIC — HTTP Basic Auth on the transport.

• AuthType.BASIC_WITH_TOKEN_EXCHANGE — HTTP Basic Auth used to call a SOAP method on a dedicated auth WSDL, exchanging credentials for a session token. The token is then injected as a keyword argument into all subsequent data calls.

• AuthType.COOKIE_SESSION — calls a SOAP login method on an auth WSDL and keeps the returned HTTP session cookie on the shared transport session.

• AuthType.PARAMETER_BASED — credentials passed as SOAP body parameters per call.

Example

>>> import uuid
>>> from ds_protocol_soap_py_lib import SoapLinkedService, SoapLinkedServiceSettings
>>> from ds_protocol_soap_py_lib.linked_service.soap import BasicWithTokenExchangeAuthSettings
>>> from ds_protocol_soap_py_lib.enums import AuthType
>>> linked_service = SoapLinkedService(
...     id=uuid.uuid4(),
...     name="example::linked_service",
...     version="1.0.0",
...     settings=SoapLinkedServiceSettings(
...         wsdl="https://ws.example.com/Data.asmx?WSDL",
...         auth_type=AuthType.BASIC_WITH_TOKEN_EXCHANGE,
...         auth_test_method="Ping",
...         basic_with_token_exchange=BasicWithTokenExchangeAuthSettings(
...             auth_wsdl="https://ws.example.com/Auth.asmx?WSDL",
...             username="user",
...             password="pass",
...             auth_method="LogonKey",
...             credential_param_key="sKey",
...         ),
...     ),
... )
>>> linked_service.connect()

Attributes

logger
SoapLinkedServiceSettingsType

Classes

BasicAuthSettings	Settings for SOAP Basic authentication.
BasicWithTokenExchangeAuthSettings	Settings for Basic + token exchange authentication.
CookieSessionAuthSettings	Settings for SOAP cookie-session authentication.
ParameterBasedAuthSettings	Settings for parameter-based authentication.
SoapLinkedServiceSettings	Settings for SOAP linked service connections.
SoapLinkedService	Linked service for SOAP APIs.

Module Contents

ds_protocol_soap_py_lib.linked_service.soap.logger

class ds_protocol_soap_py_lib.linked_service.soap.BasicAuthSettings

Settings for SOAP Basic authentication.

Uses standard HTTP Basic auth with base64-encoded username:password on the underlying requests transport.

username: str

The username for basic auth.

password: str

The password for basic auth.

class ds_protocol_soap_py_lib.linked_service.soap.BasicWithTokenExchangeAuthSettings

Settings for Basic + token exchange authentication.

Uses HTTP Basic Auth to call a SOAP method on a dedicated auth WSDL, exchanging credentials for a session token. The token is stored internally in SoapLinkedService after connect() and injected automatically as a keyword argument in all subsequent data calls via body_auth_params.

auth_wsdl: str

The WSDL endpoint used solely for the credential exchange call.

username: str

The username passed to the credential exchange call.

password: str

The password passed to the credential exchange call.

auth_method: str

The SOAP operation name to call to retrieve the credential.

auth_method_kwargs: dict[str, Any]

Additional keyword arguments to pass to the auth method.

credential_param_key: str

The SOAP body parameter name under which the credential is passed in subsequent calls (e.g. "sKey" for Xledger). The credential is injected via body_auth_params as {credential_param_key: credential}.

class ds_protocol_soap_py_lib.linked_service.soap.CookieSessionAuthSettings

Settings for SOAP cookie-session authentication.

Calls a login operation on an authentication WSDL using the same underlying HTTP session as the data client. Services such as ASP.NET ASMX APIs often set a session cookie (for example ASP.NET_SessionId) during login; the shared session keeps that cookie available for subsequent SOAP calls.

auth_wsdl: str

The WSDL endpoint used for the login call.

credentials: dict[str, Any]

Field/value mapping used to construct the SOAP credential object passed to the login method. Keys must match the fields exposed by credential_type in the authentication WSDL, for example ApplicationId, Username, and Password.

auth_method: str = 'Login'

The SOAP operation name to call for login.

credential_type: str = 'ns0:Credential'

The zeep type name used to construct the SOAP credential object.

credential_param_name: str = 'credential'

The SOAP parameter name that receives the credential object.

auth_method_kwargs: dict[str, Any]

Additional keyword arguments to pass to the login method.

session_check_method: str | None = None

Optional auth-service method to call after login, e.g. HasSession.

session_check_method_kwargs: dict[str, Any]

Optional keyword arguments for session_check_method.

cookie_name: str | None = 'ASP.NET_SessionId'

Optional HTTP cookie name for SOAP services that return the session id from the login method instead of setting it only through Set-Cookie.

cookie_domain: str | None = None

Optional cookie domain for the data service host.

When omitted, the hostname from the linked service wsdl is used. This is required when the auth WSDL and data WSDL run on different subdomains, for example api.example.com vs webservices.example.com.

class ds_protocol_soap_py_lib.linked_service.soap.ParameterBasedAuthSettings

Settings for parameter-based authentication.

Uses custom parameters passed in the SOAP body rather than HTTP headers. Access the resolved parameters via SoapLinkedService.body_auth_params.

auth_param_key1: str

The key for the first parameter used for authentication in the SOAP body.

auth_param_value1: str

The value for the first parameter used for authentication in the SOAP body.

auth_param_key2: str | None = None

Additional auth parameter key (optional).

auth_param_value2: str | None = None

Additional auth parameter value (optional).

auth_param_key3: str | None = None

Additional auth parameter key (optional).

auth_param_value3: str | None = None

Additional auth parameter value (optional).

class ds_protocol_soap_py_lib.linked_service.soap.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.COOKIE_SESSION → cookie_session

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

cookie_session: CookieSessionAuthSettings | None = None

Settings for cookie-session authentication. Required when auth_type=AuthType.COOKIE_SESSION.

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.

ds_protocol_soap_py_lib.linked_service.soap.SoapLinkedServiceSettingsType

class ds_protocol_soap_py_lib.linked_service.soap.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_cookie_session_auth(client: zeep.Client) → None

Authenticate through a SOAP login call that sets an HTTP session cookie.

The auth client uses the same requests session as the data client. This preserves cookies set by the login response for subsequent service calls.

Parameters:

client – The data WSDL client whose transport session should receive cookies.

Raises:

LinkedServiceException – If cookie session settings are missing or the login/session-check call fails.

_resolve_cookie_session_id(client: zeep.Client, auth_settings: CookieSessionAuthSettings, login_result: Any) → str | None

Resolve the session id from the login response or auth-host cookie jar.

_data_service_cookie_domain(auth_settings: CookieSessionAuthSettings) → str | None

_store_cookie_session_login_result(client: zeep.Client, auth_settings: CookieSessionAuthSettings, login_result: Any) → None

Persist the session id as an HTTP cookie for the data service host.

Some SOAP services set the session through Set-Cookie on the auth host while the data service runs on another subdomain. The session id must therefore be attached for the data WSDL hostname before subsequent service calls are made.

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