aboutsummaryrefslogtreecommitdiff
path: root/.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py
diff options
context:
space:
mode:
Diffstat (limited to '.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py')
-rw-r--r--.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py187
1 files changed, 187 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py b/.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py
new file mode 100644
index 00000000..f4169295
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/docutils/writers/docutils_xml.py
@@ -0,0 +1,187 @@
+# $Id: docutils_xml.py 9502 2023-12-14 22:39:08Z milde $
+# Author: David Goodger, Paul Tremblay, Guenter Milde
+# Maintainer: docutils-develop@lists.sourceforge.net
+# Copyright: This module has been placed in the public domain.
+
+"""
+Simple document tree Writer, writes Docutils XML according to
+https://docutils.sourceforge.io/docs/ref/docutils.dtd.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from io import StringIO
+import xml.sax.saxutils
+
+import docutils
+from docutils import frontend, nodes, writers, utils
+
+
+class RawXmlError(docutils.ApplicationError):
+ pass
+
+
+class Writer(writers.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': frontend.validate_boolean}),
+ ('Generate XML with indents and newlines.',
+ ['--indents'], # TODO use integer value for number of spaces?
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
+ ('Omit the XML declaration. Use with caution.',
+ ['--no-xml-declaration'],
+ {'dest': 'xml_declaration', 'default': 1, 'action': 'store_false',
+ 'validator': frontend.validate_boolean}),
+ ('Omit the DOCTYPE declaration.',
+ ['--no-doctype'],
+ {'dest': 'doctype_declaration', 'default': 1,
+ 'action': 'store_false', 'validator': frontend.validate_boolean}),))
+
+ settings_defaults = {'output_encoding_error_handler': 'xmlcharrefreplace'}
+
+ config_section = 'docutils_xml writer'
+ config_section_dependencies = ('writers',)
+
+ output = None
+ """Final translated form of `document`."""
+
+ def __init__(self):
+ writers.Writer.__init__(self)
+ self.translator_class = XMLTranslator
+
+ def translate(self):
+ self.visitor = visitor = self.translator_class(self.document)
+ self.document.walkabout(visitor)
+ self.output = ''.join(visitor.output)
+
+
+class XMLTranslator(nodes.GenericNodeVisitor):
+
+ # TODO: add stylesheet options similar to HTML and LaTeX writers?
+ # xml_stylesheet = '<?xml-stylesheet type="text/xsl" href="%s"?>\n'
+ 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.make_parser()
+ """SAX parser instance to check/extract raw XML."""
+ xmlparser.setFeature(
+ "http://xml.org/sax/features/external-general-entities", True)
+
+ def __init__(self, document):
+ nodes.NodeVisitor.__init__(self, document)
+
+ # Reporter
+ self.warn = self.document.reporter.warning
+ self.error = self.document.reporter.error
+
+ # Settings
+ self.settings = settings = document.settings
+ self.indent = self.newline = ''
+ if settings.newlines:
+ self.newline = '\n'
+ if settings.indents:
+ self.newline = '\n'
+ self.indent = ' ' # TODO make this configurable?
+ self.level = 0 # indentation level
+ self.in_simple = 0 # level of nesting inside mixed-content elements
+ self.fixed_text = 0 # level of nesting inside FixedText elements
+
+ # Output
+ self.output = []
+ if settings.xml_declaration:
+ self.output.append(utils.xml_declaration(settings.output_encoding))
+ if settings.doctype_declaration:
+ self.output.append(self.doctype)
+ self.output.append(self.generator % docutils.__version__)
+
+ # initialize XML parser
+ self.the_handle = TestXml()
+ self.xmlparser.setContentHandler(self.the_handle)
+
+ # generic visit and depart methods
+ # --------------------------------
+
+ simple_nodes = (nodes.TextElement, nodes.meta,
+ nodes.image, nodes.colspec, nodes.transition)
+
+ def default_visit(self, node):
+ """Default node visit method."""
+ if not self.in_simple:
+ self.output.append(self.indent*self.level)
+ self.output.append(node.starttag(xml.sax.saxutils.quoteattr))
+ self.level += 1
+ # `nodes.literal` is not an instance of FixedTextElement by design,
+ # see docs/ref/rst/restructuredtext.html#inline-literals
+ if isinstance(node, (nodes.FixedTextElement, nodes.literal)):
+ self.fixed_text += 1
+ if isinstance(node, self.simple_nodes):
+ self.in_simple += 1
+ if not self.in_simple:
+ self.output.append(self.newline)
+
+ def default_departure(self, node):
+ """Default node depart method."""
+ self.level -= 1
+ if not self.in_simple:
+ self.output.append(self.indent*self.level)
+ self.output.append(node.endtag())
+ if isinstance(node, (nodes.FixedTextElement, nodes.literal)):
+ self.fixed_text -= 1
+ if isinstance(node, self.simple_nodes):
+ self.in_simple -= 1
+ if not self.in_simple:
+ self.output.append(self.newline)
+
+ # specific visit and depart methods
+ # ---------------------------------
+
+ def visit_Text(self, node):
+ text = xml.sax.saxutils.escape(node.astext())
+ # indent text if we are not in a FixedText element:
+ if not self.fixed_text:
+ text = text.replace('\n', '\n'+self.indent*self.level)
+ self.output.append(text)
+
+ def depart_Text(self, node):
+ pass
+
+ def visit_raw(self, node):
+ if 'xml' not in node.get('format', '').split():
+ # skip other raw content?
+ # raise nodes.SkipNode
+ self.default_visit(node)
+ return
+ # wrap in <raw> element
+ self.default_visit(node) # or not?
+ xml_string = node.astext()
+ self.output.append(xml_string)
+ self.default_departure(node) # or not?
+ # Check validity of raw XML:
+ try:
+ self.xmlparser.parse(StringIO(xml_string))
+ except xml.sax._exceptions.SAXParseException:
+ col_num = self.the_handle.locator.getColumnNumber()
+ line_num = self.the_handle.locator.getLineNumber()
+ srcline = node.line
+ if not isinstance(node.parent, nodes.TextElement):
+ srcline += 2 # directive content start line
+ msg = 'Invalid raw XML in column %d, line offset %d:\n%s' % (
+ col_num, line_num, node.astext())
+ self.warn(msg, source=node.source, line=srcline+line_num-1)
+ raise nodes.SkipNode # content already processed
+
+
+class TestXml(xml.sax.handler.ContentHandler):
+
+ def setDocumentLocator(self, locator):
+ self.locator = locator