===========================
Scio: client code generator
===========================

Generating client modules from WSDL files
-----------------------------------------

Use the command-line script `scio_generate_client` to generate client
code from a WSDL file::

  $ scio_generate_client path/to/service.wsdl > service_client.py

Generating client code from a dynamic client
--------------------------------------------

It's possible to directly generate a static client class from a dynamic
client class (in fact, this is how all of Scio's code generation works
internally).

 >>> import urllib2
 >>> from scio import client, gen
 >>> code = gen.gen(client.Client(
 ...     urllib2.urlopen('http://lyricwiki.org/server.php?wsdl')))
 >>> code[:100]
 u'#\n# WARNING: this module is autogenerated. Do not edit this file!\n#\nfrom scio import client, static\n'

To use the generated client code directly, exec it into a namespace.

 >>> ns = {}
 >>> exec code in ns
 >>> ns['Client']
 <class 'Client'>
 >>> lyrics = ns['Client']()
 >>> artist, albums = lyrics.service.getArtist('Wilco')
 >>> artist
 u'Wilco'

There's little to be gained by executing the generated code directly,
though. In practice, it is more useful to output the generated code
into a module and import and use that module as normal.

 >>> with open('lyrics.py', 'w') as fh:
 ...    fh.write(code)
 ...
 >>> import lyrics
 >>> lyrics.Client
 <class 'lyrics.Client'>

Subclassing static client classes
---------------------------------

Generated client classes are normal Python class and can be subclassed
and tweaked in all of the normal ways. See :doc:`proxy_example` for a
Scio-specific example of subclassing: the same methods used there will
work with a generated client.

API Reference
-------------

.. autoclass :: scio.static.Client
   :members:
   :show-inheritance:
   :inherited-members:

   .. attribute :: service

      Service container. Each service method defined in the
      WSDL file from which this client was generated will be
      represented as a callable attribute in this container.

   .. attribute :: type

      Type container. Each type defined in the WSDL file from
      which this client was generated will be represented as
      an attribute in this container.

.. autoclass :: scio.static.TypeRegistry
   :members:

.. autofunction :: scio.gen.gen


Example
-------

Here is a code module generated from the lyricswiki WSDL file.

.. literalinclude :: ../lyrics.py
   :language: python
   :linenos: