Complex Arguments

When working with Web Services, the SUDS documentation and the PyDocs are a good place to start.

In the overview example the methods provided by the web service were very simple and took simple argument types. Sometimes however the web service will describe complex types and allow you create instances of these types that can then be added to the system/machine that the web service is providing an interface for.

A simple, hypothetical example of this would be a system that stores contact information of clients and can be used as an address book of sorts by other systems on the network. It may provide not only a way to pull contact information for a certain individual out but also a way to insert new contacts. We'll keep the example simple and say that contacts have only a name and a phone number.

This example is completely hypothetical. It is intended to give insight into complex types. It does not make use of an an actual functional web service. A very similar example can be found in the SUDS documentation.


Say we create and print the client object we associated with our web service in the following manner

from suds.client import Client
url = 'http://localhost:7575/webservices/hypothetical_webservice?wsdl'
client = Client(url)
print client

And the resulting output is the following:

Suds ( https://fedorahosted.org/suds/ ) version: 0.4 GA build: R699-20100913
Service (hypothetical_webservice)
Prefixes (0):
Ports (1):
(Soap)
Methods:
addContact(Contact contact, )
getContactList(xs:string str, xs:int length, )
getContactByName(Name name, )
Types (3):
Contact
Name
Phone

Here you can see that, while not too complicated the web service defines more than just methods that take simple type arguments and return the same. Under the Types section you can see there are three "complex" types. These are basically just objects like one creates in an object oriented programming language like java. The SUDS Client object has an instance variable called "factory" that allows you to create these complex types so you can use them to invoke methods defined by your web service that take complex arguments.

If we wanted to add a contact using the addContact() method we have to create a contact object first:

contact = client.factory.create('Contact')
print contact

The create function creates a new contact object that knows its own structure. We can view this structure by calling print on this new object and see that it prints the following:

(Contact)=
{
phone = []
age = NONE
name(Name) =
{
last = NONE
first = NONE
}
}

By examining the Contact type object we can see its structure and know what we need to create in order to have a valid Contact to add to the address book. We could then do the following to supply the necessary information for the Contact object and then call our addContact function.

phone = client.factory.create('Phone')
phone.arecode = '916'
phone.number = '5557777'
name = client.factory.create('Name')
name.first = 'John'
name.last = 'Doe'
contact.name = name
contact.phone.append(phone)
client.service.addContact(contact)

After execution a new contact will have been added via the web service. There is also a way to use python dictionaries to specify complex arguments that is detailed in the SUDS documentation.

Steps to remember when using complex types:

#Create a new type object using the factory instance variable of the Client object
my_type = client.factory.create('MyType')
 
#If you don't know the structure of the newly created object then print it to the console
print my_type