@@ -72,6 +72,13 @@ The :mod:`xml.parsers.expat` module contains two functions:
7272 *encoding * [1 ]_ is given it will override the implicit or explicit encoding of the
7373 document.
7474
75+ .. _xmlparser-non-root :
76+
77+ Parsers created through:func: `!ParserCreate ` are called "root" parsers,
78+ in the sense that they do not have any parent parser attached. Non-root
79+ parsers are created by:meth: `parser.ExternalEntityParserCreate
80+ <xmlparser.ExternalEntityParserCreate> `.
81+
7582 Expat can optionally do XML namespace processing for you, enabled by providing a
7683 value for *namespace_separator *. The value must be a one-character string; a
7784:exc: `ValueError ` will be raised if the string has an illegal length (``None ``
@@ -231,6 +238,55 @@ XMLParser Objects
231238 ..versionadded ::3.13
232239
233240
241+ :class: `!xmlparser ` objects have the following methods to mitigate some
242+ common XML vulnerabilities.
243+
244+ ..method ::xmlparser.SetAllocTrackerActivationThreshold(threshold, /)
245+
246+ Sets the number of allocated bytes of dynamic memory needed to activate
247+ protection against disproportionate use of RAM.
248+
249+ By default, parser objects have an allocation activation threshold of 64 MiB,
250+ or equivalently 67,108,864 bytes.
251+
252+ An:exc: `ExpatError ` is raised if this method is called on a
253+ |xml-non-root-parser | parser.
254+ The corresponding:attr: `~ExpatError.lineno ` and:attr: `~ExpatError.offset `
255+ should not be used as they may have no special meaning.
256+
257+ ..versionadded ::next
258+
259+ ..method ::xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)
260+
261+ Sets the maximum amplification factor between direct input and bytes
262+ of dynamic memory allocated.
263+
264+ The amplification factor is calculated as ``allocated / direct ``
265+ while parsing, where ``direct `` is the number of bytes read from
266+ the primary document in parsing and ``allocated `` is the number
267+ of bytes of dynamic memory allocated in the parser hierarchy.
268+
269+ The *max_factor * value must be a non-NaN:class: `float ` value greater than
270+ or equal to 1.0. Amplification factors greater than 100.0 can be observed
271+ near the start of parsing even with benign files in practice. In particular,
272+ the activation threshold should be carefully chosen to avoid false positives.
273+
274+ By default, parser objects have a maximum amplification factor of 100.0.
275+
276+ An:exc: `ExpatError ` is raised if this method is called on a
277+ |xml-non-root-parser | parser or if *max_factor * is outside the valid range.
278+ The corresponding:attr: `~ExpatError.lineno ` and:attr: `~ExpatError.offset `
279+ should not be used as they may have no special meaning.
280+
281+ ..note ::
282+
283+ The maximum amplification factor is only considered if the threshold
284+ that can be adjusted by:meth: `.SetAllocTrackerActivationThreshold `
285+ is exceeded.
286+
287+ ..versionadded ::next
288+
289+
234290:class: `xmlparser ` objects have the following attributes:
235291
236292
@@ -954,3 +1010,4 @@ The ``errors`` module has the following attributes:
9541010 not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
9551011 and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
9561012
1013+ xml-non-root-parser |replace :::ref: `non-root <xmlparser-non-root >`