XMLObj and XMLObjApp

XMLObject may be installed from source or, for Windows users, with a binary installer.

XMLObjApp may be installed from source or, for Windows users, with a binary installer.

XMLObj provides two special types for dealing with unique identifiers – UniqueID to hold them and ReferenceID to cross-reference them.

Suppose you wanted to represent a set of objects that don't fit cleanly into XML's single-parent/multiple-children hierarchy:

Figure 3.4. Family Tree

You could do it with the following XML:

<Family>
    <Member Name="Abe" DOB="3/31/42" />
    <Member Name="Betty" DOB="2/4/49" />
    <Member Name="Cathy" DOB="12/2/78" />
    <Member Name="Dan" Father="Abe" Mother="Betty" DOB="6/12/73" />
    <Member Name="Edith" Father="Abe" Mother="Betty" DOB="8/30/80" />
    <Member Name="Frank" DOB="11/4/70" />
    <Member Name="George" Father="Dan" Mother="Cathy" DOB="5/13/94" />
    <Member Name="Harold" Father="Dan" Mother="Cathy" DOB="7/1/97" />
    <Member Name="Irwin" Father="Frank" Mother="Edith" DOB="10/31/01" />
    <Member Name="Janet" Father="Frank" Mother="Edith" DOB="1/17/03" />
</Family>

By configuring the Name attribute as a UniqueID type and the Father and Mother attributes as ReferenceID type, we can make it easy to cross-reference between them.

Figure 3.5. Family Tree Configuration

>>> import XMLObject, tree
>>> Tree = XMLObject.Parse("tree.xml", "Family", tree.Family)
>>> Tree.Member["Janet"].DOB
'1/17/03'
>>> Tree.Member["Janet"].Mother().DOB
'8/30/80'
>>> Tree.Member["Janet"].Mother().Father().DOB
'3/31/42'

More information on the use of ReferenceID types may be found in ReferenceID.

Attribute values may be constrained somewhat by selecting the appropriate type and/or by setting an attribute's default to (required). However, this is not always sufficient. Sometimes you need to:

Although XMLObjApp does not let you enter constraints such as these directly, you can constrain XML attributes by manually editing the parser source.

Each class needs a valid children definition (VCD) string to define which tags are allowed as children (a blank VCD indicates that the class is not allowed to have any children). This string looks a lot like a regular expression. It allows the use of parenthesis, braces, modifiers (*, +, and ?), and the | operator just like regular expressions do.

Instead of giving a huge lesson on regular expressions, I'm just going to describe a few sets of allowed children and show you the VCD you could enter to specify such a set. I'm confident that you'll be able to extrapolate from there.

Once you've entered your VCD, hit Tab or click on any other control. As soon as the VCD control loses focus, XMLObjApp will recalculate the list of possible children and add or remove fields to allow you to configure how these children should be processed.

To complete our configuration of a class, we must specify how the children should be attached to the class. There are four fundamental things we need to define for each child:

To illustrate these decisions, let's look at some really contrived XML that describes an engineer:

