Amara Quick reference

Amara Bindery quick reference

Parsing

import amara
doc = amara.parse("<spam/>")  #string
doc = amara.parse(open("spam.xml", "r"))  #stream (file-like object)
doc = amara.parse("spam.xml") #OS file path
doc = amara.parse("http://example.com/spam.xml") #URL

First sample document

The next two sections are based on this sample document:

<a x="1"><b>i</b><c>j<d/>k</c><b>l</b></a>

Basic XML data access

doc.a                 #object representing a element (instance of a)
doc[u'a']            #object representing a element (instance of a)
doc.a.b               #first instance of b
doc.a.x               #u"1"
doc.a[u'x']           #u"1"
doc.a.localName       #u'a'
doc.a.nodeName        #u'a', may not match localName if doc uses namespaces
doc.a.xml_children    #list with two b instances and one c instance
doc.a.b[0]            #first instance of b
doc.a.b[1]            #second instance of b
doc.a[u'b'][1]            #second instance of b
iter(doc.a.b)         #iterator over both instances of b
unicode(doc.a.b)      #u"i"
unicode(doc.a.b[1])   #u"l"
unicode(doc.a)        #u"ijkl"
doc.a.xml_child_text  #u"" (only immediate text children, concatenated)
doc.a.xml_attributes  #{"x": (None, u"1")}, None => no namespace
doc.a.c.xml_child_elements    #{"d": <d instance>}
doc.xml()             #entire document serialized as XML
doc.a.c.xml()         #c element subtree serialized as XML

XPath

doc.xml_xpath(u"//b") #list of 2 b instances (XPath node set = Py list)
doc.xml_xpath(u"count(//b)")  #2.0 (XPath number = Py float)
doc.xml_xpath(u"/a/@x")       #u'1' (XPath string = Py unicode)
doc.xml_xpath(u"/a/@x = '1'") #True (XPath boolean = Py bool)
doc.a.xml_xpath(u"b") #list of 2 b instances

Basic document update

doc.a.append(u'New Content')  #Add a new text node to a
#Add a new text node to a immediately after its first b element child
doc.a.insert_after(doc.a.b, u'New Content')
#Add a new text node to a immediately before its first b element child
doc.a.insert_before(doc.a.b, u'New Content')
#Create a new free-standing element named 'new'
e = doc.a.xml_create_element(u'new')
#Use the append and insert methods to place the element in the tree
doc.a.append(e)
doc.a.insert_after(doc.a.b, e)
doc.a.insert_before(doc.a.b, e)
#create a tree of objects from an XML fragment then append them to a
doc.a.xml_append_fragment('<c x="1">p</c><d y="2">q</d>')
doc.a.xml_remove_child(e)  #Remove the given child object from a
doc.a.xml_remove_child_at(0)  #Remove the first child object from a
doc.a.xml_clear()  #Remove all children from a

New document creation

#Create a document with a single top-level element named root
doc = amara.create_document(u"root")

Reserialize to XML

xmlstr = doc.xml()  #Reserialize the document to a string
xmlstr = doc.xml(indent=u"yes")  #Pretty-print the document to a string

Namespaces

Sample document:

<n:a xmlns:n="urn:x-bogus1" n:x="1"><b xmlns="urn:x-bogus2">c</b></n:a>

Code:

NS1 = u'urn:x-bogus1'
NS2 = u'urn:x-bogus2'
doc.a                 #object representing a element (instance of a)
doc.a.x               #u"1"
doc[NS1, u'a'].x                      #u"1"
doc[NS1, u'a'][NS1, u'x']             #u"1"
doc.a.localName, doc.a.nodeName       #u'a', u'n:a'
doc.a.prefix, doc.a.namespaceURI      #u'n', u'urn:x-bogus1'
doc.a.xml_attributes  #{u'x': (u'n:x', u'urn:x-bogus1')}
doc.a.b.localName, doc.a.b.nodeName   #u'b', u'b'
doc.a.b.prefix, doc.a.b.namespaceURI  #None, u'urn:x-bogus2'
doc[NS1, u'a'][NS2, u'b']             #u"c"