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
, andend
in sequence. Thetext
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.
-
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 isNone
, 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 theclean
function of the https://bleach.readthedocs.io/en/latest/clean.html package. Any additional keyword arguments will be passed directly to theclean
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.