<Engineer Name="Duane">
    <Boss Name="Cecil"> (lots of "boss" data) </Boss>
    <Spouse>Elizabeth</Spouse>
    <Child>Herman</Child>
    <Child>Olaf</Child>
    <Project ProjCode="210"> (lots of data on project #210) </Project>
    <Project ProjCode="229"> (lots of data on project #229) </Project>
    <Project ProjCode="766"> (lots of data on project #766) </Project>
</Engineer>

To parse data such as this, I would configure my Engineer class in the following way:

Figure 3.6. Engineer class Configuration

As you can see from the VCD string, we expect a single boss, the possibility of a single spouse (must not be living in Utah!), any number of children (including none), and any number of projects.

The boss will be an instance of class Manager and stored in the Engineer attribute Boss. The boss instance is liable to contain several pieces of information, so we won't reduce it down any.

There can only be one spouse, just as there is only one boss, so we will save this information as attribute Spouse. However, there's only one thing of interest in the Spouse attribute – the Spouse's name.

Since the spouse has only one piece of real data, it's more convenient to access this data as Engineer.Spouse instead of as Engineer.Spouse.Name. To do this reduction, I've checked the appropriate Reduce checkbox and entered the Name member into the appropriate field.

The engineer may have any number of children. Each <Child> element is very similar in structure to the <Spouse> element. I've taken advantage of this and used the same class for both.

I've configured the Child element capture in much the same way as the <Spouse> element. Each child is reduced to the value of the Name member. The difference is that there can be multiple <Child> elements, but only one <Spouse> element. To handle these multiple elements, I've configured Child to store the data values in a list called Children.

Parsing the Engineer XML above with the model shown, will give Engineer.Children a value of ['Herman', 'Olaf'].

Like the Boss member, the Projects member will not be reduced. Each project will undoubtably contain multiple pieces of useful data we will want to maintain. However, there can be multiple projects, just as there could be multiple children. We could store these in a list, like we did with the children, but because each <Project> has a unique ProjCode, it will probably be a better choice for us to put these projects in a dictionary (with a key of ProjCode).

By putting the projects in a dictionary, we can get a list of project codes with Engineer.Projects.keys(), a list of the projects with Engineer.Projects.values(), or even access a specific project with Engineer.Projects["229"] (for example). This lets us access a specific project without having to search the list for the appropriate list index.

As mentioned previously, elements can have child text. Configuring how the text should be processed and stored begins with entering the #PCDATA pseudo-tag into the VCD. #PCDATA configuration is as shown:

Figure 3.7. #PCDATA Pseudo-tag Configuration

Text may be processed in a variety of ways:

Regardless of how the text is processed, it is saved as the entered attribute name.

As mentioned previously, there are times when you just don't want to parse all the XML in a document. One common situation for this is when one program wants to communicate an HTML-formatted message to another program. Using an <XML> pseudo-tag will accomplish just that.

<Error>
    File could <b>not</b> be opened.
</Error>

Could be parsed with:

Figure 3.8. Parsing HTML Within XML

To give Error.XML a value of:

'File could <b>not</b> be opened.'

Alternately, you can choose to extract the text Exactly and not strip off any extraneous white-space.

Most of the items on the File Menu require very little explaination. File->Open (Ctrl-O), File->Save (Ctrl-S), File->Save As..., and File->Close all open, save, and close the current XML parser description as a Python module.

By default, XMLObjApp performs a sanity test before saving the parser file. If the test fails, XMLObjApp will alert you and ask if the file should be saved anyhow. Saving a parser with errors in it is risky as it may not be possible to load the parser later to fix the errors.

You may disable this pre-save test in the preferences.

File->Sanity Test (Ctrl-T) runs a quick check on the parser you have created to make sure it makes sense. It checks for obvious problems, such as putting illegal characters in attribute names and defining a class multiple times, to more subtle mistakes, such as neglecting to define a class you use.

If successful, the Sanity Test will pop up a simple dialog to notify you of success:

Figure 3.9. Sanity Test Success

On a failure, Sanity Test will open a list of errors and warnings:

Figure 3.10. Sanity Test Failure

The failure messages are pretty self-explanitory, so I won't waste time detailing each one. Error messages are marked with a symbol and warnings with a symbol. Click on any message link to jump to the appropriate class page and field that caused the problem. Errors certainly need to be fixed. Warnings may need to be fixed.

One of XMLObjApp's more convenient features is the File->Import XML... menu item. This function imports an XML file and takes some guesses about what sorts of classes, attributes, and children should go into your parser. The configuration will almost certainly not be correct, but it should save you tons of time in creating your parser. Simply import your XML file and then tweak all the settings until they match your file's structure.

File->Preferences... allows you to set all of the following:

File->Quit closes the XMLObjApp application.

Although XMLObject automatically generates a Python parser for you, you may wish to edit the parser to enhance its functionality. One time that you'll certainly want to do this is when you derive the parser classes from other classes.

Consider the painfully simple example:

Figure 4.1. Parent class Configuration

This will create the following parser:

# vvv  Generated code, do not modify  vvv
import XMLObject
# ^^^  Generated code, do not modify  ^^^

# vvv  Generated code, do not modify  vvv
class Root(Parent):
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, Attr, XMLStack=XMLObject.Stack()):
        self.Attr = str(Attr)
# ^^^  Generated code, do not modify  ^^^

This code won't load, of course, since we haven't yet defined the Parent class just yet. We can do this by editing the code and either entering the class into the module or by importing it with a:

from ParentModule import Parent

For now, we'll just add code directly into the parser:

# vvv  Generated code, do not modify  vvv
import XMLObject
# ^^^  Generated code, do not modify  ^^^

class Parent:
    def __init__(self):
        self.Var = 5

# vvv  Generated code, do not modify  vvv
class Root(Parent):
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, Attr, XMLStack=XMLObject.Stack()):
        self.Attr = str(Attr)
# ^^^  Generated code, do not modify  ^^^
        Parent.__init__(self)

Note how I've added the Parent class and the Parent class construction without modifying any code within the blocks marked "do not modify". This is important.

Modifying the code within these blocks can still create valid code, but you may no longer be able to reload the code with XMLObjApp. Worse, the application may load the code, but then save changes to these blocks without any warnings. Just don't do it.

You can also add member functions to classes, as long as the code you add is not within the "do not modify" blocks.

XMLObject processes the XML file from top to bottom, and performs the following actions on each element in order:

_end_init accepts no parameters. It gives you a chance to do any initialization that cannot happen until after the element's children have been processed.

Stack is a class used to track an element's relationship to the rest of the document. Stack is passed to element constructors during XML parsing.

It defines the following members:

UniqueIDs serve two purposes; they allow elements to cross-reference each other, and they provide a mechanism to find an element by ID – regardless of where the element is located in the document hierarchy.

<Family>
    <Member Name="Abe" DOB="3/31/42" />
    <Member Name="Betty" DOB="2/4/49" />
    <Member Name="Cathy" DOB="12/2/78" />
    <Member Name="Dan" Father="Abe" Mother="Betty" DOB="6/12/73" />
    <Member Name="Edith" Father="Abe" Mother="Betty" DOB="8/30/80" />
    <Member Name="Frank" DOB="11/4/70" />
    <Member Name="George" Father="Dan" Mother="Cathy" DOB="5/13/94" />
    <Member Name="Harold" Father="Dan" Mother="Cathy" DOB="7/1/97" />
    <Member Name="Irwin" Father="Frank" Mother="Edith" DOB="10/31/01" />
    <Member Name="Janet" Father="Frank" Mother="Edith" DOB="1/17/03" />
</Family>

import XMLObject

class Member:
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, Name, DOB=None, Father=None, Mother=None, XMLStack=None):
        self.DOB = str(DOB)
        self.Name = XMLStack.UniqueID("Member", Name, self, XMLStack)
        self.Father = XMLStack.ReferenceID(Father, XMLStack)
        self.Mother = XMLStack.ReferenceID(Mother, XMLStack)

