genx.Writer.addAttribute

This adds the given genx.Attribute object to the currently active element.

A simple example:

>>> import genx
>>> w = genx.Writer()
>>> attr = genx.declareAttribute("href")
>>> fp = file("/tmp/text.xml", "w")
>>> w.startDocFile(fp)
>>> w.startElementLiteral("a")
>>> w.addAttribute(attr, "http://example.com/")
>>> w.endElement()
>>> w.endDocument()
>>>

This produces the following output:

<a href="http://example.com/"></a>

genx.Writer.addAttributeLiteral

This adds an attribute with the given name and value to the currently active element. An optional namespace string can be passed in too. This method is slower than using genx.Writer.addAttribute with a defined genx.Attribute object.

Typical use:

>>> import genx
>>> writer = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> writer.startDocFile(fp)
>>> writer.startElementLiteral("elem")
>>> writer.addAttributeLiteral("attr", "value")
>>> writer.endElement()
>>> writer.endDocument()
>>> 

And the content of test.xml:

<elem attr="value"></elem>

genx.Writer.addNamespace

Adds the given genx.Namespace object to the currently active element, using an optional prefix.

A simple example with an element:

>>> import genx
>>> writer = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> ns = writer.declareNamespace("http://example.com", "foo")
>>> writer.startDocFile(fp)
>>> writer.startElementLiteral("elem")
>>> writer.addNamespace(ns)
>>> writer.endElement()
>>> writer.endDocument()
>>> 

And the output in test.xml:

<elem xmlns:foo="http://example.com"></elem>

genx.Writer.addText

Adds the specified text to the currently active element. The text will be encoded as UTF-8, so ensure that the text has the correct encoding (this can usually be achieved when reading in the string using the decode method, e.g. s = fp.read().decode('ISO-8859-1')).

Basic usage:

>>> import genx
>>> w = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> w.startDocFile(fp)
>>> w.startElementLiteral("elem")
>>> w.addText("some text")
>>> w.endElement()
>>> w.endDocument()
>>> 

The output:

<elem>some text</elem>

genx.Writer.checkText

This is a function for sanity checking strings. It checks to see if the given string is valid UTF-8 and if it contains any invalid XML characters.

The return codes are based on genx's error codes, currently I'm not exposing these codes, so currently the three relevant return codes are:

0

The text is ok.

1

The text is invalid UTF-8.

2

The text is invalid XML.

Simple usage:

>>> import genx
>>> w = genx.Writer()
>>> w.checkText("This is a plain string")
0
>>> w.checkText("This is an invalid unicode string. \xff\x01")
1
>>> w.checkText("This is an invalid XML string\x01")
2
>>> 

genx.Writer.comment

This adds an XML comment (e.g. <!-- my comment -->) in the generated XML.

For example:

>>> import genx
>>> w = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> w.startDocFile(fp)
>>> w.comment("A comment") 
>>> w.startElementLiteral("elem")
>>> w.comment("Another comment")
>>> w.endElement()
>>> w.endDocument()
>>> 

test.xml:

<!--A comment-->
<elem><!--Another comment--></elem>

genx.Writer.PI

Adds an XML Processing Instruction (e.g. <?foo bar?>) to the file.

For example:

>>> import genx
>>> w = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> w.startDocFile(fp)
>>> w.PI("foo", "bar")
>>> w.startElementLiteral("elem")
>>> w.endElement()
>>> w.endDocument()
>>> 

Produces:

<?foo bar?>
<elem></elem>

genx.Writer.declareAttribute

This creates a genx.Attribute object with the given name, and an optional genx.Namespace object. This object can then be used with genx.Writer.addAttribute calls to add attributes to the current document.

A simple example:

>>> import genx
>>> w = genx.Writer()
>>> attr = w.declareAttribute("attr")
>>> ns = w.declareNamespace("http://example.com/ns")
>>> attr2 = w.declareAttribute("attr2", ns)
>>>

genx.Writer.declareElement

Declare a new element, using the optional genx.Namespace object.

A trivial example:

>>> import genx
>>> writer = genx.Writer()
>>> elem = writer.declareElement("element")
>>> ns = writer.declareNamespace("http://example.com/ns")
>>> elem_with_ns = writer.declareElement("anotherelem", ns)
>>>

genx.Writer.declareNamespace

Declare a new genx.Namespace object, using the given namespace URI and an optional prefix. Use a prefix of "" to declare the the default namespace.

A simple example:

