XMLWriter

class astropy.utils.xml.writer.XMLWriter(file)[source]

Bases: object

A class to write well-formed and nicely indented XML.

Use like this:

w = XMLWriter(fh)
with w.tag('html'):
    with w.tag('body'):
        w.data('This is the content')

Which produces:

<html>
 <body>
  This is the content
 </body>
</html>
Parameters
filewritable file-like object.

Methods Summary

close(self, id)

Closes open elements, up to (and including) the element identified by the given identifier.

comment(self, comment)

Adds a comment to the output stream.

data(self, text)

Adds character data to the output stream.

element(self, tag[, text, wrap, attrib])

Adds an entire element.

end(self[, tag, indent, wrap])

Closes the current element (opened by the most recent call to start).

flush(self)

get_indentation(self)

Returns the number of indentation levels the file is currently in.

get_indentation_spaces(self[, offset])

Returns a string of spaces that matches the current indentation level.

object_attrs(obj, attrs)

Converts an object with a bunch of attributes on an object into a dictionary for use by the XMLWriter.

start(self, tag[, attrib])

Opens a new element.

tag(self, tag[, attrib])

A convenience method for creating wrapper elements using the with statement.

xml_cleaning_method(self[, method])

Context manager to control how XML data tags are cleaned (escaped) to remove potentially unsafe characters or constructs.

Methods Documentation

close(self, id)[source]

Closes open elements, up to (and including) the element identified by the given identifier.

Parameters
idint

Element identifier, as returned by the start method.

comment(self, comment)[source]

Adds a comment to the output stream.

Parameters
commentstr

Comment text, as a Unicode string.

data(self, text)[source]

Adds character data to the output stream.

Parameters
textstr

Character data, as a Unicode string.

element(self, tag, text=None, wrap=False, attrib={}, **extra)[source]

Adds an entire element. This is the same as calling start, data, and end in sequence. The text argument can be omitted.

end(self, tag=None, indent=True, wrap=False)[source]

Closes the current element (opened by the most recent call to start).

Parameters
tagstr

Element name. If given, the tag must match the start tag. If omitted, the current element is closed.

flush(self)[source]
get_indentation(self)[source]

Returns the number of indentation levels the file is currently in.

get_indentation_spaces(self, offset=0)[source]

Returns a string of spaces that matches the current indentation level.

static object_attrs(obj, attrs)[source]

Converts an object with a bunch of attributes on an object into a dictionary for use by the XMLWriter.

Parameters
objobject

Any Python object

attrssequence of str

Attribute names to pull from the object

Returns
attrsdict

Maps attribute names to the values retrieved from obj.attr. If any of the attributes is None, it will not appear in the output dictionary.

start(self, tag, attrib={}, **extra)[source]

Opens a new element. Attributes can be given as keyword arguments, or as a string/string dictionary. The method returns an opaque identifier that can be passed to the close() method, to close all open elements up to and including this one.

Parameters
tagstr

The element name

attribdict of str -> str

Attribute dictionary. Alternatively, attributes can be given as keyword arguments.

Returns
idint

Returns an element identifier.

tag(self, tag, attrib={}, **extra)[source]

A convenience method for creating wrapper elements using the with statement.

Examples

>>> with writer.tag('foo'):  
...     writer.element('bar')
... # </foo> is implicitly closed here
...

Parameters are the same as to start.

xml_cleaning_method(self, method='escape_xml', **clean_kwargs)[source]

Context manager to control how XML data tags are cleaned (escaped) to remove potentially unsafe characters or constructs.

The default (method='escape_xml') applies brute-force escaping of certain key XML characters like <, >, and & to ensure that the output is not valid XML.

In order to explicitly allow certain XML tags (e.g. link reference or emphasis tags), use method='bleach_clean'. This sanitizes the data string using the clean function of the http://bleach.readthedocs.io/en/latest/clean.html package. Any additional keyword arguments will be passed directly to the clean function.

Finally, use method='none' to disable any sanitization. This should be used sparingly.

Example:

w = writer.XMLWriter(ListWriter(lines))
with w.xml_cleaning_method('bleach_clean'):
    w.start('td')
    w.data('<a href="http://google.com">google.com</a>')
    w.end()
Parameters
methodstr

Cleaning method. Allowed values are “escape_xml”, “bleach_clean”, and “none”.

**clean_kwargskeyword args

Additional keyword args that are passed to the bleach.clean() function.