Module xml

XML renderer

Imports:
__future__, cStringIO, copy, lxml, nagare.namespaces, peak.rules, types, urllib
Classes:
Renderer(XmlRenderer): The XML Renderer
RendererMetaClass(type): Meta class for the renderer class
TagProp(object): Tag factory with a behavior of an object attribute
XmlRenderer(common.Renderer): The base class of all the renderers that generate a XML dialect
_Tag(ET.ElementBase): A xml tag
Methods:
add_attribute(self, name, value): Default method to add an attribute to a tag
add_attribute(self, name, value):
add_attribute(self, name, value):
add_child(self, o): Default method to add an object to a tag
add_child(self, s): Add a string to a tag
add_child(self, i): Add elements to a tag
add_child(self, n): Add a number to a tag
add_child(self, element): Add a tag to a tag
add_child(self, element): Add a comment element to a tag
add_child(self, element): Add a PI element to a tag
add_child(self, d): Add a dictionary to a tag
Attributes:
CHECK_ATTRIBUTES = False
_MELD_ID = '{%s}id' % _MELD_NS
_MELD_NS = 'http://www.plope.com/software/meld3'
e.findmeld('addr').text = addr
e.findmeld('name').text = name
t1 = x.parse_xmlstring("\n <a>avant<x>kjkjkl</x>#<b b='b'>hello</b>apres</a>\n ")
t2 = x.parse_xmlstring("\n <toto>xxx<titi a='a'>world</titi>yyy</toto>\n ")
x = Renderer()
x = Renderer()
x.namespaces = { 'meld' : 'http://www.plope.com/software/meld3' }

Class xml.Renderer

Back to xml

Bases:
XmlRenderer

The XML Renderer

This renderer generate any tags you give

>>> xml = xml.Renderer()
>>> xml.foo(xml.bar).write_xmlstring()
'<foo><bar/></foo>'
Methods:
__getattr__(self, name): Any attribute access becomes a tag generation

Method xml.Renderer.__getattr__

Back to xml.Renderer

Arguments:
self, name

Any attribute access becomes a tag generation

In:
  • name -- name of the tag to generate
Return:
  • the generated tag

Class xml.RendererMetaClass

Back to xml

Bases:
type

Meta class for the renderer class

Discover the tags that have a special factory and pass them to the class_init() method of the class

Methods:
__new__(self, cls_name, bases, ns): Creation of the class

Method xml.RendererMetaClass.__new__

Back to xml.RendererMetaClass

Arguments:
self, cls_name, bases, ns

Creation of the class

In:
  • cls_name -- name of the class to create
  • bases -- tuple of the base classes of the class to create
  • ns -- namespace of the class to create
Return:
  • the new class

Class xml.TagProp

Back to xml

Bases:
object

Tag factory with a behavior of an object attribute

Each time this attribute is read, a new tag is created

Methods:
__get__(self, renderer, cls): Create a new tag each time this attribute is read
__init__(self, name, authorized_attribs=None, factory=None): Initialization

Method xml.TagProp.__get__

Back to xml.TagProp

Arguments:
self, renderer, cls

Create a new tag each time this attribute is read

In:
  • renderer -- the object that has this attribute
  • cls -- not used
Return:
  • a new tag

Method xml.TagProp.__init__

Back to xml.TagProp

Arguments:
self, name, authorized_attribs=None, factory=None

Initialization

In:
  • name -- name of the tags to create
  • authorized_attribs -- names of the valid attributes
  • factory -- special factory to create the tag

Class xml.XmlRenderer

Back to xml

Bases:
common.Renderer

The base class of all the renderers that generate a XML dialect

Methods:
__init__(self, parent=None): Renderer initialisation
__lshift__(self, current): Add a tag to the last tag pushed by a with statement
_get_default_namespace(self): Return the default_namespace
_makeelement(self, tag, parser): Make a tag, in the default namespace set
_set_default_namespace(self, namespace): Change the default namespace
class_init(cls, special_tags): Class initialisation
comment(self, text=''): Create a comment element
enter(self, current): A new tag is pushed by a with statement
exit(self): End of a with statement
makeelement(self, tag): Make a tag, in the default namespace set
parse_xml(self, source, fragment=False, no_leading_text=False, **kw): Parse a XML file
parse_xmlstring(self, text, fragment=False, no_leading_text=False, **kw): Parse a XML string
processing_instruction(self, target, text=None, **kw): Create a processing instruction element
root(self): Return the first tag(s) sent to the renderer
Attributes:
__metaclass__ = RendererMetaClass
content_type = 'text/xml'
default_namespace = property(_get_default_namespace, _set_default_namespace)
doctype = ''

Method xml.XmlRenderer.__init__

Back to xml.XmlRenderer

Arguments:
self, parent=None

Renderer initialisation

In:
  • parent -- parent renderer

Method xml.XmlRenderer.__lshift__

Back to xml.XmlRenderer

Arguments:
self, current

Add a tag to the last tag pushed by a with statement

In:
  • current -- tag to add
Return:
  • self, the renderer

Method xml.XmlRenderer._get_default_namespace

Back to xml.XmlRenderer

Arguments:
self

Return the default_namespace

Return:
  • the default namespace or None if no default namespace was set

Method xml.XmlRenderer._makeelement

Back to xml.XmlRenderer

Arguments:
self, tag, parser

Make a tag, in the default namespace set

In:
  • tag -- name of the tag to create
  • parser -- parser used to create the tag
Return:
  • the new tag

Method xml.XmlRenderer._set_default_namespace

Back to xml.XmlRenderer

Arguments:
self, namespace

Change the default namespace

The namespace must be a key of the self.namespaces dictionary or be None

For example:

x.namespaces = { 'xsl' : 'http://www.w3.org/1999/XSL/Transform' }
x.set_default_namespace('xsl')

Method xml.XmlRenderer.class_init

Back to xml.XmlRenderer

Arguments:
cls, special_tags

Class initialisation

In:
-- special_tags -- tags that have a special factory
Decorators:
@classmethod

Method xml.XmlRenderer.comment

Back to xml.XmlRenderer

Arguments:
self, text=''

Create a comment element

In:
  • text -- text of the comment
Return:
  • the new comment element

Method xml.XmlRenderer.enter

Back to xml.XmlRenderer

Arguments:
self, current

A new tag is pushed by a with statement

In:
  • current -- the tag
Return:
  • current

Method xml.XmlRenderer.makeelement

Back to xml.XmlRenderer

Arguments:
self, tag

Make a tag, in the default namespace set

In:
  • tag -- name of the tag to create
Return:
  • the new tag

Method xml.XmlRenderer.parse_xml

Back to xml.XmlRenderer

Arguments:
self, source, fragment=False, no_leading_text=False, **kw

Parse a XML file

In:
  • source -- can be a filename or a file object
  • fragment -- if True, can parse a XML fragment i.e a XML without a unique root
  • no_leading_text -- if fragment is True, no_leading_text is False and the XML to parsed begins by a text, this text is keeped
  • kw -- keywords parameters are passed to the XML parser
Return:
  • the root element of the parsed XML, if fragment is False
  • a list of XML elements, if fragment is True

Method xml.XmlRenderer.parse_xmlstring

Back to xml.XmlRenderer

Arguments:
self, text, fragment=False, no_leading_text=False, **kw

Parse a XML string

In:
  • text -- can be a str or unicode string
  • fragment -- if True, can parse a XML fragment i.e a XML without a unique root
  • no_leading_text -- if fragment is True, no_leading_text is False and the XML to parsed begins by a text, this text is keeped
  • kw -- keywords parameters are passed to the XML parser
Return:
  • the root element of the parsed XML, if fragment is False
  • a list of XML elements, if fragment is True

Method xml.XmlRenderer.processing_instruction

Back to xml.XmlRenderer

Arguments:
self, target, text=None, **kw

Create a processing instruction element

In:
  • target -- the PI target
  • text -- the PI text
  • kw -- pseudo attributes
Return:
  • the new processing instruction element

Method xml.XmlRenderer.root

Back to xml.XmlRenderer

Arguments:
self

Return the first tag(s) sent to the renderer

Warning

A list of tags can be returned

Return:
  • the tag(s)
Decorators:
@property

Class xml._Tag

Back to xml

Bases:
ET.ElementBase

A xml tag

Methods:
__call__(self, *children, **attrib): Append child and attributes to this tag
__enter__(self):
__exit__(self, exception, data, tb):
add_child(self, child): Append a child to this tag
append_text(self, text): Append a text to this tag
fill(self, *children, **attrib): Change all the child and append attributes of this tag
findmeld(self, id, default=None): Find a tag with a given meld:id value
init(self, renderer): Each tag keeps track of the renderer that created it
meld_id(self, id): Set the value of the attribute meld:id of this tag
renderer(self): Return the renderer that created this tag
repeat(self, iterable, childname=None): Iterate over a sequence, cloning a new child each time
replace(self, *children): Replace this tag by others
write_xmlstring(self, encoding='utf-8', pipeline=True, **kw): Serialize in XML the tree beginning at this tag
xpath(self, *args, **kw): Override xpath() to associate a renderer to all the returned nodes

