GH-121970: Remove Docutils list monkeypatch #142056

AA-Turner · 2025-11-29T00:10:04Z

Also xref:

HTML diff:

Index: Doc/build/html/library/decimal.html
===================================================================
diff --git a/Doc/build/html/library/decimal.html b/Doc/build/html/library/decimal.html
--- a/Doc/build/html/library/decimal.html	(revision 7a9fa14a69c89318caeabcada59cffe72f5815cb)
+++ b/Doc/build/html/library/decimal.html	(revision 7d5ef821bfebcedeb532dcf2b2e27fcf45220aaf)
@@ -2438,18 +2438,18 @@
 </section>
 <section id="decimal-faq">
 <span id="id1"></span><h2>Decimal FAQ<a class="headerlink" href="#decimal-faq" title="Link to this heading">¶</a></h2>
-<p>Q. It is cumbersome to type <code class="docutils literal notranslate"><span class="pre">decimal.Decimal('1234.5')</span></code>.  Is there a way to
+<p>Q: It is cumbersome to type <code class="docutils literal notranslate"><span class="pre">decimal.Decimal('1234.5')</span></code>.  Is there a way to
 minimize typing when using the interactive interpreter?</p>
-<p>A. Some users abbreviate the constructor to just a single letter:</p>
+<p>A: Some users abbreviate the constructor to just a single letter:</p>
 <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">D</span> <span class="o">=</span> <span class="n">decimal</span><span class="o">.</span><span class="n">Decimal</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">D</span><span class="p">(</span><span class="s1">&#39;1.23&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="n">D</span><span class="p">(</span><span class="s1">&#39;3.45&#39;</span><span class="p">)</span>
 <span class="go">Decimal(&#39;4.68&#39;)</span>
 </pre></div>
 </div>
-<p>Q. In a fixed-point application with two decimal places, some inputs have many
+<p>Q: In a fixed-point application with two decimal places, some inputs have many
 places and need to be rounded.  Others are not supposed to have excess digits
 and need to be validated.  What methods should be used?</p>
-<p>A. The <a class="reference internal" href="#decimal.Decimal.quantize" title="decimal.Decimal.quantize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code></a> method rounds to a fixed number of decimal places. If
+<p>A: The <a class="reference internal" href="#decimal.Decimal.quantize" title="decimal.Decimal.quantize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code></a> method rounds to a fixed number of decimal places. If
 the <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> trap is set, it is also useful for validation:</p>
 <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">TWOPLACES</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="o">**</span> <span class="o">-</span><span class="mi">2</span>       <span class="c1"># same as Decimal(&#39;0.01&#39;)</span>
 </pre></div>
@@ -2470,9 +2470,9 @@
 <span class="gr">Inexact</span>: <span class="n">None</span>
 </pre></div>
 </div>
-<p>Q. Once I have valid two place inputs, how do I maintain that invariant
+<p>Q: Once I have valid two place inputs, how do I maintain that invariant
 throughout an application?</p>
-<p>A. Some operations like addition, subtraction, and multiplication by an integer
+<p>A: Some operations like addition, subtraction, and multiplication by an integer
 will automatically preserve fixed point.  Others operations, like division and
 non-integer multiplication, will change the number of decimal places and need to
 be followed-up with a <a class="reference internal" href="#decimal.Decimal.quantize" title="decimal.Decimal.quantize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code></a> step:</p>
@@ -2505,19 +2505,19 @@
 <span class="go">Decimal(&#39;0.03&#39;)</span>
 </pre></div>
 </div>
-<p>Q. There are many ways to express the same value.  The numbers <code class="docutils literal notranslate"><span class="pre">200</span></code>,
+<p>Q: There are many ways to express the same value.  The numbers <code class="docutils literal notranslate"><span class="pre">200</span></code>,
 <code class="docutils literal notranslate"><span class="pre">200.000</span></code>, <code class="docutils literal notranslate"><span class="pre">2E2</span></code>, and <code class="docutils literal notranslate"><span class="pre">.02E+4</span></code> all have the same value at
 various precisions. Is there a way to transform them to a single recognizable
 canonical value?</p>
-<p>A. The <a class="reference internal" href="#decimal.Decimal.normalize" title="decimal.Decimal.normalize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">normalize()</span></code></a> method maps all equivalent values to a single
+<p>A: The <a class="reference internal" href="#decimal.Decimal.normalize" title="decimal.Decimal.normalize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">normalize()</span></code></a> method maps all equivalent values to a single
 representative:</p>
 <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">values</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="n">Decimal</span><span class="p">,</span> <span class="s1">&#39;200 200.000 2E2 .02E+4&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">v</span><span class="o">.</span><span class="n">normalize</span><span class="p">()</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
 <span class="go">[Decimal(&#39;2E+2&#39;), Decimal(&#39;2E+2&#39;), Decimal(&#39;2E+2&#39;), Decimal(&#39;2E+2&#39;)]</span>
 </pre></div>
 </div>
-<p>Q. When does rounding occur in a computation?</p>
-<p>A. It occurs <em>after</em> the computation.  The philosophy of the decimal
+<p>Q: When does rounding occur in a computation?</p>
+<p>A: It occurs <em>after</em> the computation.  The philosophy of the decimal
 specification is that numbers are considered exact and are created
 independent of the current context.  They can even have greater
 precision than current context.  Computations process with those
@@ -2535,9 +2535,9 @@
 <span class="go">Decimal(&#39;3.1416&#39;)</span>
 </pre></div>
 </div>
-<p>Q. Some decimal values always print with exponential notation.  Is there a way
+<p>Q: Some decimal values always print with exponential notation.  Is there a way
 to get a non-exponential representation?</p>
-<p>A. For some values, exponential notation is the only way to express the number
+<p>A: For some values, exponential notation is the only way to express the number
 of significant places in the coefficient.  For example, expressing
 <code class="docutils literal notranslate"><span class="pre">5.0E+3</span></code> as <code class="docutils literal notranslate"><span class="pre">5000</span></code> keeps the value constant but cannot show the
 original’s two-place significance.</p>
@@ -2552,24 +2552,24 @@
 <span class="go">Decimal(&#39;5000&#39;)</span>
 </pre></div>
 </div>
-<p>Q. Is there a way to convert a regular float to a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>?</p>
-<p>A. Yes, any binary floating-point number can be exactly expressed as a
+<p>Q: Is there a way to convert a regular float to a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>?</p>
+<p>A: Yes, any binary floating-point number can be exactly expressed as a
 Decimal though an exact conversion may take more precision than intuition would
 suggest:</p>
 <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
 <span class="go">Decimal(&#39;3.141592653589793115997963468544185161590576171875&#39;)</span>
 </pre></div>
 </div>
-<p>Q. Within a complex calculation, how can I make sure that I haven’t gotten a
+<p>Q: Within a complex calculation, how can I make sure that I haven’t gotten a
 spurious result because of insufficient precision or rounding anomalies.</p>
-<p>A. The decimal module makes it easy to test results.  A best practice is to
+<p>A: The decimal module makes it easy to test results.  A best practice is to
 re-run calculations using greater precision and with various rounding modes.
 Widely differing results indicate insufficient precision, rounding mode issues,
 ill-conditioned inputs, or a numerically unstable algorithm.</p>
-<p>Q. I noticed that context precision is applied to the results of operations but
+<p>Q: I noticed that context precision is applied to the results of operations but
 not to the inputs.  Is there anything to watch out for when mixing values of
 different precisions?</p>
-<p>A. Yes.  The principle is that all values are considered to be exact and so is
+<p>A: Yes.  The principle is that all values are considered to be exact and so is
 the arithmetic on those values.  Only the results are rounded.  The advantage
 for inputs is that “what you type is what you get”.  A disadvantage is that the
 results can look odd if you forget that the inputs haven’t been rounded:</p>
@@ -2593,8 +2593,8 @@
 <span class="go">Decimal(&#39;1.2345&#39;)</span>
 </pre></div>
 </div>
-<p>Q. Is the CPython implementation fast for large numbers?</p>
-<p>A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
+<p>Q: Is the CPython implementation fast for large numbers?</p>
+<p>A: Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
 the decimal module integrate the high speed <a class="reference external" href="https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html">libmpdec</a> library for
 arbitrary precision correctly rounded decimal floating-point arithmetic <a class="footnote-reference brackets" href="#id4" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>.
 <code class="docutils literal notranslate"><span class="pre">libmpdec</span></code> uses <a class="reference external" href="https://en.wikipedia.org/wiki/Karatsuba_algorithm">Karatsuba multiplication</a>
Index: Doc/build/html/library/ssl.html
===================================================================
diff --git a/Doc/build/html/library/ssl.html b/Doc/build/html/library/ssl.html
--- a/Doc/build/html/library/ssl.html	(revision 7a9fa14a69c89318caeabcada59cffe72f5815cb)
+++ b/Doc/build/html/library/ssl.html	(revision 7d5ef821bfebcedeb532dcf2b2e27fcf45220aaf)
@@ -3545,13 +3545,13 @@
 </dd>
 <dt><span class="target" id="index-20"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1422.html"><strong>RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management</strong></a></dt><dd><p>Steve Kent</p>
 </dd>
-<dt><span class="target" id="index-21"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc4086.html"><strong>RFC 4086: Randomness Requirements for Security</strong></a></dt><dd><p>Donald E., Jeffrey I. Schiller</p>
+<dt><span class="target" id="index-21"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc4086.html"><strong>RFC 4086: Randomness Requirements for Security</strong></a></dt><dd><p>Donald E. Eastlake, Jeffrey I. Schiller, Steve Crocker</p>
 </dd>
-<dt><span class="target" id="index-22"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5280.html"><strong>RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile</strong></a></dt><dd><p>D. Cooper</p>
+<dt><span class="target" id="index-22"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5280.html"><strong>RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile</strong></a></dt><dd><p>David Cooper et al.</p>
 </dd>
-<dt><span class="target" id="index-23"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5246.html"><strong>RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2</strong></a></dt><dd><p>T. Dierks et. al.</p>
+<dt><span class="target" id="index-23"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5246.html"><strong>RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2</strong></a></dt><dd><p>Tim Dierks and Eric Rescorla.</p>
 </dd>
-<dt><span class="target" id="index-24"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6066.html"><strong>RFC 6066: Transport Layer Security (TLS) Extensions</strong></a></dt><dd><p>D. Eastlake</p>
+<dt><span class="target" id="index-24"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6066.html"><strong>RFC 6066: Transport Layer Security (TLS) Extensions</strong></a></dt><dd><p>Donald E. Eastlake</p>
 </dd>
 <dt><a class="reference external" href="https://www.iana.org/assignments/tls-parameters/tls-parameters.xml">IANA TLS: Transport Layer Security (TLS) Parameters</a></dt><dd><p>IANA</p>
 </dd>
Index: Doc/build/html/reference/compound_stmts.html
===================================================================
diff --git a/Doc/build/html/reference/compound_stmts.html b/Doc/build/html/reference/compound_stmts.html
--- a/Doc/build/html/reference/compound_stmts.html	(revision 7a9fa14a69c89318caeabcada59cffe72f5815cb)
+++ b/Doc/build/html/reference/compound_stmts.html	(revision 7d5ef821bfebcedeb532dcf2b2e27fcf45220aaf)
@@ -1104,9 +1104,9 @@
 keyword patterns also work as for other types.</p>
 <p>If only keyword patterns are present, they are processed as follows,
 one by one:</p>
-<p>I. The keyword is looked up as an attribute on the subject.</p>
-<blockquote>
-<div><ul class="simple">
+<ol class="upperroman simple">
+<li><p>The keyword is looked up as an attribute on the subject.</p>
+<ul class="simple">
 <li><p>If this raises an exception other than <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>, the
 exception bubbles up.</p></li>
 <li><p>If this raises <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>, the class pattern has failed.</p></li>
@@ -1114,14 +1114,15 @@
 against the subject’s attribute value.  If this fails, the class
 pattern fails; if this succeeds, the match proceeds to the next keyword.</p></li>
 </ul>
-</div></blockquote>
-<p>II. If all keyword patterns succeed, the class pattern succeeds.</p>
+</li>
+<li><p>If all keyword patterns succeed, the class pattern succeeds.</p></li>
+</ol>
 <p>If any positional patterns are present, they are converted to keyword
 patterns using the <a class="reference internal" href="datamodel.html#object.__match_args__" title="object.__match_args__"><code class="xref py py-data docutils literal notranslate"><span class="pre">__match_args__</span></code></a> attribute on the class
 <code class="docutils literal notranslate"><span class="pre">name_or_attr</span></code> before matching:</p>
-<p>I. The equivalent of <code class="docutils literal notranslate"><span class="pre">getattr(cls,</span> <span class="pre">&quot;__match_args__&quot;,</span> <span class="pre">())</span></code> is called.</p>
-<blockquote>
-<div><ul class="simple">
+<ol class="upperroman">
+<li><p>The equivalent of <code class="docutils literal notranslate"><span class="pre">getattr(cls,</span> <span class="pre">&quot;__match_args__&quot;,</span> <span class="pre">())</span></code> is called.</p>
+<ul class="simple">
 <li><p>If this raises an exception, the exception bubbles up.</p></li>
 <li><p>If the returned value is not a tuple, the conversion fails and
 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p></li>
@@ -1136,11 +1137,10 @@
 <p class="admonition-title">See also</p>
 <p><a class="reference internal" href="datamodel.html#class-pattern-matching"><span class="std std-ref">Customizing positional arguments in class pattern matching</span></a></p>
 </div>
-</div></blockquote>
-<dl class="simple">
-<dt>II. Once all positional patterns have been converted to keyword patterns,</dt><dd><p>the match proceeds as if there were only keyword patterns.</p>
-</dd>
-</dl>
+</li>
+<li><p>Once all positional patterns have been converted to keyword patterns,
+the match proceeds as if there were only keyword patterns.</p></li>
+</ol>
 <p>For the following built-in types the handling of positional subpatterns is
 different:</p>
 <ul class="simple">

A

Issue: Improve and reorganise pyspecific #121970

📚 Documentation preview 📚: https://cpython-previews--142056.org.readthedocs.build/en/142056/

AA-Turner · 2025-11-29T00:12:47Z

We now only have escaping in two places -- for AMK and R. David Murray. These are both needed as single-line paragraphs.

A

picnixz · 2025-11-29T00:15:30Z

Didn't we already have #140031?

AA-Turner · 2025-11-29T00:22:51Z

Didn't we already have #140031?

@picnixz this is a more focussed change, but also IMO resolves the underlying problem -- most cases actually don't need escaping, and as seen with the compound statements change, it actually renders better with the monkeypatch removed.

A

miss-islington-app · 2025-11-29T14:28:27Z

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

(cherry picked from commit 3c11738) Co-authored-by: Adam Turner <[email protected]>

bedevere-app · 2025-11-29T14:28:42Z

GH-142088 is a backport of this pull request to the 3.14 branch.

(cherry picked from commit 3c11738) Co-authored-by: Adam Turner <[email protected]>

bedevere-app · 2025-11-29T14:28:46Z

GH-142089 is a backport of this pull request to the 3.13 branch.

Remove Docutils list monkeypatch

e7abe7d

AA-Turner requested a review from gpshead as a code owner November 29, 2025 00:10

AA-Turner added the docs Documentation in the Doc dir label Nov 29, 2025

AA-Turner requested review from hugovk and picnixz as code owners November 29, 2025 00:10

AA-Turner added the needs backport to 3.13 bugs and security fixes label Nov 29, 2025

github-project-automation bot added this to Docs PRs Nov 29, 2025

AA-Turner added the needs backport to 3.14 bugs and security fixes label Nov 29, 2025

github-project-automation bot moved this to Todo in Docs PRs Nov 29, 2025

bedevere-app bot added the awaiting core review label Nov 29, 2025

bedevere-app bot mentioned this pull request Nov 29, 2025

Improve and reorganise pyspecific #121970

Open

AA-Turner added the skip news label Nov 29, 2025

gpshead approved these changes Nov 29, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Nov 29, 2025

hugovk mentioned this pull request Nov 29, 2025

gh-139257: escape enumerator-like letters to support docutils 0.22 #140031

Closed

hugovk approved these changes Nov 29, 2025

View reviewed changes

AA-Turner merged commit 3c11738 into python:main Nov 29, 2025
43 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Nov 29, 2025

bedevere-app bot removed the awaiting merge label Nov 29, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 29, 2025

pythonGH-121970: Remove Docutils list monkeypatch (pythonGH-142056)

095e565

(cherry picked from commit 3c11738) Co-authored-by: Adam Turner <[email protected]>

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Nov 29, 2025

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 29, 2025

pythonGH-121970: Remove Docutils list monkeypatch (pythonGH-142056)

941f675

(cherry picked from commit 3c11738) Co-authored-by: Adam Turner <[email protected]>

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Nov 29, 2025

picnixz mentioned this pull request Nov 29, 2025

GH-139257 Use an explicitly named link #142090

Closed

AA-Turner pushed a commit that referenced this pull request Nov 29, 2025

[3.14] GH-121970: Remove Docutils list monkeypatch (GH-142056) (#142088)

612213c

AA-Turner pushed a commit that referenced this pull request Nov 29, 2025

[3.13] GH-121970: Remove Docutils list monkeypatch (GH-142056) (#142089)

342c9e0

StanFromIreland pushed a commit to StanFromIreland/cpython that referenced this pull request Dec 6, 2025

pythonGH-121970: Remove Docutils list monkeypatch (python#142056)

aea747e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

GH-121970: Remove Docutils list monkeypatch #142056

GH-121970: Remove Docutils list monkeypatch #142056

AA-Turner commented Nov 29, 2025 •

edited

Loading

Uh oh!

AA-Turner commented Nov 29, 2025

Uh oh!

picnixz commented Nov 29, 2025

Uh oh!

AA-Turner commented Nov 29, 2025

Uh oh!

Uh oh!

miss-islington-app bot commented Nov 29, 2025

Uh oh!

bedevere-app bot commented Nov 29, 2025

Uh oh!

bedevere-app bot commented Nov 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

GH-121970: Remove Docutils list monkeypatch #142056

GH-121970: Remove Docutils list monkeypatch #142056

Conversation

AA-Turner commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AA-Turner commented Nov 29, 2025

Uh oh!

picnixz commented Nov 29, 2025

Uh oh!

AA-Turner commented Nov 29, 2025

Uh oh!

Uh oh!

miss-islington-app bot commented Nov 29, 2025

Uh oh!

bedevere-app bot commented Nov 29, 2025

Uh oh!

bedevere-app bot commented Nov 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AA-Turner commented Nov 29, 2025 •

edited

Loading