Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Lightweight declarative YAML and XML data binding for Python.

Project Description


Lightweight declarative YAML and XML data binding for Python

Guts is written by Sebastian Heimann <>. It is
released under the MIT license. See the file LICENSE for more details.


* PyYAML: Download it from and follow the given
installation instructions or install it through your system's package
manager (e.g. the `python-yaml` package on Debian based Linuxes).


A file `` might look like:

from guts import *

class Song(Object):
name = String.T()
album = String.T(default='')
artist = String.T(default='')
year = Int.T(optional=True)

class Playlist(Object):
xmltagname = 'playlist'
name = String.T(default='Untitled Playlist')
comment = String.T(optional=True)
song_list = List.T(Song.T())

These classes come with automatic `__init__`:

>>> from playlist import *
>>> song1 = Song(name='Metropolis', artist='Kraftwerk')
>>> song2 = Song(name='I Robot', artist='The Alan Parsons Project', album='I Robot')
>>> playlist = Playlist(song_list=[song1,song2])

They serialize to YAML:

>>> print song1.dump()
--- !playlist.Song
name: Metropolis
artist: Kraftwerk

They also serialize to XML:

>>> print playlist.dump_xml()
<name>Untitled Playlist</name>
<name>I Robot</name>
<album>I Robot</album>
<artist>The Alan Parsons Project</artist>

Objects can validate themselves:

>>> song1.validate()
>>> song2.year = 1977
>>> song2.validate()
>>> song2.year = 'abc'
>>> song2.validate()
Traceback (most recent call last):
guts.ValidationError: year: "abc" is not of type int

Objects can regularize themselves:

>>> song2.year = '1977'
>>> song2.regularize()
>>> song2.year
>>> type(song2.year)
<type 'int'>

They also deserialize from YAML and XML:

>>> playlist2 = load_string(playlist.dump())
>>> playlist3 = load_xml_string(playlist.dump_xml())

Incremental loading of large YAML or XML files is supported with the
`guts.iload_all()` and `guts.iload_all_xml()` functions, which are buildt to
return generators yielding Guts objects.

This module comes with a rudimentary code generator `xmlschema-to-guts` to turn
(some) XML Schema definitions (XSD) into Python modules containing Guts class

Here is an example using the first example in the W3C XML Schema Primer. The
Schema shall be defined in `po.xsd`:

<xsd:schema xmlns:xsd="">

<xsd:documentation xml:lang="en">
Purchase order schema for
Copyright 2000 All rights reserved.

<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>

<xsd:element name="comment" type="xsd:string"/>

<xsd:complexType name="PurchaseOrderType">
<xsd:element name="shipTo" type="USAddress"/>
<xsd:element name="billTo" type="USAddress"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="items" type="Items"/>
<xsd:attribute name="orderDate" type="xsd:date"/>

<xsd:complexType name="USAddress">
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="street" type="xsd:string"/>
<xsd:element name="city" type="xsd:string"/>
<xsd:element name="state" type="xsd:string"/>
<xsd:element name="zip" type="xsd:decimal"/>
<xsd:attribute name="country" type="xsd:NMTOKEN"

<xsd:complexType name="Items">
<xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
<xsd:element name="productName" type="xsd:string"/>
<xsd:element name="quantity">
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxExclusive value="100"/>
<xsd:element name="USPrice" type="xsd:decimal"/>
<xsd:element ref="comment" minOccurs="0"/>
<xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
<xsd:attribute name="partNum" type="SKU" use="required"/>

<!-- Stock Keeping Unit, a code for identifying products -->
<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{3}-[A-Z]{2}"/>


A corresponding XML file `po.xml` might look like this:

<?xml version="1.0"?>
<purchaseOrder orderDate="1999-10-20">
<shipTo country="US">
<name>Alice Smith</name>
<street>123 Maple Street</street>
<city>Mill Valley</city>
<billTo country="US">
<name>Robert Smith</name>
<street>8 Oak Avenue</street>
<city>Old Town</city>
<comment>Hurry, my lawn is going wild</comment>
<item partNum="872-AA">
<comment>Confirm this is electric</comment>
<item partNum="926-AA">
<productName>Baby Monitor</productName>

Using the Guts code generator

$ xmlschema-to-guts po.xsd >

will produce a Python module ``:

from guts import *

class SKU(StringPattern):
pattern = '\\d{3}-[A-Z]{2}'

class Comment(String):
xmltagname = 'comment'

class Quantity(Int):

class USAddress(Object):
country = String.T(default='US', optional=True, xmlstyle='attribute')
name = String.T()
street = String.T()
city = String.T()
state = String.T()
zip = Float.T()

class Item(Object):
part_num = SKU.T(xmlstyle='attribute')
product_name = String.T()
quantity = Quantity.T()
us_price = Float.T(xmltagname='USPrice')
comment = Comment.T(optional=True)
ship_date = DateTimestamp.T(optional=True)

class Items(Object):
item_list = List.T(Item.T())

class PurchaseOrderType(Object):
order_date = DateTimestamp.T(optional=True, xmlstyle='attribute')
ship_to = USAddress.T()
bill_to = USAddress.T()
comment = Comment.T(optional=True)
items = Items.T()

class PurchaseOrder(PurchaseOrderType):
xmltagname = 'purchaseOrder'

And we can use it e.g. to parse the example XML file `po.xml` from above:

>>> from po import *
>>> order = load_xml(filename='po.xml')
>>> print order # dumps YAML
--- !po.PurchaseOrder
order_date: '1999-10-20'
ship_to: !po.USAddress
name: Alice Smith
street: 123 Maple Street
city: Mill Valley
state: CA
zip: 90952.0
bill_to: !po.USAddress
name: Robert Smith
street: 8 Oak Avenue
city: Old Town
state: PA
zip: 95819.0
comment: Hurry, my lawn is going wild
items: !po.Items
- !po.Item
part_num: 872-AA
product_name: Lawnmower
quantity: 1
us_price: 148.95
comment: Confirm this is electric
- !po.Item
part_num: 926-AA
product_name: Baby Monitor
quantity: 1
us_price: 39.98
ship_date: '1999-05-21'

Release History

Release History

This version
History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
guts-0.2.tar.gz (19.6 kB) Copy SHA256 Checksum SHA256 Source Oct 30, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting