XMLWriter¶
-
class
astropy.utils.xml.writer.
XMLWriter
(file)[source] [edit on github]¶ 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: - file : writable file-like object.
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. 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] [edit on github]¶ Closes open elements, up to (and including) the element identified by the given identifier.
Parameters: - id : int
Element identifier, as returned by the
start
method.
-
comment
(comment)[source] [edit on github]¶ Adds a comment to the output stream.
Parameters: - comment : str
Comment text, as a Unicode string.
-
data
(text)[source] [edit on github]¶ Adds character data to the output stream.
Parameters: - text : str
Character data, as a Unicode string.
-
element
(tag, text=None, wrap=False, attrib={}, **extra)[source] [edit on github]¶ Adds an entire element. This is the same as calling
start
,data
, andend
in sequence. Thetext
argument can be omitted.
-
end
(tag=None, indent=True, wrap=False)[source] [edit on github]¶ Closes the current element (opened by the most recent call to
start
).Parameters: - tag : str
Element name. If given, the tag must match the start tag. If omitted, the current element is closed.
-
flush
()[source] [edit on github]¶
-
get_indentation
()[source] [edit on github]¶ Returns the number of indentation levels the file is currently in.
-
get_indentation_spaces
(offset=0)[source] [edit on github]¶ Returns a string of spaces that matches the current indentation level.
-
static
object_attrs
(obj, attrs)[source] [edit on github]¶ Converts an object with a bunch of attributes on an object into a dictionary for use by the
XMLWriter
.Parameters: - obj : object
Any Python object
- attrs : sequence of str
Attribute names to pull from the object
Returns: - attrs : dict
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
(tag, attrib={}, **extra)[source] [edit on github]¶ 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: - tag : str
The element name
- attrib : dict of str -> str
Attribute dictionary. Alternatively, attributes can be given as keyword arguments.
Returns: - id : int
Returns an element identifier.
-
tag
(tag, attrib={}, **extra)[source] [edit on github]¶ A convenience method for creating wrapper elements using the
with
statement.Examples
>>> with writer.tag('foo'): # doctest: +SKIP ... writer.element('bar') ... # </foo> is implicitly closed here ...
Parameters are the same as to
start
.
-
xml_cleaning_method
(method='escape_xml', **clean_kwargs)[source] [edit on github]¶ 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 http://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="http://google.com">google.com</a>') w.end()
Parameters: - method : str
Cleaning method. Allowed values are “escape_xml”, “bleach_clean”, and “none”.
- **clean_kwargs : keyword args
Additional keyword args that are passed to the bleach.clean() function.