The SOAPpy module can be installed by:

  1. Using an operating system package manager install/update the appropriate package. For example:
    1. On Debain Linux or Debain based Linux distributions (e.g. Bio-Linux, Linux Mint or Ubuntu), install the python-soappy package:
      sudo apt-get install python-soappy
    2. On RedHat based Linux distributions (e.g. CentOS, Fedora, Red Hat Enterprise Linux, and Scientific Linux) install the SOAPpy package:
      yum install SOAPpy
    3. If using MacPorts on OS X install the py-soappy package.
  2. Downloading the SOAPpy distribution and installing manually:

Note: SOAPpy depends on the following Python modules, which also need to be installed:

For an overview of how to install a module see Installing Python Modules.

Accessing a Service

There are two ways to use SOAPpy to access a SOAP Web Service:

  1. Generate a dynamic interface to the service (service proxy) from a WSDL at runtime.
  2. Directly invoke SOAP calls against the service.

Dynamic Interface from a WSDL

SOAPpy provides a simple interface to services which provide a WSDL description. For example using the WSDbfetch service (examples/SOAP/SOAPpy/

# Import SOAPpy WSDL package.
from SOAPpy import WSDL
# WSDbfetch WSDL URL.
wsdlUrl = '';
# Default option values.
query = 'uniprot:wap_rat'
format = 'fasta'
style = 'raw'
# Create a service proxy from the WSDL.
dbfetchSrv = WSDL.Proxy(wsdlUrl)
# Perform the query.
result = dbfetchSrv.fetchData(query, format, style)
# Output the result.
print result

Direct SOAP Calls

If a WSDL is not available for the Web Service, then direct calls can be made to the service using the call method. For example using WSDbfetch by performing direct calls (examples/SOAP/SOAPpy/

# Import SOAPpy WSDL package.
from SOAPpy import SOAPProxy
# WSDbfetch endpoint URL.
endpointUrl = ''
# WSDbfetch XML namespace.
xmlNamespace = ''
# Default option values.
query = 'uniprot:wap_rat'
format = 'fasta'
style = 'raw'
# Create a service interface.
dbfetchSrv = SOAPProxy(endpointUrl, namespace=xmlNamespace)
# Perform the query.
result = dbfetchSrv.fetchData(query, format, style)
# Output the result.
print result

Complex Data Structures

The methods in the WSDbfetch all use simple string parameters. Many of the other EBI services use more complex input structures. For example WSWUBlast requires a structure containing the various parameters and the input sequence to be passed to the runWUBlast method (examples/SOAP/SOAPpy/

# Import WSDL package
from SOAPpy import WSDL
# Create service interface
wsdlUrl = ''
server = WSDL.Proxy(wsdlUrl)
# Query sequence
seq = """>Q8E5Q5_STRA3
# Structure containing parameters
blast_params = {
  'program':'blastp',          # Protein vs. protein search
  'database':'swissprot',      # Database to search
  'email':'', # User e-mail address
  'async':1                    # Async submission
# Structure containing the sequence data
blast_data = [{'type':'sequence', 'content':seq}]
# Submit the job to the service passing the data structures
jobId = server.runWUBlast(params=blast_params,content=blast_data)
print jobId

The runWUBlast method returns a job identifier which can be used with the checkStatus method to get the status of the job (e.g. RUNNING, DONE or ERROR) and the poll method to get the results of the job.

# Poll till job finishes
status = 'PENDING'
while status == 'RUNNING' or status == 'PENDING':
    status = server.checkStatus(jobId)
    print status
    if status == 'RUNNING' or status == 'PENDING':
# Get the result
result = server.poll(jobId, 'tooloutput')
print result

SOAP Message Trace

It is useful when debugging a client to be able to see the actual SOAP messages exchanged. SOAPpy provides a trace option which can be used to enable output of these messages:

server = WSDL.Proxy(wsdlUrl)
server.soapproxy.config.dumpSOAPOut = 1
server.soapproxy.config.dumpSOAPIn = 1

Alternatively the underlying HTTP library httplib has a debug mode which outputs the complete messages transferred, including the HTTP headers:

import httplib
httplib.HTTPConnection.debuglevel = 1

SOAP Faults

SOAPpy maps SOAP faults into Python exceptions which can be handled in the usual way:

    # Perform the query.
    result = dbfetchSrv.fetchData(query, format, style)
    # Output the result.
    print result
except SOAPpy.Types.faultType, ex:
    print ex


In some environments it is necessary to configure a proxy before a client can connect to external services. To use a HTTP proxy with SOAPpy:

server = WSDL.Proxy(wsdlUrl)
# Configure an HTTP proxy
server.soapproxy.http_proxy = ''

To support the use of the http_proxy or HTTP_proxy environment variables to set the proxy information, which typically include the protocol prefix the following could be used:

server = WSDL.Proxy(wsdlUrl)
# Configure HTTP proxy from OS environment (e.g. http_proxy="")
if os.environ.has_key('http_proxy'):
    http_proxy_conf = os.environ['http_proxy'].replace('http://', '')
elif os.environ.has_key('HTTP_PROXY'):
    http_proxy_conf = os.environ['HTTP_PROXY'].replace('http://', '')
    http_proxy_conf = None
server.soapproxy.http_proxy = http_proxy_conf


HTTP clients usually provide information about what they are, this allows services to handle specific clients differently if necessary, and gives service providers information about how their services are being used. By default SOAPpy sets the HTTP User-Agent header (see RFC2616 section 14.43) to something like SOAPpy 0.12.0 (, where the version number (0.12.0) is the version of SOAPpy. If additional identification of the client is required the a more specific product token (see RFC2616 section 3.8) should be added to the beginning of the User-Agent string:

# Modify the user-agent to add a more specific prefix (see RFC2616 section 14.43)
import SOAPpy
import os
# User-agent string to use:
#   Example-Client/1.0 (Linux) SOAPpy 0.12.0 (
userAgent = 'Example-Client/1.0 (' + os.uname()[0] + ') ' + SOAPpy.Client.SOAPUserAgent()
# Function to return User-agent.
def SOAPUserAgent():
    return userAgent
# Redefine default User-agent function to return custom User-agent.
SOAPpy.Client.SOAPUserAgent = SOAPUserAgent

Note: while the HTTP specification does not define a limit on the size of HTTP headers, web server implementations often do limit the maximum size of an HTTP header to 8KB or 16KB. If the server limit for an HTTP header is exceeded a “400 Bad Request” will be returned by the server.

Sample Clients

Most SOAP Web Services at EMBL-EBI have sample clients which provide command-line access to the service and example code. For Python some of the clients are based on SOAPpy.

Document/literal SOAP

RPC/encoded SOAP

Service Sample client

Further Reading

tutorials/06_programming/python/soap/soappy.txt · Last modified: 2014/03/27 11:49 by hpm