From 834a7e0e71d0c15c9e6f3e01b90d855536efc814 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 8 Oct 2025 20:05:34 +0200 Subject: [PATCH 1/6] Doc/library/pyexpat.rst: Recommend "hasattr" with Expat security methods This mimics existing method SetReparseDeferralEnabled. --- Doc/library/pyexpat.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index 9aae5c9da7471d..47364322c56852 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -262,6 +262,15 @@ against some common XML vulnerabilities. Activation thresholds below 4 MiB are known to break support for DITA 1.3 payload and are hence not recommended. + .. note:: + + :meth:`SetBillionLaughsAttackProtectionActivationThreshold` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`SetBillionLaughsAttackProtectionActivationThreshold` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. versionadded:: next .. method:: xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /) @@ -294,6 +303,15 @@ against some common XML vulnerabilities. that can be adjusted by :meth:`.SetBillionLaughsAttackProtectionActivationThreshold` is exceeded. + .. note:: + + :meth:`SetBillionLaughsAttackProtectionMaximumAmplification` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`SetBillionLaughsAttackProtectionMaximumAmplification` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. versionadded:: next .. method:: xmlparser.SetAllocTrackerActivationThreshold(threshold, /) @@ -309,6 +327,15 @@ against some common XML vulnerabilities. The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset` should not be used as they may have no special meaning. + .. note:: + + :meth:`SetAllocTrackerActivationThreshold` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`SetAllocTrackerActivationThreshold` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. versionadded:: next .. method:: xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /) @@ -340,6 +367,15 @@ against some common XML vulnerabilities. that can be adjusted by :meth:`.SetAllocTrackerActivationThreshold` is exceeded. + .. note:: + + :meth:`SetAllocTrackerMaximumAmplification` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`SetAllocTrackerMaximumAmplification` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. versionadded:: next From 828f786f265ab2fe1312b85d583a507a8afa9471 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 8 Oct 2025 20:05:46 +0200 Subject: [PATCH 2/6] Doc/library/pyexpat.rst: Use ".. note::" with SetReparseDeferralEnabled .. to make it consistent with the other four Expat security methods. --- Doc/library/pyexpat.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index 47364322c56852..2295b3dc1140e5 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -223,10 +223,14 @@ XMLParser Objects Calling ``SetReparseDeferralEnabled(True)`` allows re-enabling reparse deferral. - Note that :meth:`SetReparseDeferralEnabled` has been backported to some - prior releases of CPython as a security fix. Check for availability of - :meth:`SetReparseDeferralEnabled` using :func:`hasattr` if used in code - running across a variety of Python versions. + .. note:: + + :meth:`SetReparseDeferralEnabled` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`SetReparseDeferralEnabled` + using :func:`hasattr` if used in code running across a variety of Python + versions. .. versionadded:: 3.13 From c932512744613171fcbb98f48d54c72e7aecbf0f Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 8 Oct 2025 20:17:59 +0200 Subject: [PATCH 3/6] Doc/library/xml.etree.elementtree.rst: Use ".. note::" for backport notes .. to make it consistent with Doc/library/pyexpat.rst. --- Doc/library/xml.etree.elementtree.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 00075ac2a23e6b..952ab203c0472c 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1398,7 +1398,9 @@ XMLParser Objects Disabling reparse deferral has security consequences; please see :meth:`xml.parsers.expat.xmlparser.SetReparseDeferralEnabled` for details. - Note that :meth:`flush` has been backported to some prior releases of + .. note:: + + :meth:`flush` has been backported to some prior releases of CPython as a security fix. Check for availability of :meth:`flush` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -1476,7 +1478,9 @@ XMLPullParser Objects Disabling reparse deferral has security consequences; please see :meth:`xml.parsers.expat.xmlparser.SetReparseDeferralEnabled` for details. - Note that :meth:`flush` has been backported to some prior releases of + .. note:: + + :meth:`flush` has been backported to some prior releases of CPython as a security fix. Check for availability of :meth:`flush` using :func:`hasattr` if used in code running across a variety of Python versions. From 32d51e3e7c25e01f69336e4d6b076a08475ef130 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 8 Oct 2025 21:18:37 +0200 Subject: [PATCH 4/6] Doc/library/xml.etree.elementtree.rst: Add missing indent by 3 --- Doc/library/xml.etree.elementtree.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 952ab203c0472c..a15065690ab88f 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1400,10 +1400,12 @@ XMLParser Objects .. note:: - :meth:`flush` has been backported to some prior releases of - CPython as a security fix. Check for availability of :meth:`flush` - using :func:`hasattr` if used in code running across a variety of Python - versions. + :meth:`flush` + has been backported to some prior releases of CPython as a security + fix. Check for availability of + :meth:`flush` + using :func:`hasattr` if used in code running across a variety of + Python versions. .. versionadded:: 3.13 @@ -1480,10 +1482,12 @@ XMLPullParser Objects .. note:: - :meth:`flush` has been backported to some prior releases of - CPython as a security fix. Check for availability of :meth:`flush` - using :func:`hasattr` if used in code running across a variety of Python - versions. + :meth:`flush` + has been backported to some prior releases of CPython as a security + fix. Check for availability of + :meth:`flush` + using :func:`hasattr` if used in code running across a variety of + Python versions. .. versionadded:: 3.13 From 67b52216ec429f62735266603f4f5d7e8833feea Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Thu, 9 Oct 2025 15:34:41 +0200 Subject: [PATCH 5/6] Add an exclemation mark to suppress distracting links Related: https://devguide.python.org/documentation/style-guide/#links Idea by @picnixz --- Doc/library/pyexpat.rst | 20 ++++++++++---------- Doc/library/xml.etree.elementtree.rst | 8 ++++---- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index 2295b3dc1140e5..466417056d52d6 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -225,10 +225,10 @@ XMLParser Objects .. note:: - :meth:`SetReparseDeferralEnabled` + :meth:`!SetReparseDeferralEnabled` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`SetReparseDeferralEnabled` + :meth:`!SetReparseDeferralEnabled` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -268,10 +268,10 @@ against some common XML vulnerabilities. .. note:: - :meth:`SetBillionLaughsAttackProtectionActivationThreshold` + :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`SetBillionLaughsAttackProtectionActivationThreshold` + :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -309,10 +309,10 @@ against some common XML vulnerabilities. .. note:: - :meth:`SetBillionLaughsAttackProtectionMaximumAmplification` + :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`SetBillionLaughsAttackProtectionMaximumAmplification` + :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -333,10 +333,10 @@ against some common XML vulnerabilities. .. note:: - :meth:`SetAllocTrackerActivationThreshold` + :meth:`!SetAllocTrackerActivationThreshold` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`SetAllocTrackerActivationThreshold` + :meth:`!SetAllocTrackerActivationThreshold` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -373,10 +373,10 @@ against some common XML vulnerabilities. .. note:: - :meth:`SetAllocTrackerMaximumAmplification` + :meth:`!SetAllocTrackerMaximumAmplification` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`SetAllocTrackerMaximumAmplification` + :meth:`!SetAllocTrackerMaximumAmplification` using :func:`hasattr` if used in code running across a variety of Python versions. diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index a15065690ab88f..e4d3f508f4dbf0 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1400,10 +1400,10 @@ XMLParser Objects .. note:: - :meth:`flush` + :meth:`!flush` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`flush` + :meth:`!flush` using :func:`hasattr` if used in code running across a variety of Python versions. @@ -1482,10 +1482,10 @@ XMLPullParser Objects .. note:: - :meth:`flush` + :meth:`!flush` has been backported to some prior releases of CPython as a security fix. Check for availability of - :meth:`flush` + :meth:`!flush` using :func:`hasattr` if used in code running across a variety of Python versions. From 50144239cabbdeaeaa41f142916b7f09d0216b21 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Fri, 10 Oct 2025 00:03:55 +0200 Subject: [PATCH 6/6] Demo more quiet version without ".. note::" --- Doc/library/pyexpat.rst | 75 ++++++++++++--------------- Doc/library/xml.etree.elementtree.rst | 28 +++++----- 2 files changed, 45 insertions(+), 58 deletions(-) diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index 466417056d52d6..50760a17603f22 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -223,14 +223,12 @@ XMLParser Objects Calling ``SetReparseDeferralEnabled(True)`` allows re-enabling reparse deferral. - .. note:: - - :meth:`!SetReparseDeferralEnabled` - has been backported to some prior releases of CPython as a security fix. - Check for availability of - :meth:`!SetReparseDeferralEnabled` - using :func:`hasattr` if used in code running across a variety of Python - versions. + Note that :meth:`!SetReparseDeferralEnabled` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!SetReparseDeferralEnabled` + using :func:`hasattr` if used in code running across a variety of Python + versions. .. versionadded:: 3.13 @@ -261,19 +259,18 @@ against some common XML vulnerabilities. The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset` should not be used as they may have no special meaning. + Note that :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. note:: Activation thresholds below 4 MiB are known to break support for DITA 1.3 payload and are hence not recommended. - .. note:: - - :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` - has been backported to some prior releases of CPython as a security fix. - Check for availability of - :meth:`!SetBillionLaughsAttackProtectionActivationThreshold` - using :func:`hasattr` if used in code running across a variety of Python - versions. .. versionadded:: next @@ -301,21 +298,19 @@ against some common XML vulnerabilities. The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset` should not be used as they may have no special meaning. + Note that :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. note:: The maximum amplification factor is only considered if the threshold that can be adjusted by :meth:`.SetBillionLaughsAttackProtectionActivationThreshold` is exceeded. - .. note:: - - :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` - has been backported to some prior releases of CPython as a security fix. - Check for availability of - :meth:`!SetBillionLaughsAttackProtectionMaximumAmplification` - using :func:`hasattr` if used in code running across a variety of Python - versions. - .. versionadded:: next .. method:: xmlparser.SetAllocTrackerActivationThreshold(threshold, /) @@ -331,14 +326,12 @@ against some common XML vulnerabilities. The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset` should not be used as they may have no special meaning. - .. note:: - - :meth:`!SetAllocTrackerActivationThreshold` - has been backported to some prior releases of CPython as a security fix. - Check for availability of - :meth:`!SetAllocTrackerActivationThreshold` - using :func:`hasattr` if used in code running across a variety of Python - versions. + Note that :meth:`!SetAllocTrackerActivationThreshold` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!SetAllocTrackerActivationThreshold` + using :func:`hasattr` if used in code running across a variety of Python + versions. .. versionadded:: next @@ -365,21 +358,19 @@ against some common XML vulnerabilities. The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset` should not be used as they may have no special meaning. + Note that :meth:`!SetAllocTrackerMaximumAmplification` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!SetAllocTrackerMaximumAmplification` + using :func:`hasattr` if used in code running across a variety of Python + versions. + .. note:: The maximum amplification factor is only considered if the threshold that can be adjusted by :meth:`.SetAllocTrackerActivationThreshold` is exceeded. - .. note:: - - :meth:`!SetAllocTrackerMaximumAmplification` - has been backported to some prior releases of CPython as a security fix. - Check for availability of - :meth:`!SetAllocTrackerMaximumAmplification` - using :func:`hasattr` if used in code running across a variety of Python - versions. - .. versionadded:: next diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index e4d3f508f4dbf0..5bdfac58ef8ab3 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1398,14 +1398,12 @@ XMLParser Objects Disabling reparse deferral has security consequences; please see :meth:`xml.parsers.expat.xmlparser.SetReparseDeferralEnabled` for details. - .. note:: - - :meth:`!flush` - has been backported to some prior releases of CPython as a security - fix. Check for availability of - :meth:`!flush` - using :func:`hasattr` if used in code running across a variety of - Python versions. + Note that :meth:`!flush` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!flush` + using :func:`hasattr` if used in code running across a variety of Python + versions. .. versionadded:: 3.13 @@ -1480,14 +1478,12 @@ XMLPullParser Objects Disabling reparse deferral has security consequences; please see :meth:`xml.parsers.expat.xmlparser.SetReparseDeferralEnabled` for details. - .. note:: - - :meth:`!flush` - has been backported to some prior releases of CPython as a security - fix. Check for availability of - :meth:`!flush` - using :func:`hasattr` if used in code running across a variety of - Python versions. + Note that :meth:`!flush` + has been backported to some prior releases of CPython as a security fix. + Check for availability of + :meth:`!flush` + using :func:`hasattr` if used in code running across a variety of Python + versions. .. versionadded:: 3.13