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:
filefile-like (writeable)

Methods Summary

close(id)

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

comment(comment)

Adds a comment to the output stream.

data(text)

Adds character data to the output stream.

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

Adds an entire element.

end([tag, indent, wrap])

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

flush()

get_indentation()

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

get_indentation_spaces([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(tag[, attrib])

Opens a new element.

string_element(xml_string)

Reformat the indentation in the XML to insert the MIVOT block.

tag(tag[, attrib])

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

xml_cleaning_method([method])

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

Methods Documentation

close(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(comment)[source]#

Adds a comment to the output stream.

Parameters:
commentstr

Comment text, as a Unicode string.

data(text)[source]#

Adds character data to the output stream.

Parameters:
textstr

Character data, as a Unicode string.

element(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(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()[source]#
get_indentation()[source]#

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

get_indentation_spaces(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(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.

string_element(xml_string)[source]#

Reformat the indentation in the XML to insert the MIVOT block.

tag(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(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 bleach 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="https://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.