ds_protocol_soap_py_lib.linked_service ====================================== .. py:module:: ds_protocol_soap_py_lib.linked_service .. autoapi-nested-parse:: **File:** ``__init__.py`` **Region:** ``ds_protocol_soap_py_lib/linked_service`` SOAP Linked Service This module implements a linked service for SOAP APIs. .. rubric:: Example >>> import uuid >>> from ds_protocol_soap_py_lib.enums import AuthType >>> from ds_protocol_soap_py_lib.linked_service import ( ... BasicAuthSettings, ... SoapLinkedService, ... SoapLinkedServiceSettings, ... ) >>> linked_service = SoapLinkedService( ... id=uuid.uuid4(), ... name="example::linked_service", ... version="1.0.0", ... settings=SoapLinkedServiceSettings( ... wsdl="https://api.example.com?WSDL", ... auth_type=AuthType.BASIC, ... basic=BasicAuthSettings( ... username="user", ... password="pass", ... ), ... ), ... ) >>> linked_service.connect() Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/ds_protocol_soap_py_lib/linked_service/soap/index Classes ------- .. autoapisummary:: ds_protocol_soap_py_lib.linked_service.BasicAuthSettings ds_protocol_soap_py_lib.linked_service.ParameterBasedAuthSettings ds_protocol_soap_py_lib.linked_service.SoapLinkedService ds_protocol_soap_py_lib.linked_service.SoapLinkedServiceSettings Package Contents ---------------- .. py:class:: BasicAuthSettings Settings for SOAP Basic authentication. Uses standard HTTP Basic auth with base64-encoded username:password on the underlying requests transport. .. py:attribute:: username :type: str The username for basic auth. .. py:attribute:: password :type: str The password for basic auth. .. py:class:: 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``. .. py:attribute:: auth_param_key1 :type: str The key for the first parameter used for authentication in the SOAP body. .. py:attribute:: auth_param_value1 :type: str The value for the first parameter used for authentication in the SOAP body. .. py:attribute:: auth_param_key2 :type: str | None :value: None Additional auth parameter key (optional). .. py:attribute:: auth_param_value2 :type: str | None :value: None Additional auth parameter value (optional). .. py:attribute:: auth_param_key3 :type: str | None :value: None Additional auth parameter key (optional). .. py:attribute:: auth_param_value3 :type: str | None :value: None Additional auth parameter value (optional). .. 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.