docutils.writers.docutils_xml module

Simple document tree Writer, writes Docutils XML according to https://docutils.sourceforge.io/docs/ref/docutils.dtd.

exception RawXmlError

Bases: ApplicationError

class Writer

Bases: Writer

supported = ('xml',)

Formats this writer supports.

settings_spec = ('"Docutils XML" Writer Options', None, (('Generate XML with newlines before and after tags.', ['--newlines'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Generate XML with indents and newlines.', ['--indents'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Omit the XML declaration.  Use with caution.', ['--no-xml-declaration'], {'action': 'store_false', 'default': 1, 'dest': 'xml_declaration', 'validator': <function validate_boolean>}), ('Omit the DOCTYPE declaration.', ['--no-doctype'], {'action': 'store_false', 'default': 1, 'dest': 'doctype_declaration', 'validator': <function validate_boolean>})))

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

• Option group title (string or None which implies no group, just a list of single options).

• Description (string or None).

• A sequence of option tuples. Each consists of:

  • Help text (string)

  • List of option strings (e.g. ['-Q', '--quux']).

  • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

    Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

    Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

    See the optparse docs for more details.

• More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

settings_defaults = {'output_encoding_error_handler': 'xmlcharrefreplace'}

A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.

config_section = 'docutils_xml writer'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

config_section_dependencies = ('writers',)

A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.

output = None

Final translated form of document.

translate()

Do final translation of self.document into self.output. Called from write. Override in subclasses.

Usually done with a docutils.nodes.NodeVisitor subclass, in combination with a call to docutils.nodes.Node.walk() or docutils.nodes.Node.walkabout(). The NodeVisitor subclass must support all standard elements (listed in docutils.nodes.node_class_names) and possibly non-standard elements used by the current Reader as well.

class XMLTranslator(document)

Bases: GenericNodeVisitor

doctype = '<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">\n'

generator = '<!-- Generated by Docutils %s -->\n'

xmlparser = <xml.sax.expatreader.ExpatParser object>

SAX parser instance to check/extract raw XML.

simple_nodes = (<class 'docutils.nodes.TextElement'>, <class 'docutils.nodes.image'>, <class 'docutils.nodes.colspec'>, <class 'docutils.nodes.transition'>)

default_visit(node)

Default node visit method.

default_departure(node)

Default node depart method.

visit_Text(node)

depart_Text(node)

visit_raw(node)

class TestXml

Bases: ContentHandler

setDocumentLocator(locator)

Called by the parser to give the application a locator for locating the origin of document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the DocumentHandler interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application’s business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation of the events in this interface. The application should not attempt to use it at any other time.