CINXE.COM
PEP 387 (Backwards Compatibility Policy) updates/clarifications - PEPs - Discussions on Python.org
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>PEP 387 (Backwards Compatibility Policy) updates/clarifications - PEPs - Discussions on Python.org</title> <meta name="description" content="Hello, I’d like to propose the following changes to our backwards compatibility policy. I see them as clarifications and/or codifying the status quo, but, you might disagree. Thank you to other members of the 2022 Stee&hellip;"> <meta name="generator" content="Discourse 3.4.0.beta3-dev - https://github.com/discourse/discourse version 5bf5d1335680f28a8eb65c488353be9585eed08e"> <link rel="icon" type="image/png" href="https://global.discourse-cdn.com/flex016/uploads/python1/optimized/1X/9997f0605d56c4bfecd63594f52f42cdafd6b06a_2_32x32.png"> <link rel="apple-touch-icon" type="image/png" href="https://global.discourse-cdn.com/flex016/uploads/python1/optimized/1X/4c06143de7870c35963b818b15b395092a434991_2_180x180.png"> <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff"> <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#111111"> <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, user-scalable=yes, viewport-fit=cover"> <link rel="canonical" href="https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042" /> <link rel="search" type="application/opensearchdescription+xml" href="https://discuss.python.org/opensearch.xml" title="Discussions on Python.org Search"> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/color_definitions_base__2_89bb3b818d8860c6da830055d8964bc4f806db7f.css?__ws=discuss.python.org" media="all" rel="stylesheet" class="light-scheme"/><link href="https://sea2.discourse-cdn.com/flex016/stylesheets/color_definitions_dark_1_2_0ef303cf72b1435fdf680c3db5c67cce60860418.css?__ws=discuss.python.org" media="(prefers-color-scheme: dark)" rel="stylesheet" class="dark-scheme"/> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/desktop_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="desktop" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/checklist_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="checklist" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-adplugin_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-adplugin" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-akismet_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-akismet" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-cakeday_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-cakeday" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-chat-integration_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-chat-integration" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-details_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-details" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-lazy-videos_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-lazy-videos" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-local-dates_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-local-dates" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-math_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-math" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-narrative-bot_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-narrative-bot" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-policy_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-policy" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-presence_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-presence" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-solved_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-solved" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-templates_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-templates" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-topic-voting_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-topic-voting" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-user-notes_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-user-notes" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-yearly-review_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-yearly-review" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/footnote_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="footnote" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/hosted-site_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="hosted-site" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/poll_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="poll" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/spoiler-alert_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="spoiler-alert" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/discourse-topic-voting_desktop_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="discourse-topic-voting_desktop" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/poll_desktop_ae2c05eb022973cfd87e169e0799a6bd34290cdc.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="poll_desktop" /> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/desktop_theme_4_93427783b0a70199f2e06d65a8eb2ca5c365dbcd.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="desktop_theme" data-theme-id="4" data-theme-name="unformatted code detector"/> <link href="https://sea2.discourse-cdn.com/flex016/stylesheets/desktop_theme_2_5372499f761ae877fe1ed2c103226d632862786d.css?__ws=discuss.python.org" media="all" rel="stylesheet" data-target="desktop_theme" data-theme-id="2" data-theme-name="light"/> <link rel="alternate nofollow" type="application/rss+xml" title="RSS feed of 'PEP 387 (Backwards Compatibility Policy) updates/clarifications'" href="https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042.rss" /> <meta property="og:site_name" content="Discussions on Python.org" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary" /> <meta name="twitter:image" content="https://global.discourse-cdn.com/flex016/uploads/python1/original/1X/f93ff97c4f381b5e8add5a0c163b4ded29f20ed7.png" /> <meta property="og:image" content="https://global.discourse-cdn.com/flex016/uploads/python1/original/1X/f93ff97c4f381b5e8add5a0c163b4ded29f20ed7.png" /> <meta property="og:url" content="https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042" /> <meta name="twitter:url" content="https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042" /> <meta property="og:title" content="PEP 387 (Backwards Compatibility Policy) updates/clarifications" /> <meta name="twitter:title" content="PEP 387 (Backwards Compatibility Policy) updates/clarifications" /> <meta property="og:description" content="Hello, I’d like to propose the following changes to our backwards compatibility policy. I see them as clarifications and/or codifying the status quo, but, you might disagree. Thank you to other members of the 2022 Steering Council for lots of discussion on this. The remaining bad ideas are mine. I sent this as a draft PR, see there for the current version. The initial proposal, with more rationale, is below: Explicit policy for undocumented things - Anything documented publicly as being p..." /> <meta name="twitter:description" content="Hello, I’d like to propose the following changes to our backwards compatibility policy. I see them as clarifications and/or codifying the status quo, but, you might disagree. Thank you to other members of the 2022 Steering Council for lots of discussion on this. The remaining bad ideas are mine. I sent this as a draft PR, see there for the current version. The initial proposal, with more rationale, is below: Explicit policy for undocumented things - Anything documented publicly as being p..." /> <meta property="og:article:section" content="PEPs" /> <meta property="og:article:section:color" content="0088CC" /> <meta name="twitter:label1" value="Reading time" /> <meta name="twitter:data1" value="1 mins 🕑" /> <meta name="twitter:label2" value="Likes" /> <meta name="twitter:data2" value="21 ❤" /> <meta property="article:published_time" content="2022-12-19T16:38:22+00:00" /> <meta property="og:ignore_canonical" content="true" /> </head> <body class="crawler browser-update"> <header> <a href="/"> Discussions on Python.org </a> </header> <div id="main-outlet" class="wrap" role="main"> <div id="topic-title"> <h1> <a href="/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042">PEP 387 (Backwards Compatibility Policy) updates/clarifications</a> </h1> <div class="topic-category" itemscope itemtype="http://schema.org/BreadcrumbList"> <span itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"> <a href="/c/peps/19" class="badge-wrapper bullet" itemprop="item"> <span class='badge-category-bg' style='background-color: #0088CC'></span> <span class='badge-category clear-badge'> <span class='category-name' itemprop='name'>PEPs</span> </span> </a> <meta itemprop="position" content="1" /> </span> </div> </div> <div itemscope itemtype='http://schema.org/DiscussionForumPosting'> <meta itemprop='headline' content='PEP 387 (Backwards Compatibility Policy) updates/clarifications'> <link itemprop='url' href='https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042'> <meta itemprop='datePublished' content='2022-12-19T16:38:22Z'> <meta itemprop='articleSection' content='PEPs'> <meta itemprop='keywords' content=''> <div itemprop='publisher' itemscope itemtype="http://schema.org/Organization"> <meta itemprop='name' content='Python Software Foundation'> <div itemprop='logo' itemscope itemtype="http://schema.org/ImageObject"> <meta itemprop='url' content='https://global.discourse-cdn.com/flex016/uploads/python1/original/1X/c7591c98caf3b31d4d9c6f322f41ed9d80a50800.png'> </div> </div> <div id='post_1' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/encukou'><span itemprop='name'>encukou</span></a> (Petr Viktorin) </span> <link itemprop="mainEntityOfPage" href="https://discuss.python.org/t/pep-387-backwards-compatibility-policy-updates-clarifications/22042"> <span class="crawler-post-infos"> <time datetime='2022-12-19T16:38:22Z' class='post-time'> December 19, 2022, 4:38pm </time> <meta itemprop='dateModified' content='2022-12-20T00:40:02Z'> <span itemprop='position'>1</span> </span> </div> <div class='post' itemprop='text'> <p>Hello,<br> I’d like to propose the following changes to our backwards compatibility policy. I see them as clarifications and/or codifying the status quo, but, you might disagree.</p> <p>Thank you to other members of the 2022 Steering Council for lots of discussion on this. The remaining <em>bad</em> ideas are mine.</p> <p>I sent this as a <a href="https://github.com/python/peps/pull/2931">draft PR</a>, see there for the current version.<br> The initial proposal, with more rationale, is below:</p> <h2> <a name="explicit-policy-for-undocumented-things-1" class="anchor" href="#explicit-policy-for-undocumented-things-1"></a>Explicit policy for undocumented things</h2> <pre><code class="lang-diff"> - Anything documented publicly as being private. + Note that if something is not documented at all, it is *not* + automatically considered private. </code></pre> <p>Our documentation doesn’t cover everything. When it’s lacking, people reach for the source code or other sources, from StackOverflow to blogs. I’m all for better stability expectation management, but for existing stuff (which might be decades old), by default we should assume that someone uses it.</p> <h2> <a name="examples-for-extended-deprecation-period-2" class="anchor" href="#examples-for-extended-deprecation-period-2"></a>Examples for extended deprecation period</h2> <pre><code class="lang-diff">- It's fine to wait more than two releases. + + It's fine to wait more than two releases, for example: + + - If the expected maintenance overhead and security risk of the + deprecated behavior is small (e.g. an old function is reimplemented + in terms of a new, more general one), it can stay indefinitely + (or until the situation changes). + + - If the deprecated feature is replaced by a new one, it should + generally be removed only after the last Python version + *without* the new feature reaches end of support. </code></pre> <p>It was too easy to misread the PEP as saying that Python deprecation periods are “two releases”, or “two releases by default”. Rather, I see the two releases as the <em>minimum</em>, a line that needs a project-wide decision to cross. (The project-wide decision is implemented/approximated as a SC ruling.)</p> <h2> <a name="py_deprecated-3" class="anchor" href="#py_deprecated-3"></a>Py_DEPRECATED</h2> <pre><code class="lang-diff">- [...] Compiler warnings are also acceptable. [...] + For C API, a compiler warning generated by the ``Py_DEPRECATED`` macro + is also acceptable. </code></pre> <p>The <code>Py_DEPRECATED</code> macro doesn’t contain the info a deprecation is supposed to have (“the release the incompatibility is expected to become the default and a link to an issue that users can post feedback to.”) It also relies on compiler extensions, so users with less common compilers won’t see it.<br> Ideally that should all be fixed in <code>Py_DEPRECATED</code> some day, but in the meantime, let’s explicitly say that <code>Py_DEPRECATED</code> is fine.</p> <h2> <a name="clarifications-4" class="anchor" href="#clarifications-4"></a>Clarifications</h2> <pre><code class="lang-diff">-2. Add a warning. [...) +2. Add a warning to the current ``main`` branch. [...] </code></pre> <pre><code class="lang-diff">- [...] (e.g. for a warning in Python 3.10, you either wait + [...] (e.g. for a warning in Python 3.10.0, you either wait until at least Python 3.12 or Python 4.0 to make the change). </code></pre> <p>Generally, adding a deprecation warning is not a bugfix so it shouldn’t go in a stable release. These changes should nudge people to not worry about older branches.</p> <h2> <a name="changelog-5" class="anchor" href="#changelog-5"></a>Changelog</h2> <p>The PEP should also get a Changelog section with a link to this discussion. That’s not in the PR yet.</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="8" /> <span class='post-likes'>8 Likes</span> </div> </div> <div id='post_2' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/barry'><span itemprop='name'>barry</span></a> (Barry Warsaw) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2022-12-19T23:33:58Z' class='post-time'> December 19, 2022, 11:33pm </time> <meta itemprop='dateModified' content='2022-12-19T23:33:58Z'> <span itemprop='position'>2</span> </span> </div> <div class='post' itemprop='text'> <aside class="quote group-committers" data-username="encukou" data-post="1" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/encukou/48/2461_2.png" class="avatar"> Petr Viktorin:</div> <blockquote> <p>for existing stuff (which might be decades old), by default we should assume that someone uses it.</p> </blockquote> </aside> <p>Someone probably does, but I’m not sure if that should extend the deprecation policy to undocumented APIs. How would I then document that an API <em>is</em> private or should be considered unstable? Do I have to do that with every method and variable in my code (probably at least narrowing out leading-underscore names)?</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="2" /> <span class='post-likes'>2 Likes</span> </div> </div> <div id='post_3' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/brettcannon'><span itemprop='name'>brettcannon</span></a> (Brett Cannon) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2022-12-20T00:45:32Z' class='post-time'> December 20, 2022, 12:45am </time> <meta itemprop='dateModified' content='2022-12-20T00:45:32Z'> <span itemprop='position'>3</span> </span> </div> <div class='post' itemprop='text'> <aside class="quote group-committers" data-username="barry" data-post="2" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/barry/48/42_2.png" class="avatar"> Barry Warsaw:</div> <blockquote> <p>How would I then document that an API <em>is</em> private or should be considered unstable?</p> </blockquote> </aside> <p>Probably leading underscore or <a href="https://peps.python.org/pep-0689/" class="inline-onebox">PEP 689 – Unstable C API tier | peps.python.org</a> .</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="3" /> <span class='post-likes'>3 Likes</span> </div> </div> <div id='post_4' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/encukou'><span itemprop='name'>encukou</span></a> (Petr Viktorin) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2022-12-20T08:48:32Z' class='post-time'> December 20, 2022, 8:48am </time> <meta itemprop='dateModified' content='2022-12-20T08:48:32Z'> <span itemprop='position'>4</span> </span> </div> <div class='post' itemprop='text'> <p>Right, use a leading underscore. That’s the first thing on the PEP’s list of what’s private.</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="2" /> <span class='post-likes'>2 Likes</span> </div> </div> <div id='post_5' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/barry'><span itemprop='name'>barry</span></a> (Barry Warsaw) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2022-12-20T19:39:20Z' class='post-time'> December 20, 2022, 7:39pm </time> <meta itemprop='dateModified' content='2022-12-20T19:39:20Z'> <span itemprop='position'>5</span> </span> </div> <div class='post' itemprop='text'> <aside class="quote group-committers" data-username="encukou" data-post="4" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/encukou/48/2461_2.png" class="avatar"> Petr Viktorin:</div> <blockquote> <p>use a leading underscore</p> </blockquote> </aside> <p>Sure, of course I get that, and of course do the same in my own code. But what about existing stdlib code that this PEP covers? Do we go a-rewriting to ensure that stdlib APIs conform to this convention, otherwise they are now all considered public? And if we do, then doesn’t that effectively break the backward compatibility constraints proposed in the PEP’s revision?</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="1" /> <span class='post-likes'>1 Like</span> </div> </div> <div id='post_6' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/brettcannon'><span itemprop='name'>brettcannon</span></a> (Brett Cannon) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2022-12-20T20:08:36Z' class='post-time'> December 20, 2022, 8:08pm </time> <meta itemprop='dateModified' content='2022-12-20T20:08:36Z'> <span itemprop='position'>6</span> </span> </div> <div class='post' itemprop='text'> <aside class="quote group-committers" data-username="barry" data-post="5" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/barry/48/42_2.png" class="avatar"> Barry Warsaw:</div> <blockquote> <p>Do we go a-rewriting to ensure that stdlib APIs conform to this convention, otherwise they are now all considered public?</p> </blockquote> </aside> <p>Assuming that module has actual stewards who care, you probably could.</p> <aside class="quote group-committers" data-username="barry" data-post="5" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/barry/48/42_2.png" class="avatar"> Barry Warsaw:</div> <blockquote> <p>And if we do, then doesn’t that effectively break the backward compatibility constraints proposed in the PEP’s revision?</p> </blockquote> </aside> <p>Only if you don’t follow the deprecation policy for the old names. <img src="https://emoji.discourse-cdn.com/apple/wink.png?v=12" title=":wink:" class="emoji" alt=":wink:" loading="lazy" width="20" height="20"> You can probably do a redirection where the old name raises the warning.</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="3" /> <span class='post-likes'>3 Likes</span> </div> </div> <div id='post_7' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/ncoghlan'><span itemprop='name'>ncoghlan</span></a> (Alyssa Coghlan) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2023-01-01T02:55:04Z' class='post-time'> January 1, 2023, 2:55am </time> <meta itemprop='dateModified' content='2023-01-01T02:55:04Z'> <span itemprop='position'>7</span> </span> </div> <div class='post' itemprop='text'> <aside class="quote group-committers" data-username="barry" data-post="5" data-topic="22042"> <div class="title"> <div class="quote-controls"></div> <img loading="lazy" alt="" width="24" height="24" src="https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.python.org/barry/48/42_2.png" class="avatar"> Barry Warsaw:</div> <blockquote> <p>Do we go a-rewriting to ensure that stdlib APIs conform to this convention, otherwise they are now all considered public?</p> </blockquote> </aside> <p>It wouldn’t make sense to do that pre-emptively, but if a future refactoring wanted to make changes to that “intended to be internal but not marked as such” API, <em>that</em> would be the time to add the missing underscore.</p> <p>The old unintentionally public API would gain a code comment explaining why it still existed as a compatibility wrapper around the new clearly private API. Whether it was actively deprecated or not would depend on the specific situation.</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="0" /> <span class='post-likes'></span> </div> </div> <div id='post_8' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/encukou'><span itemprop='name'>encukou</span></a> (Petr Viktorin) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2023-06-19T09:44:49Z' class='post-time'> June 19, 2023, 9:44am </time> <meta itemprop='dateModified' content='2023-06-19T09:44:49Z'> <span itemprop='position'>8</span> </span> </div> <div class='post' itemprop='text'> <p>Submitted to the SC: <a href="https://github.com/python/steering-council/issues/196" class="inline-onebox">Backwards Compatibility Policy updates/clarifications · Issue #196 · python/steering-council · GitHub</a></p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="1" /> <span class='post-likes'>1 Like</span> </div> </div> <div id='post_9' itemprop='comment' itemscope itemtype='http://schema.org/Comment' class='topic-body crawler-post'> <div class='crawler-post-meta'> <span class="creator" itemprop="author" itemscope itemtype="http://schema.org/Person"> <a itemprop="url" href='https://discuss.python.org/u/gpshead'><span itemprop='name'>gpshead</span></a> (Gregory P. Smith) </span> <span class="crawler-post-infos"> <time itemprop='datePublished' datetime='2023-06-19T18:25:36Z' class='post-time'> June 19, 2023, 6:25pm </time> <meta itemprop='dateModified' content='2023-06-19T18:25:36Z'> <span itemprop='position'>9</span> </span> </div> <div class='post' itemprop='text'> <p>The steering council is happy with these changes.</p> </div> <div itemprop="interactionStatistic" itemscope itemtype="http://schema.org/InteractionCounter"> <meta itemprop="interactionType" content="http://schema.org/LikeAction"/> <meta itemprop="userInteractionCount" content="1" /> <span class='post-likes'>1 Like</span> </div> </div> </div> </div> <footer class="container wrap"> <nav class='crawler-nav'> <ul> <li itemscope itemtype='http://schema.org/SiteNavigationElement'> <span itemprop='name'> <a href='/' itemprop="url">Home </a> </span> </li> <li itemscope itemtype='http://schema.org/SiteNavigationElement'> <span itemprop='name'> <a href='/categories' itemprop="url">Categories </a> </span> </li> <li itemscope itemtype='http://schema.org/SiteNavigationElement'> <span itemprop='name'> <a href='/guidelines' itemprop="url">Guidelines </a> </span> </li> <li itemscope itemtype='http://schema.org/SiteNavigationElement'> <span itemprop='name'> <a href='/tos' itemprop="url">Terms of Service </a> </span> </li> <li itemscope itemtype='http://schema.org/SiteNavigationElement'> <span itemprop='name'> <a href='/privacy' itemprop="url">Privacy Policy </a> </span> </li> </ul> </nav> <p class='powered-by-link'>Powered by <a href="https://www.discourse.org">Discourse</a>, best viewed with JavaScript enabled</p> </footer> <div class="buorg"><div>Unfortunately, <a href="https://www.discourse.org/faq/#browser">your browser is unsupported</a>. Please <a href="https://browsehappy.com">switch to a supported browser</a> to view rich content, log in and reply.</div></div> </body> </html>