Method xml._Tag.__call__

Back to xml._Tag

Arguments:
self, *children, **attrib

Append child and attributes to this tag

In:
  • children -- children to add
  • attrib -- attributes to add
Return:
  • self

Method xml._Tag.add_child

Back to xml._Tag

Arguments:
self, child

Append a child to this tag

In:
  • child -- child to add

Method xml._Tag.append_text

Back to xml._Tag

Arguments:
self, text

Append a text to this tag

In:
  • text -- text to add

Method xml._Tag.fill

Back to xml._Tag

Arguments:
self, *children, **attrib

Change all the child and append attributes of this tag

In:
  • children -- list of the new children of this tag
  • attrib -- dictionnary of attributes of this tag
Return:
  • self

Method xml._Tag.findmeld

Back to xml._Tag

Arguments:
self, id, default=None

Find a tag with a given meld:id value

In:
  • id -- value of the meld:id attribute to search
  • default -- value returned if the tag is not found
Return:
  • the tag found, else the default value

Method xml._Tag.init

Back to xml._Tag

Arguments:
self, renderer

Each tag keeps track of the renderer that created it

Return:
  • self

Method xml._Tag.meld_id

Back to xml._Tag

Arguments:
self, id

Set the value of the attribute meld:id of this tag

In:
  • id - value of the meld;id attribute
Return:
  • self

Method xml._Tag.renderer

Back to xml._Tag

Arguments:
self

Return the renderer that created this tag

Return:
  • the renderer
Decorators:
@property

Method xml._Tag.repeat

Back to xml._Tag

Arguments:
self, iterable, childname=None

Iterate over a sequence, cloning a new child each time

In:
  • iterable -- the sequence
  • childname -- If None, clone this tag each time else clone each time the tag that have childname as meld:id value
Return:
  • list of tuples (cloned child, item of the sequence)

Method xml._Tag.replace

Back to xml._Tag

Arguments:
self, *children

Replace this tag by others

In:
  • children -- list of tags to replace this tag

Method xml._Tag.write_xmlstring

Back to xml._Tag

Arguments:
self, encoding='utf-8', pipeline=True, **kw

Serialize in XML the tree beginning at this tag

In:
  • encoding -- encoding of the XML
  • pipeline -- if False, the meld:id attributes are deleted
Return:
  • the XML

Method xml.add_attribute

Back to xml

Arguments:
self, name, value

Default method to add an attribute to a tag

In:
  • self -- the tag
  • name -- name of the attribute to add
  • value -- value of the attribute to add

Method xml.add_child

Back to xml

Arguments:
self, o

Default method to add an object to a tag

In:
  • self -- the tag
  • o -- object to add

Try to add the result of o.render() to the tag


Method xml.add_child

Back to xml

Arguments:
self, s

Add a string to a tag

In:
  • self -- the tag
  • s - str or unicode string to add
Decorators:
@peak.rules.when(add_child, (_Tag, basestring))

Method xml.add_child

Back to xml

Arguments:
self, i

Add elements to a tag

In:
  • self -- the tag
  • i -- elements to add

Add each element as a child

Decorators:
@peak.rules.when(add_child, (_Tag, (list, tuple, types.GeneratorType)))

Method xml.add_child

Back to xml

Arguments:
self, n

Add a number to a tag

In:
  • self -- the tag
  • n -- number to add

Convert the number to string and then add it

Decorators:
@peak.rules.when(add_child, (_Tag, (int, long, float)))

Method xml.add_child

Back to xml

Arguments:
self, element

Add a tag to a tag

In:
  • self -- the tag
  • element -- the tag to add
Decorators:
@peak.rules.when(add_child, (_Tag, ET._Element))

Method xml.add_child

Back to xml

Arguments:
self, element

Add a comment element to a tag

In:
  • self -- the tag
  • element -- the comment to add
Decorators:
@peak.rules.when(add_child, (_Tag, ET._Comment))

Method xml.add_child

Back to xml

Arguments:
self, element

Add a PI element to a tag

In:
  • self -- the tag
  • element -- the PI to add

Do nothing

Decorators:
@peak.rules.when(add_child, (_Tag, ET._ProcessingInstruction))

Method xml.add_child

Back to xml

Arguments:
self, d

Add a dictionary to a tag

In:
  • self -- the tag
  • element -- the dictionary to add

Each key/value becomes an attribute of the tag

Attribute name can end with a '_' which is removed

Decorators:
@peak.rules.when(add_child, (_Tag, dict))