address final comments

Author: picnixz

Doc/library/pyexpat.rst

@@ -72,6 +72,13 @@ The :mod:`xml.parsers.expat` module contains two functions:
    *encoding* [1]_ is given it will override the implicit or explicit encoding of the
    document.
 
+   .. _xmlparser-non-root:
+
+   Parsers created through :func:`!ParserCreate` are called "root" parsers,
+   in the sense that they do not have any parent parser attached. Non-root
+   parsers are created by :meth:`parser.ExternalEntityParserCreate
+   <xmlparser.ExternalEntityParserCreate>`.
+
    Expat can optionally do XML namespace processing for you, enabled by providing a
    value for *namespace_separator*.  The value must be a one-character string; a
    :exc:`ValueError` will be raised if the string has an illegal length (``None``
@@ -120,11 +127,6 @@ The :mod:`xml.parsers.expat` module contains two functions:
 XMLParser Objects
 -----------------
 
-.. class:: xmlparser
-
-   The type of an Expat XML parser created by :func:`ParserCreate`.
-
-
 :class:`xmlparser` objects have the following methods:
 
 
@@ -236,7 +238,7 @@ XMLParser Objects
    .. versionadded:: 3.13
 
 
-:class:`xmlparser` objects have the following methods to mitigate some
+:class:`!xmlparser` objects have the following methods to mitigate some
 common XML vulnerabilities.
 
 .. method:: xmlparser.SetAllocTrackerActivationThreshold(threshold, /)
@@ -247,7 +249,8 @@ common XML vulnerabilities.
    By default, parser objects have an allocation activation threshold of 64 MiB,
    or equivalently 67,108,864 bytes.
 
-   An :exc:`ExpatError` is raised if this method is called on a non-root parser.
+   An :exc:`ExpatError` is raised if this method is called on a
+   |xml-non-root-parser| parser.
    The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
    should not be used as they may have no special meaning.
 
@@ -270,8 +273,8 @@ common XML vulnerabilities.
 
    By default, parser objects have a maximum amplification factor of 100.0.
 
-   An :exc:`ExpatError` is raised if this method is called on a non-root
-   parser or if *max_factor* is outside the valid range.
+   An :exc:`ExpatError` is raised if this method is called on a
+   |xml-non-root-parser| parser or if *max_factor* is outside the valid range.
    The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
    should not be used as they may have no special meaning.
 
@@ -1007,3 +1010,4 @@ The ``errors`` module has the following attributes:
    not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
    and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
 
+.. |xml-non-root-parser| replace:: :ref:`non-root <xmlparser-non-root>`

Doc/whatsnew/3.15.rst

@@ -545,7 +545,7 @@ xml.parsers.expat
 
 * Add :func:`~xml.parsers.expat.xmlparser.SetAllocTrackerActivationThreshold`
   and :func:`~xml.parsers.expat.xmlparser.SetAllocTrackerMaximumAmplification`
-  to :class:`~xml.parsers.expat.xmlparser` objects to prevent use of
+  to :ref:`xmlparser <xmlparser-objects>` objects to prevent use of
   disproportional amounts of dynamic memory from within an Expat parser.
   (Contributed by Bénédikt Tran in :gh:`90949`.)
 

Lib/test/test_pyexpat.py

@@ -7,6 +7,7 @@
 import re
 import sys
 import sysconfig
+import textwrap
 import unittest
 import traceback
 from io import BytesIO
@@ -834,24 +835,42 @@ class AttackProtectionTestBase(abc.ABC):
     """
 
     @staticmethod
-    def exponential_expansion_payload(ncols, nrows, text='.'):
+    def exponential_expansion_payload(*, nrows, ncols, text='.'):
         """Create a billion laughs attack payload.
 
         Be careful: the number of total items is pow(n, k), thereby
         requiring at least pow(ncols, nrows) * sizeof(text) memory!
         """
+        template = textwrap.dedent(f"""\
+            <?xml version="1.0"?>
+            <!DOCTYPE doc [
+                <!ENTITY row0 "{text}">
+                <!ELEMENT doc (#PCDATA)>
+            {{body}}
+            ]>
+            <doc>&row{nrows};</doc>
+        """).rstrip()
+
         body = '\n'.join(
             f'<!ENTITY row{i + 1} "{f"&row{i};" * ncols}">'
             for i in range(nrows)
         )
-        return f"""\
-<?xml version="1.0"?>
-<!DOCTYPE doc [
-<!ENTITY row0 "{text}">
-<!ELEMENT doc (#PCDATA)>
-{body}
-]>
-<doc>&row{nrows};</doc>"""
+        body = textwrap.indent(body, ' ' * 4)
+        return template.format(body=body)
+
+    def test_payload_generation(self):
+        # self-test for exponential_expansion_payload()
+        payload = self.exponential_expansion_payload(nrows=2, ncols=3)
+        self.assertEqual(payload, textwrap.dedent("""\
+            <?xml version="1.0"?>
+            <!DOCTYPE doc [
+                <!ENTITY row0 ".">
+                <!ELEMENT doc (#PCDATA)>
+                <!ENTITY row1 "&row0;&row0;&row0;">
+                <!ENTITY row2 "&row1;&row1;&row1;">
+            ]>
+            <doc>&row2;</doc>
+        """).rstrip())
 
     def assert_root_parser_failure(self, func, /, *args, **kwargs):
         """Check that func(*args, **kwargs) is invalid for a sub-parser."""
@@ -966,7 +985,7 @@ def test_set_activation_threshold__threshold_reached(self):
         # Check that the threshold is reached by choosing a small factor
         # and a payload whose peak amplification factor exceeds it.
         self.assertIsNone(self.set_maximum_amplification(parser, 1.0))
-        payload = self.exponential_expansion_payload(10, 4)
+        payload = self.exponential_expansion_payload(ncols=10, nrows=4)
         self.assert_rejected(parser.Parse, payload, True)
 
     def test_set_activation_threshold__threshold_not_reached(self):
@@ -976,7 +995,7 @@ def test_set_activation_threshold__threshold_not_reached(self):
         # Check that the threshold is reached by choosing a small factor
         # and a payload whose peak amplification factor exceeds it.
         self.assertIsNone(self.set_maximum_amplification(parser, 1.0))
-        payload = self.exponential_expansion_payload(10, 4)
+        payload = self.exponential_expansion_payload(ncols=10, nrows=4)
         self.assertIsNotNone(parser.Parse(payload, True))
 
     def test_set_maximum_amplification__amplification_exceeded(self):
@@ -986,7 +1005,7 @@ def test_set_maximum_amplification__amplification_exceeded(self):
         # Choose a max amplification factor expected to always be exceeded.
         self.assertIsNone(self.set_maximum_amplification(parser, 1.0))
         # Craft a payload for which the peak amplification factor is > 1.0.
-        payload = self.exponential_expansion_payload(1, 2)
+        payload = self.exponential_expansion_payload(ncols=1, nrows=2)
         self.assert_rejected(parser.Parse, payload, True)
 
     def test_set_maximum_amplification__amplification_not_exceeded(self):
@@ -996,7 +1015,7 @@ def test_set_maximum_amplification__amplification_not_exceeded(self):
         # Choose a max amplification factor expected to never be exceeded.
         self.assertIsNone(self.set_maximum_amplification(parser, 1e4))
         # Craft a payload for which the peak amplification factor is < 1e4.
-        payload = self.exponential_expansion_payload(1, 2)
+        payload = self.exponential_expansion_payload(ncols=1, nrows=2)
         self.assertIsNotNone(parser.Parse(payload, True))
 
 

Misc/NEWS.d/next/Library/2025-09-22-14-40-11.gh-issue-90949.UM35nb.rst

@@ -1,5 +1,5 @@
 Add :func:`~xml.parsers.expat.xmlparser.SetAllocTrackerActivationThreshold`
 and :func:`~xml.parsers.expat.xmlparser.SetAllocTrackerMaximumAmplification`
-to :class:`~xml.parsers.expat.xmlparser` objects to prevent use of
+to :ref:`xmlparser <xmlparser-objects>` objects to prevent use of
 disproportional amounts of dynamic memory from within an Expat parser.
 Patch by Bénédikt Tran.