The SOAPpy module can be installed by:

1. Using the system package manager install/update the appropriate package, for example:
   • python-soappy for Debain based Linux systems (e.g. Ubuntu or Bio-Linux)
   • SOAPpy for RedHat/Fedora based Linux systems.
2. Downloading the SOAPpy distribution and installing manually:
   • GitHub kiorky/SOAPpy
   • Python Web Services Project (versions up to 0.12.0)

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

• PyXML: http://pyxml.sourceforge.net/topics/
• fpconst: http://research.warnes.net/projects/rzope/fpconst/
  • Mirror at EBI: fpconst-0.7.2.zip

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

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.

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

# Import SOAPpy WSDL package.
from SOAPpy import WSDL
 
# WSDbfetch WSDL URL.
wsdlUrl = 'http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl';
# 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

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/dbfetch_soappy_call.pl):

# Import SOAPpy WSDL package.
from SOAPpy import SOAPProxy
 
# WSDbfetch endpoint URL.
endpointUrl = 'http://www.ebi.ac.uk/ws/services/WSDbfetch';
# WSDbfetch XML namespace.
xmlNamespace = 'http://www.ebi.ac.uk/ws/services/WSDbfetch'
# 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

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/wublast_soaplite.py):

# Import WSDL package
from SOAPpy import WSDL
 
# Create service interface
wsdlUrl = 'http://www.ebi.ac.uk/Tools/webservices/wsdl/WSWUBlast.wsdl'
server = WSDL.Proxy(wsdlUrl)
 
# Query sequence
seq = """>Q8E5Q5_STRA3
MKLSKRYRFWQKVIKALGVLALIATLVLVVYLYKLGILNDSNELKDLVHKYEFWGPMIFI
VAQIVQIVFPVIPGGVTTVAGFLIFGPTLGFIYNYIGIIIGSVILFWLVKFYGRKFVLLF
MDQKTFDKYESKLETSGYEKFFIFCMASPISPADIMVMITGLSNMSIKRFVTIIMITKPI
SIIGYSYLWIYGGDILKNFLN"""
 
# Structure containing parameters
blast_params = {
  'program':'blastp',      # Protein vs. protein search
  'database':'swissprot',  # Database to search
  'email':'your@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':
        time.sleep(15)
 
# Get the result
result = server.poll(jobId, 'tooloutput')
print result

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

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

try:
    # 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 = 'proxy.example.com:8080'

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="http://proxy.example.com:8080")
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://', '')
else:
    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 (http://pywebsvcs.sf.net), 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 (pywebsvcs.sf.net)
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.

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.

• Dive Into Python, Chapter 12. SOAP Web Services