Skip to content

SOAP

Client-independent SOAP support.

SOAP is an HTTP-based protocol

This packages provides implementations specific to SOAP. The generic HTTP features are available as a part of HTTP support.

Markers

Header dataclass

Bases: ParameterMarker[SoapHeader]

Mark parameter as a request header.

An argument gets converted to a dictionary and passed over to a backend.

Examples:

>>> def call(body: Annotated[HeaderModel, Header()]) -> ...:
>>>     ...
Source code in combadge/support/soap/markers.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
@dataclass(**SLOTS)
class Header(ParameterMarker[SoapHeader]):
    """
    Mark parameter as a request header.

    An argument gets converted to a dictionary and passed over to a backend.

    Examples:
        >>> def call(body: Annotated[HeaderModel, Header()]) -> ...:
        >>>     ...
    """

    exclude_unset: bool = False
    by_alias: bool = False

    @override
    def __call__(self, request: SoapHeader, value: Any) -> None:  # noqa: D102
        value = get_type_adapter(cast(Hashable, type(value))).dump_python(
            value,
            by_alias=self.by_alias,
            exclude_unset=self.exclude_unset,
        )
        if request.soap_header is None:
            request.soap_header = value
        elif isinstance(request.soap_header, dict):
            request.soap_header.update(value)  # merge into the existing header
        else:
            raise ValueError(f"attempting to merge `{type(value)}` into `{type(request.soap_header)}`")

    def __class_getitem__(cls, item: type[Any]) -> Any:
        raise NotImplementedError("the shortcut is no longer supported, use `Annotated[..., Header()]`")

operation_name 

operation_name(name: str) -> Callable[[FunctionT], FunctionT]

Mark a service call's operation name.

Examples:

>>> class SupportsNumberConversion(SupportsService):
>>>     @operation_name("NumberToWords")
>>>     def number_to_words(self) -> ...:
>>>         ...
See Also
Source code in combadge/support/soap/markers.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def operation_name(name: str) -> Callable[[FunctionT], FunctionT]:
    """
    Mark a service call's operation name.

    Examples:
        >>> class SupportsNumberConversion(SupportsService):
        >>>     @operation_name("NumberToWords")
        >>>     def number_to_words(self) -> ...:
        >>>         ...

    See Also:
        - [Structure of a WSDL message](https://www.ibm.com/docs/en/rtw/9.0.0?topic=documents-structure-wsdl-message)
    """
    return OperationName[Any](name).mark

Responses

Response extensions for SOAP.

BaseSoapFault

Bases: ErrorResponse

SOAP Fault error response model.

This class is intended for use with the SOAP Fault specification

For custom errors returned in a SOAP response body (such as <error> tag), subclass the ErrorResponse.

Tip

SOAP backends should always fall back to BaseSoapFault if the actual SOAP fault does not match any of the protocol's return types.

For client developers, this means that it is a good idea to include BaseSoapFault as the last possible Union variant to let users know that is should be handled.

Source code in combadge/support/soap/response.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class BaseSoapFault(ErrorResponse):
    """
    [SOAP Fault][1] error response model.

    [1]: https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383507

    Note: This class is intended for use with the SOAP Fault specification
        For custom errors returned in a SOAP response body (such as `<error>` tag),
        subclass the `ErrorResponse`.

    Tip:
        SOAP backends should **always** fall back to `BaseSoapFault` if the actual SOAP fault
        does not match any of the protocol's return types.

        For client developers, this means that it is a good idea to include `BaseSoapFault`
        as the last possible `Union` variant to let users know that is should be handled.
    """

    code: str
    message: str

    def raise_for_result(self, exception: Optional[BaseException] = None) -> NoReturn:
        """Raise the derived error for this fault."""
        if not exception:
            raise self.Error(self)  # type: ignore[arg-type]
        raise exception from self.Error(self)  # type: ignore[arg-type]

raise_for_result 

raise_for_result(exception: Optional[BaseException] = None) -> NoReturn

Raise the derived error for this fault.

Source code in combadge/support/soap/response.py 
29
30
31
32
33
def raise_for_result(self, exception: Optional[BaseException] = None) -> NoReturn:
    """Raise the derived error for this fault."""
    if not exception:
        raise self.Error(self)  # type: ignore[arg-type]
    raise exception from self.Error(self)  # type: ignore[arg-type]