Repository: twisted/twisted

Issue:
deprecate microdom
|[<img alt="exarkun's avatar" src="https://avatars.githubusercontent.com/u/254565?s=50" width="50" height="50">](https://github.com/exarkun)| @exarkun reported|
|-|-|
|Trac ID|trac#3561|
|Type|task|
|Created|2008-12-01 17:44:45Z|

In the olden days, there were lots of XML parsers, and they were bad.  Now there's even more XML parsers, and they're not _so_ bad.  But microdom is still bad.  Now it's probably worse than most other XML libraries.  Plus, we're not going to fix the obvious bugs in it (eg [#8049](https://github.com/twisted/twisted/issues/8049)).  People shouldn't use it, so it should be deprecated.

`twisted.web.html` uses microdom, so it should also be deprecated probably (it's not an intensely useful module anyway).  Anything else in Twisted which uses microdom (hopefully, not many things) should stop or also be deprecated (some things in domhelpers use it, for example).


<details><summary>Searchable metadata</summary>

```
trac-id__3561 3561
type__task task
reporter__exarkun exarkun
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__new new
resolution__ 
component__web web
keywords__ 
time__1228153485000000 1228153485000000
changetime__1434535103308074 1434535103308074
version__None None
owner__ 
cc__glyph
```
</details>


Discussion:

Patch:
diff --git a/src/twisted/web/domhelpers.py b/src/twisted/web/domhelpers.py
index 6ccc7c920f..0903eb692b 100644
--- a/src/twisted/web/domhelpers.py
+++ b/src/twisted/web/domhelpers.py
@@ -4,13 +4,23 @@
 
 """
 A library for performing interesting tasks with DOM objects.
-"""
 
+This module is now deprecated.
+"""
+import warnings
 from io import StringIO
 
+from incremental import Version, getVersionString
+
 from twisted.web import microdom
 from twisted.web.microdom import escape, getElementsByTagName, unescape
 
+warningString = "twisted.web.domhelpers was deprecated at {}".format(
+    getVersionString(Version("Twisted", "NEXT", 0, 0))
+)
+warnings.warn(warningString, DeprecationWarning, stacklevel=3)
+
+
 # These modules are imported here as a shortcut.
 escape
 getElementsByTagName
diff --git a/src/twisted/web/microdom.py b/src/twisted/web/microdom.py
index 6c23a1a890..51eff3f4f6 100644
--- a/src/twisted/web/microdom.py
+++ b/src/twisted/web/microdom.py
@@ -16,17 +16,27 @@ fine for the documentation generator, which parses a fairly representative
 sample of XML.
 
 Microdom mainly focuses on working with HTML and XHTML.
+
+This module is now deprecated.
 """
 
 # System Imports
 import re
+import warnings
 from io import BytesIO, StringIO
 
+from incremental import Version, getVersionString
+
 # Twisted Imports
 from twisted.python.compat import ioType
 from twisted.python.util import InsensitiveDict
 from twisted.web.sux import ParseError, XMLParser
 
+warningString = "twisted.web.microdom was deprecated at {}".format(
+    getVersionString(Version("Twisted", "NEXT", 0, 0))
+)
+warnings.warn(warningString, DeprecationWarning, stacklevel=3)
+
 
 def getElementsByTagName(iNode, name):
     """
diff --git a/src/twisted/web/newsfragments/3651.removal b/src/twisted/web/newsfragments/3651.removal
new file mode 100644
index 0000000000..06a16e473a
--- /dev/null
+++ b/src/twisted/web/newsfragments/3651.removal
@@ -0,0 +1,1 @@
+twisted.dom.microdom and twisted.web.domhelpers are now deprecated.


Test patch:
diff --git a/src/twisted/web/test/test_domhelpers.py b/src/twisted/web/test/test_domhelpers.py
index 9e876c7d43..670f9bc30c 100644
--- a/src/twisted/web/test/test_domhelpers.py
+++ b/src/twisted/web/test/test_domhelpers.py
@@ -5,7 +5,7 @@
 """
 Specific tests for (some of) the methods in L{twisted.web.domhelpers}.
 """
-
+from importlib import reload
 from typing import Any, Optional
 from xml.dom import minidom
 
@@ -260,6 +260,18 @@ class MicroDOMHelpersTests(DOMHelpersTestsMixin, TestCase):
         actual = domhelpers.gatherTextNodes(doc5.documentElement)
         self.assertEqual(actual, expected)
 
+    def test_deprecation(self):
+        """
+        An import will raise the deprecation warning.
+        """
+        reload(domhelpers)
+        warnings = self.flushWarnings([self.test_deprecation])
+        self.assertEqual(1, len(warnings))
+        self.assertEqual(
+            "twisted.web.domhelpers was deprecated at Twisted NEXT",
+            warnings[0]["message"],
+        )
+
 
 class MiniDOMHelpersTests(DOMHelpersTestsMixin, TestCase):
     dom = minidom
diff --git a/src/twisted/web/test/test_xml.py b/src/twisted/web/test/test_xml.py
index 39bf78b7e0..129137b824 100644
--- a/src/twisted/web/test/test_xml.py
+++ b/src/twisted/web/test/test_xml.py
@@ -5,7 +5,7 @@
 """
 Some fairly inadequate testcases for Twisted XML support.
 """
-
+from importlib import reload
 from io import BytesIO
 
 from twisted.trial.unittest import TestCase
@@ -788,6 +788,18 @@ alert("I hate you");
         xmlOut = document.toxml()
         self.assertEqual(xmlOut, xmlOk)
 
+    def test_deprecation(self):
+        """
+        An import will raise the deprecation warning.
+        """
+        reload(microdom)
+        warnings = self.flushWarnings([self.test_deprecation])
+        self.assertEqual(1, len(warnings))
+        self.assertEqual(
+            "twisted.web.microdom was deprecated at Twisted NEXT",
+            warnings[0]["message"],
+        )
+
 
 class BrokenHTMLTests(TestCase):
     """