Skip to main content
`Ctrl`+`K`

# XMLWriter

class astropy.utils.xml.writer.XMLWriter(file)

  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 file-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)

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

    Parameters:
      id `python:int`

        Element identifier, as returned by the `start` method.

  comment(comment)

    Adds a comment to the output stream.

    Parameters:
      comment `python:str`

        Comment text, as a Unicode string.

  data(text)

    Adds character data to the output stream.

    Parameters:
      text `python:str`

        Character data, as a Unicode string.

  element(tag, text=None, wrap=False, attrib={}, **extra)

    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)

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

    Parameters:
      tag `python:str`

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

  flush()
  get_indentation()

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

  get_indentation_spaces(offset=0)

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

  static object_attrs(obj, attrs)

    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 python:sequence of `python:str`

        Attribute names to pull from the object

    Returns:
      attrs `python:dict`

        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)

    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 `python:str`

        The element name

      attrib `python:dict` of `python:str` -> `python:str`

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

    Returns:
      id `python:int`

        Returns an element identifier.

  string_element(xml_string)

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

  tag(tag, attrib={}, **extra)

    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)

    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:
      method `python: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.