write_filename

igwn_ligolw.utils.write_filename(xmldoc, filename, verbose=False, compress=None, with_mv=True, trap_signals=(Signals.SIGTERM, Signals.SIGTSTP), **kwargs)

Writes the LIGO Light Weight document tree rooted at xmldoc to the file name filename. If filename is None the file is written to stdout, otherwise it is written to the named file. Friendly verbosity messages are printed while writing the file if verbose is True.

The compress keyword argument selects the compression format to use. Recognized values are: “auto” to automatically select the format based on filename; None to select the default behaviour (which is “auto”); or any of the compression format values recognized by write_fileobj(). When “auto” is the mode selected, then if the filename ends in “.bz2”, “.gz”, or “.xz” then the corresponding compression format is selected, othewrise if the filename does not match a recognized pattern or if filename is None (writing to stdout) then compression is disabled.

If with_mv is True and filename is not None the filename has a “~” appended to it and the file is written to that name then moved to the requested name once the write has completed successfully.

Internally, write_fileobj() is used to perform the write. All additional keyword arguments are passed to write_fileobj().

This function traps the signals in the trap_signals iterable during the write process (see SignalsTrap for the default signals), and it does this by temporarily installing its own signal handlers in place of the current handlers. This is done to prevent HTCondor eviction during the write process. When the file write is concluded the original signal handlers are restored. Then, if signals were trapped during the write process, the signals are resent to the current process in the order in which they were received. The signal.signal() system call cannot be invoked from threads, and trap_signals must be set to None or an empty sequence if this function is used from a thread.

Example:

>>> # write file
>>> write_filename(xmldoc, "demo.xml")
>>> # write gzip-compressed file (auto-select format)
>>> write_filename(xmldoc, "demo.xml.gz")
>>> # force compression off
>>> write_filename(xmldoc, "demo.xml.gz", compress = False)