The Client object

The Client is the main interface for interacting with a SOAP server. It provides a service attribute which references the default binding of the client (via a ServiceProxy object). The default binding can be specified when initiating the client by passing the service_name and port_name. Otherwise the first service and first port within that service are used as the default.

Caching of WSDL and XSD files

When the client is initialized it will automatically retrieve the WSDL file passed as argument. This WSDL file generally references various other WSDL and XSD files. By default Zeep doesn’t cache these files but it is however advised to enable this for performance reasons.

Please see Caching how to enable this. To make it easy to use the zeep.CachingClient() automatically creates a Transport object with SqliteCache enabled.

Configuring the client

The Client class accepts a settings argument to configuring the client. You can initialise the object using the following code:

from zeep import Client, Settings

settings = Settings(strict=False, xml_huge_tree=True)
client = Client('http://my-wsdl/wsdl', settings=settings)

The settings object is always accessible via the client using client.settings. For example:

with client.settings(raw_response=True):
    response = client.service.myoperation()

Please see Settings for more information.

The AsyncClient

The AsyncClient allows you to execute operations in an asynchronous fashion. There is one big caveat however: the wsdl documents are still loaded using synchronous methods. The reason for this is that the codebase was originally not written for asynchronous usage and support that is quite a lot of work.

To use async operations you need to use the AsyncClient() and the corresponding AsyncTransport() (this is the default transport for the AsyncClient)

client = zeep.AsyncClient("http://localhost:8000/?wsdl")

response = await client.service.myoperation()

New in version 4.0.0.

Strict mode

By default zeep will operate in ‘strict’ mode. This can be disabled if you are working with a SOAP server which is not standards compliant by using the strict setting. See Settings. Disabling strict mode will change the following behaviour:

  • The XML is parsed with the recover mode enabled
  • Nonoptional elements are allowed to be missing in xsd:sequences

Note that disabling strict mode should be considered a last resort since it might result in data-loss between the XML and the returned response.

The ServiceProxy object

The ServiceProxy object is a simple object which will check if an operation exists for attribute or item requested. If the operation exists then it will return an OperationProxy object (callable) which is responsible for calling the operation on the binding.

from zeep import Client
from zeep import xsd

client = Client('http://my-endpoint.com/production.svc?wsdl')

# service is a ServiceProxy object.  It will check if there
# is an operation with the name `X` defined in the binding
# and if that is the case it will return an OperationProxy
client.service.X()

# The operation can also be called via an __getitem__ call.
# This is useful if the operation name is not a valid
# python attribute name.
client.service['X-Y']()

Using non-default bindings

As mentioned by default Zeep picks the first binding in the WSDL as the default. This binding is available via client.service. To use a specific binding you can use the bind() method on the client object:

from zeep import Client
from zeep import xsd

client = Client('http://my-endpoint.com/production.svc?wsdl')

service2 = client.bind('SecondService', 'Port12')
service2.someOperation(myArg=1)

for example, if your wsdl contains these definitions

<wsdl:service name="ServiceName">
<wsdl:port name="PortName" binding="tns:BasicHttpsBinding_IServiziPartner">
<soap:address location="https://aaa.bbb.ccc/ddd/eee.svc"/>
</wsdl:port>
<wsdl:port name="PortNameAdmin" binding="tns:BasicHttpsBinding_IServiziPartnerAdmin">
<soap:address location="https://aaa.bbb.ccc/ddd/eee.svc/admin"/>
</wsdl:port>
</wsdl:service>

and you need to calls methods defined in https://aaa.bbb.ccc/ddd/eee.svc/admin you can do:

client = Client("https://www.my.wsdl") # this will use default binding
client_admin = client.bind('ServiceName', 'PortNameAdmin')
client_admin.method1() #this will call method1 defined in service name ServiceName and port PortNameAdmin

Creating new ServiceProxy objects

There are situations where you either need to change the SOAP address from the one which is defined within the WSDL or the WSDL doesn’t define any service elements. This can be done by creating a new ServiceProxy using the Client.create_service() method.

from zeep import Client
from zeep import xsd

client = Client('http://my-endpoint.com/production.svc?wsdl')
service = client.create_service(
    '{http://my-target-namespace-here}myBinding',
    'http://my-endpoint.com/acceptance/')

service.submit('something')

Creating the raw XML documents

When you want zeep to build and return the XML instead of sending it to the server you can use the Client.create_message() call. It requires the ServiceProxy as the first argument and the operation name as the second argument.

from zeep import Client

client = Client('http://my-endpoint.com/production.svc?wsdl')
node = client.create_message(client.service, 'myOperation', user='hi')