Getting started, part 2
=======================

In this tutorial we're going to introduce WSDL and send a couple of requests
using a SOAP client. It is based on the
:doc:`previous one <getting_started_part_1>`, so you'd better walk through it,
if you hadn't before.


Introducing WSDL
----------------

Ok, if you are intereseted in SOAP you might have already heard about WSDL and
what it is. If you hadn't then you should know that WSDL is the most wonderful
thing about SOAP. WSDL is a language which may be used to provide a formal
specification of a SOAP web service. This specification can be then used to
generate clients which can easily interact with this service taking away all
the burden of making and sending requests from your shoulders.

Having our pyws server running on ``localhost:8000`` and bound to ``/api`` we
can get it's WSDL description at http://localhost:8000/api/wsdl. You may
want to cast a glance on it, but it's not necessary.

Now, let's create a client and send a few requests. We will use
`suds <https://fedorahosted.org/suds/>`_, it is written in Python and is quite
pretty to use. Open python console and let's write some code there::

    >>> import suds
    >>> client = suds.client.Client('http://localhost:8000/api/wsdl', cache=None)
    >>> client.service.add_simple('hello ', 'world')
    hello world

That's it! Isn't it awesome? No curl, HTTP, POST and so on, we just call a
method and it just works!


Complex types
-------------

Now it's time to play with some comlex types: lists and dicts.

First, we need to add a couple of functions to the server, again edit
``server.py``, add this::

    @register(return_type=[int], args=([int], ))
    def double_list(a):
        return map(lambda x: x * 2, a)

    ABDict = {0: 'ABDict', 'a': int, 'b': int}

    @register(return_type=ABDict, args=(ABDict, ))
    def double_dict(a):
        return dict((k, v * 2) for k, v in a.iteritems())

The code seems to be quite self-explanatory, the only thing is that
``0: 'ABDict'`` gives the dict a name, it's required as pyws can't just invent
it. Now, restart the server and go back to python console::

    >>> import suds
    >>> client = suds.client.Client('http://localhost:8000/api/wsdl', cache=None)
    >>> lst = client.factory.create('ns0:IntegerList')
    >>> lst.item = range(3)
    >>> client.service.double_list(lst)
    (IntegerList){
       item[] =
          0,
          2,
          4,
     }

    >>> dct = client.factory.create('ns0:ABDict')
    >>> dct.a = 1
    >>> dct.b = 2
    >>> client.service.double_dict(dct)
    (ABDict){
       a = 2
       b = 4
     }

Pretty simple, huh?

Now that you've done with this introduction, you may want to go
:doc:`deeper <working_with_pyws>`.