High-Level Introduction to Spyne¶

Concepts¶

The following is a quick introduction to the Spyne way of naming things:

• Protocols:

  Protocols define the rules for transmission of structured data. They are subclasses of spyne.protocol._base.ProtocolBase class. In an MVC world, you would call them “Views”.

  For example, Spyne implements a subset of the Soap 1.1 protocol.

• Transports:

  Transports, also protocols themselves, encapsulate protocol data in their free-form data sections. They are subclasses of either spyne.client._base.ClientBase or spyne.server._base.ServerBase classes.

  For example, Http is used as a transport for Soap, by tucking a Soap message in the arbitrary byte-stream part of a Http POST request. The same Http is exposed as a protocol via the spyne.protocol.http.HttpRpc class to decode Rest-like request parameters. One could use Soap as a transport by tucking a protocol message in its base64-encoded ByteArray container.

  Transports appear under two packages in Spyne source code: spyne.client and spyne.server.

• Models:

  Models are used to define schemas. They are mere magic cookies that contain very little amount of serialization logic. They are subclasses of spyne.model._base.ModelBase.

  Types like Unicode, Integer or ByteArray are all models. They reside in the spyne.model package.

• Interface Documents:

  Interface documents provide a machine-readable description of the expected input and output of the exposed method calls. Thus, they have pretty much the same purpose as a method signature in a programming language. They are subclasses of spyne.interface.base.InterfaceDocumentBase.

  spyne.interface package is where you can find them.

• Serializers:

  Serializers are currently not distinguished in Spyne code. They are the protocol-specific representations of a serialized Python object.

  They can be anything between an lxml.etree.Element instance to a gzipped byte stream. Apis around pickle, simplejson, YaML and the like that serialize dynamic hieararchies of “dict”s also fall in this category.

How your code is wrapped¶

While the information in the previous section gave you an idea about how Spyne code is organized, this section is supposed to give you an idea about how you should organize your code using the tools provided by Spyne.

Before proceeding further, having good idea about the following four terms used throughout Spyne would be very useful:

• User Methods or User Code:

  User methods are the code that you wrote and decided to use Spyne to expose to the outside world.

• Decorators:

  The @rpc and @srpc decorators from spyne.decorator module are used to flag methods that will be exposed to the outside world by marking their input and output types, as well as other properties.

• Service Definition:

  The spyne.service.ServiceBase is an abstract base class for service definitions, which are the smallest exposable unit in Spyne. You can use one service class per method definition or you can use, say, a service class for read-only or read/write services or you can cram everything into one service class, it’s up to you.

  Service definition classes are suitable for grouping services that have common properties like logging, transaction management and security policy. It’s often a good idea to use your own ServiceBase subclass where such common operations are added via events instead of using the vanilla ServiceBase class offered by Spyne.

• Application:

  The spyne.application.Application class is what ties services and protocols together, ready to be wrapped by a transport.

  It also lets you define events and hooks like you can with the ServiceBase class, so you can do more general, application-wide customizations like exception management.

  Note

  You may know that Spyne is a generalized version of a Soap library. So inevitably, some artifacts of the Soap world creep in from here and there.

  One of those artifacts is the namespace feature of Xml. There are varying opinions about the usefulness of Xml namespaces, but as we think it’s generally “A Nice Thing”, we chose to keep it around.

  When instantiating the spyne.application.Application class, you should also give it a targetNamespace (the tns argument to its constructor) string and an optional application name (the name argument to the Application constructor), which are used to generally distinguish your application from other applications in the universe.

  While it’s conventionally the URL and the name of the class of your application, you can put tns="Hogwarts", name="Harry" there and just be done with it.

  Every object in the Spyne world has a name and belongs to a namespace. Public functions (and the implicit spyne.model.complex.ComplexModel subclasses that are created for the input and output types of the functions you defined) are forced to be in the tns of the Application and have whatever you give them as public_name in the spyne.decorator.srpc() decorator. Spyne-defined types generally belong to a pre-defined namespace by default. User-defined objects have the module name as namespace string and class name as name string by default.

What’s next?¶

Now that you have a general idea about how Spyne is supposed to work, let’s get coding. You can start by Hello World tutorial right now.