>>> import genx
>>> w = genx.Writer()
>>> ns = w.declareNamespace("http://example.com/ns")
>>> ns2 = w.declareNamespace("http://example.com/ns2", "myprefix")
>>>

genx.Writer.endDocument

Finish writing the current document. When this is called all the elements should have been previously closed using genx.Writer.endElement calls. After this is called the genx.Writer instance can be re-used with another file.

An example of re-using a genx.Writer instance:

>>> import genx
>>> w = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> elem = w.declareElement("elem")
>>> w.startDocFile(fp)
>>> w.startElement(elem)
>>> w.endElement() 
>>> w.endDocument()
>>> fp2 = file("/tmp/test2.xml", "w")
>>> w.startDocFile(fp2)
>>> w.startElement(elem)
>>> w.startElement(elem)
>>> w.endElement()
>>> w.endElement()
>>> w.endDocument()
>>> 

The content of test.xml:

<elem></elem>

The content of test2.xml:

<elem><elem></elem></elem>

genx.Writer.endElement

Finish writing the current element. This needs to be called to close each corresponding element created with genx.Writer.startElement or genx.Writer.startElementLiteral calls.

genx.Writer.scrubText

This silently scrubs any invalid characters out of the given string.

A simple example:

>>> import genx
>>> writer = genx.Writer()
>>> writer.scrubText("A string")
'A string'
>>> writer.scrubText("A string |\x01|")
'A string ||'
>>> 

genx.Writer.startDocFile

This starts a new document using the given File object. It should be called only once for each document. If called again on an active document you will get a genx.SequenceError.

genx.Writer.startElement

Starts a new XML element using the given genx.Element object. This is the preferred way to write elements into an XML document, as it is faster to re-use premade genx.Element objects than to use genx.Writer.startElementLiteral calls.

A simple example:

>>> import genx
>>> w = genx.Writer()
>>> elem = w.declareElement("foo")
>>> fp = file("/tmp/test.xml", "w")
>>> w.startDocFile(fp)
>>> w.startElement(elem)
>>> w.endElement()
>>> w.endDocument()
>>>

This writes:

<foo></foo>

genx.Writer.startElementLiteral

Starts a new XML element with the given name and an optional namespace URI string. This is the most straight forward way to create elements, but it isn't the fastest, and can get unwieldy when compared to genx.Writer.startElement.

A variation of the example in genx.Writer.startElement:

>>> import genx
>>> w = genx.Writer()
>>> fp = file("/tmp/test.xml", "w")
>>> w.startDocFile(fp)
>>> w.startElementLiteral("foo")
>>> w.endElement()
>>> w.endDocument()
>>>

This writes:

<foo></foo>

genx.Writer.unsetDefaultNamespace

This clears the default namespace declaration. This is slightly tricky to explain, probably easier to demonstrate.

#!/usr/bin/env python

import genx

w = genx.Writer()
nsdef = w.declareNamespace("http://default", "")
nspref = w.declareNamespace("http://pref", "pref")
e = w.declareElement("e")
edef = w.declareElement("edef", nsdef)
epref = w.declareElement("epref", nspref)

fp = file("/tmp/test.xml", "w")
w.startDocFile(fp)
w.startElement(edef)
w.addNamespace(nspref)
w.startElement(e)
w.endElement()
w.startElement(epref)
w.unsetDefaultNamespace()
w.startElement(e)
w.endElement()
w.endElement()
w.endElement()
w.endDocument()

fp2 = file("/tmp/test2.xml", "w")
w.startDocFile(fp2)
w.startElement(edef)
w.addNamespace(nspref)
w.startElement(e)
w.endElement()
w.startElement(epref)
#w.unsetDefaultNamespace()
w.startElement(e)
w.endElement()
w.endElement()
w.endElement()
w.endDocument()

Using xmllint and diff to compare the outputs:

$ xmllint --format /tmp/test2.xml >test2.xml
$ xmllint --format /tmp/test.xml >test.xml
$ diff -u test.xml test2.xml 
--- test.xml    2004-05-31 23:44:50.000000000 +0100
+++ test2.xml   2004-05-31 23:44:45.000000000 +0100
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <edef xmlns="http://default" xmlns:pref="http://pref">
   <e xmlns=""/>
-  <pref:epref xmlns="">
-    <e/>
+  <pref:epref>
+    <e xmlns=""/>
   </pref:epref>
 </edef>

The lines with the - characters in front of them represent text.xml (with the unsetDefaultNamespace call) and the lines with the + character in front represent test2.xml (without the call). As you can see the unsetDefaultNamespace call forcibly resets the namespace.