Getting Started
===============

NEW: 

   Mark Pilgrims' online book _Dive Into Python_ at
   http://diveintopython.org includes a nice tutorial for SOAPpy in
   Chapter 12. "SOAP Web Services" at
   http://diveintopython.org/soap_web_services.



The easiest way to get up to speed is to run and read the scripts in the
tests directory. Better documentation is coming.

Here are some examples of how to use SOAPpy:


CLIENT EXAMPLES:

   ## CODE
   from SOAPpy import SOAPProxy
   server = SOAPProxy("http://localhost:8080/")
   print server.echo("Hello world")
   ## /CODE

This opens a connection to the server listening on localhost:8080, calls the
method echo with the ordered parameter of "Hello World", and prints the
results.


    ## CODE
    from SOAPpy import SOAPProxy
    server = SOAPProxy("https://localhost:8443/")
    print server.echo("Hello world")
    ## /CODE
    
This opens a secure connection to the SSL server listening on
localhost:8443, calls the method echo with the ordered parameter of
"Hello World" and prints the results. Python must be built with OpenSSL.


    ## CODE
    from SOAPpy import SOAPProxy
    server = SOAPProxy("http://services.xmethods.com/soap",
            	        namespace = "urn:xmethods-delayed-quotes")
    print server.getQuote(symbol = "IBM")
    ## /CODE
    
This calls method getQuote that is in the namespace URI of
urn:xmethods-delayed-quotes on server services.xmethods.com. getQuote is
passed a named parameter, symbol.


    ## CODE
    from SOAPpy import SOAPProxy
    server = SOAPProxy("http://services.xmethods.com/soap")
    
    print server._ns("urn:xmethods-delayed-quotes").getQuote(symbol = "IBM")
    ## /CODE
    
This does the same thing as the previous example, however namespace is
specified inline on a per call basis rather than at the server level.


    ## CODE
    from SOAPpy import SOAPProxy
    server = SOAPProxy("http://services.xmethods.com/soap",
    			soapaction = "http://somesite.com/myaction")
    
    print server._ns("urn:xmethods-delayed-quotes").getQuote(symbol = "IBM")
    ## /CODE
    
This is the same quote call with a soapaction specified.


    ## CODE
    from SOAPpy import SOAPProxy
    server = SOAPProxy("http://services.xmethods.com:80/soap")
    
    ns = "urn:xmethods-delayed-quotes")
    sa = "http://somesite.com/myaction"
    my_call = server._ns(ns)._sa(sa)
    my_call.getQuote(symbol = "IBM")
    my_call.getQuote(symbol = "IBM")
    my_call.getQuote(symbol = "IBM")
    ## /CODE
    
The same example, this time with both the soapaction and the namespace
specified inline and saved in a local variable for getQuote to be called
against.

** What SOAPpy does with the results of a call could seem surprising. If
there is only one element in the structType that has the return value and
unwrap_results is turned on (the default) it will bubble up the single
attribute, otherwise it will return you a structType object with all of the
attributes.



SERVER EXAMPLES:

    ## CODE
    from SOAPpy import SOAPServer
    def echo(s):
        return s + s # repeats a string twice
    
    server = SOAPServer(("localhost", 8080))
    server.registerFunction(echo)
    server.serve_forever()
    ## /CODE
    
This exposes the function echo (that takes an unnamed arguement) on a server
running on localhost:8080.


    ## CODE
    from SOAPpy import SOAPServer
    def echo(s):
        return s + s # repeats a string twice
    
    server = SOAPServer()
    server.registerFunction(echo, "echo-space")
    server.serve_forever()
    ## /CODE
    
The same as above, but this time the method is available in the namespace
"echo-space".


    ## CODE
    from SOAPpy import SOAPServer
    
    class echoBuilder:
        def echo(self, val):
            return val + val
    
    server = SOAPServer()
    e = echoBuilder()
    server.registerObject(e)
    server.serve_forever()
    ## /CODE
    
This registers the whole instance of the object echoBuilder, e.  Every
method of the instance is exposed on the server.


    ## CODE
    from SOAPpy import SOAPServer
    
    def echo(**kw):
        return kw['first'] + kw['second'] + kw['third']
    
    server = SOAPServer()
    server.registerKWFunction(echo)
    server.serve_forever()
    ## /CODE
    
This time the method echo is exposed and it expects named arguments. The
main thing to notice here is the use of the method registerKWFunction over
registerFunction.

    
    ## CODE
    from SOAPpy import SOAPServer
    
    from M2Crypto import SSL
    
    def echo(s):
        return s+s # repeats a string twice
    
    ssl_context = SSL.Context()
    ssl_context.load_cert('server.pem')
    
    server = SOAPServer(("localhost",8443), ssl_context = ssl_context)
    server.registerFunction(echo)
    server.serve_forever()
    ## /CODE
    
This exposes the function echo (taking an unnamed arguement) on a server
accepting SSL connections at localhost:8443. Ng Pheng Siong's M2Crypto
package (available at <http://www.pobox.org.sg/home/ngps/m2/>) must be
installed. Also see tests/silabserver.py.

$Id: GettingStarted.txt,v 1.4 2005/02/21 20:09:29 warnes Exp $