class Family:
    ChildSpec = XMLObject.ChildClass({"Member": XMLObject.StdChild(Member,
        "Member", "Dict", Key="Name")}, "(<Member>)*")
    def __init__(self, XMLStack):
        self.Member = {}

>>> import XMLObject, tree
>>> Tree = XMLObject.Parse("tree.xml", "Family", tree.Family)
>>> Tree.Member["Janet"].DOB
'1/17/03'
>>> Tree.Member["Janet"].Mother().DOB
'8/30/80'
>>> Tree.Member["Janet"].Mother().Father().DOB
'3/31/42'

<Elements>
    <Fruit Name="apple" Color="red" Size="medium" />
    <Fruit Name="orange" Color="orange" Size="medium" />
    <Fruit Name="grape" Color="purple" Size="small" />
    <Color Name="red" Fruit="apple" />
    <Color Name="orange" Fruit="orange" />
    <Color Name="purple" Fruit="grape" />
</Elements>

import XMLObject

class Fruit:
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, Name, Color=None, Size=None, XMLStack=None):
        self.Name = XMLStack.UniqueID("Fruit", Name, self, XMLStack)
        self.Color = XMLStack.ReferenceID(Color, XMLStack)
        self.Size = Size

class Color:
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, Name, Fruit=None, XMLStack=None):
        self.Name = XMLStack.UniqueID("Color", Name, self, XMLStack)
        self.Fruit = XMLStack.ReferenceID(Fruit, XMLStack)

class Elements:
    ChildSpec = XMLObject.ChildClass({"Fruit": XMLObject.StdChild(Fruit,
        "Fruit", "List"), "Color": XMLObject.StdChild(Color, "Color", "List")},
        "((<Fruit>) | (<Color>))*")
    def __init__(self, XMLStack):
        self.Fruit = []
        self.Color = []

>>> import XMLObject, elements
>>> Elements = XMLObject.Parse("elements.xml", "Elements", elements.Elements)
>>> str(Elements.Color[0].Name)
'red'
>>> str(Elements.Color[1].Name)
'orange'
>>> str(Elements.Color[1].Fruit)
'orange'
>>> Elements.Color[1].Fruit.__class__
<class XMLObject.ReferenceID at 0x009832D0>
>>> Elements.Color[1].Fruit("Fruit").__class__
<class elements.Fruit at 0x009830F0>
>>> Elements.Color[1].Fruit("Fruit").Size
'medium'

<Customers>
    <Customer Name="Joe Blow">
        <Order ID="Z98212" Status="shipped" />
    </Customer>
    <Customer Name="Gre7g Luterman">
        <Order ID="H67921" Status="shipped" />
        <Order ID="M26611" Status="lost" />
    </Customer>
</Customers>

import XMLObject

class Order:
    ChildSpec = XMLObject.ChildClass({}, "")
    def __init__(self, ID, Status=None, XMLStack=None):
        self._root = XMLStack[-1]
        self._parent = XMLStack[0]
        self.Status = Status
        self.ID = XMLStack.UniqueID("Order", ID, self, XMLStack)

class Customer:
    ChildSpec = XMLObject.ChildClass({"Order": XMLObject.StdChild(Order,
        "Order", "Dict", Key="ID")}, "(<Order>)*")
    def __init__(self, Name, XMLStack=None):
        self.Name = Name
        self.Order = {}

class Customers:
    ChildSpec = XMLObject.ChildClass({"Customer": XMLObject.StdChild(Customer,
        "Customer", "Dict", Key="Name")}, "(<Customer>)*")
    def __init__(self, XMLStack=None):
        self.Customer = {}

>>> import XMLObject, customers
>>> Customers = XMLObject.Parse("customers.xml", "Customers",
... customers.Customers)
>>> Matches = filter(lambda Customer: Customer.Order.has_key("M26611"),
... Customers.Customer.values())
>>> len(Matches)
1
>>> Matches[0].Name
'Gre7g Luterman'
>>> Matches[0].Order["M26611"].Status
'lost'

>>> import XMLObject, customers
>>> Stack = XMLObject.Stack()
>>> Customers = XMLObject.Parse("customers.xml", "Customers",
... customers.Customers, Stack)
>>> Stack("M26611").Status
'lost'
>>> Stack("M26611")._parent.Name
'Gre7g Luterman'