0
# Zeep
1

2
A comprehensive Python SOAP client library for consuming SOAP web services with support for SOAP 1.1/1.2, WSSE authentication, and async operations. Zeep provides a modern, Pythonic interface for working with SOAP services, automatic WSDL parsing, type conversion, fault handling, and comprehensive error reporting.
3

4
## Package Information
5

6
- **Package Name**: zeep
7
- **Language**: Python
8
- **Installation**: `pip install zeep`
9
- **Requirements**: Python 3.8+
10
- **Optional Dependencies**: 
11
  - `pip install zeep[async]` for async support
12
  - `pip install zeep[xmlsec]` for XML security
13

14
## Core Imports
15

16
```python
17
import zeep
18
from zeep import Client, AsyncClient, Settings, Transport
19
```
20

21
For advanced features:
22

23
```python
24
from zeep import Plugin, CachingClient
25
from zeep.wsse import UsernameToken, Signature
26
from zeep.xsd import AnyObject
27
from zeep.cache import InMemoryCache, SqliteCache
28
from zeep.helpers import serialize_object
29
```
30

31
## Basic Usage
32

33
```python
34
from zeep import Client
35

36
# Create a SOAP client
37
client = Client('http://example.com/service.wsdl')
38

39
# Call a SOAP operation
40
result = client.service.SomeOperation(param1='value1', param2='value2')
41

42
# Work with the result
43
print(result)
44

45
# Access different services/ports if needed
46
specific_service = client.bind('ServiceName', 'PortName')
47
result = specific_service.SomeOperation(param='value')
48
```
49

50
## Architecture
51

52
Zeep is built around several core components:
53

54
- **Client**: Main entry point for SOAP operations (sync/async variants)
55
- **Transport**: HTTP communication layer with caching and session management
56
- **WSDL**: Document parser and operation discovery
57
- **XSD**: XML Schema processing and type conversion
58
- **WSSE**: Web Services Security for authentication and signing
59
- **Plugin System**: Extensible request/response interception
60

61
The library automatically handles WSDL parsing, namespace management, type conversion between Python objects and XML, and provides comprehensive error reporting for debugging SOAP interactions.
62

63
## Capabilities
64

65
### Client Operations
66

67
Core SOAP client functionality for connecting to web services, calling operations, and handling responses. Includes both synchronous and asynchronous clients with automatic WSDL parsing and type conversion.
68

69
```python { .api }
70
class Client:
71
    def __init__(
72
        self, 
73
        wsdl: str, 
74
        wsse=None, 
75
        transport=None, 
76
        service_name=None, 
77
        port_name=None, 
78
        plugins=None, 
79
        settings=None
80
    ): ...
81
    
82
    def bind(self, service_name: str = None, port_name: str = None): ...
83
    def create_service(self, binding_name: str, address: str): ...
84
    def create_message(self, service, operation_name: str, *args, **kwargs): ...
85
    def type_factory(self, namespace: str): ...
86
    def get_type(self, name: str): ...
87
    def get_element(self, name: str): ...
88
    def set_ns_prefix(self, prefix: str, namespace: str): ...
89
    def set_default_soapheaders(self, headers): ...
90

91
class AsyncClient(Client): ...
92
class CachingClient(Client): ...
93
```
94

95
[Client Operations](./client-operations.md)
96

97
### Transport and Settings
98

99
HTTP transport configuration, caching, session management, and XML parsing settings. Controls how zeep communicates with SOAP services and processes XML documents.
100

101
```python { .api }
102
class Transport:
103
    def __init__(
104
        self, 
105
        cache=None, 
106
        timeout: int = 300, 
107
        operation_timeout: int = None, 
108
        session=None
109
    ): ...
110

111
class Settings:
112
    def __init__(
113
        self,
114
        strict: bool = True,
115
        raw_response: bool = False,
116
        force_https: bool = True,
117
        extra_http_headers=None,
118
        xml_huge_tree: bool = False,
119
        forbid_dtd: bool = False,
120
        forbid_entities: bool = True,
121
        forbid_external: bool = True,
122
        xsd_ignore_sequence_order: bool = False
123
    ): ...
124
```
125

126
[Transport and Settings](./transport-settings.md)
127

128
### WSSE Security
129

130
Web Services Security features including username tokens, digital signatures, and authentication mechanisms for secure SOAP communication.
131

132
```python { .api }
133
class UsernameToken:
134
    def __init__(self, username: str, password: str, password_digest: bool = False): ...
135

136
class Signature:
137
    def __init__(self, key_file: str, cert_file: str): ...
138

139
class BinarySignature(Signature): ...
140
class MemorySignature(Signature): ...
141
class Compose: ...
142
```
143

144
[WSSE Security](./wsse-security.md)
145

146
### XSD and Type Handling
147

148
XML Schema processing, type conversion, and handling of complex XML structures. Provides tools for working with XSD types and converting between Python objects and XML.
149

150
```python { .api }
151
class AnyObject:
152
    def __init__(self, xsd_object, value): ...
153

154
# XSD processing utilities and type conversion
155
class Schema: ...
156

157
# XSD constants
158
Nil: object
159
SkipValue: object
160

161
# Helper functions
162
def serialize_object(obj): ...
163
```
164

165
[XSD and Type Handling](./xsd-types.md)
166

167
### Plugin System
168

169
Extensible plugin architecture for intercepting and modifying SOAP requests and responses. Enables custom logging, authentication, caching, and other cross-cutting concerns.
170

171
```python { .api }
172
class Plugin:
173
    def ingress(self, envelope, http_headers, operation): ...
174
    def egress(self, envelope, http_headers, operation, binding_options): ...
175

176
class HistoryPlugin(Plugin):
177
    def __init__(self, maxlen: int = 1): ...
178
```
179

180
[Plugin System](./plugin-system.md)
181

182
### Exception Handling
183

184
Comprehensive exception hierarchy for handling SOAP faults, transport errors, XML parsing issues, and validation failures with detailed error information.
185

186
```python { .api }
187
class Error(Exception): ...
188
class Fault(Error): ...
189
class TransportError(Error): ...
190
class ValidationError(Error): ...
191
class XMLSyntaxError(Error): ...
192
class WsdlSyntaxError(Error): ...
193
```
194

195
[Exception Handling](./exception-handling.md)
196

197
## Types
198

199
```python { .api }
200
# Main client types
201
Client = typing.Type[Client]
202
AsyncClient = typing.Type[AsyncClient]
203
CachingClient = typing.Type[CachingClient]
204

205
# Configuration types  
206
Settings = typing.Type[Settings]
207
Transport = typing.Type[Transport]
208
AsyncTransport = typing.Type[AsyncTransport]
209

210
# Security types
211
UsernameToken = typing.Type[UsernameToken]
212
Signature = typing.Type[Signature]
213

214
# XSD types
215
AnyObject = typing.Type[AnyObject]
216
Schema = typing.Type[Schema]
217

218
# Plugin types
219
Plugin = typing.Type[Plugin]
220
HistoryPlugin = typing.Type[HistoryPlugin]
221

222
# Cache types
223
InMemoryCache = typing.Type[InMemoryCache]
224
SqliteCache = typing.Type[SqliteCache]
225

226
# Helper functions
227
def serialize_object(obj): ...
228
```