gh-144473: Add "steal" term to glossary; clarify "stealing" on error by encukou · Pull Request #144502 · python/cpython

encukou · 2026-02-05T13:28:36Z

Issue: Docs: Clarify/unify “stealing” docs #144473

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

With one exception, all "stealing" functions also steal on error, but it makes sense to note this in each case.

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

encukou · 2026-02-05T13:31:15Z

I'm not a huge fan of putting "steal(s)" in quotations. If the user is confused about the term, then they can just click it to go to the glossary. Otherwise, the user knows the term, so it shouldn't be in scare quotes.

Noted.
Are you aware of the discussion about this in capi-workgroup/problems#11?

ZeroIntensity · 2026-02-05T13:48:48Z

I wasn't aware of that discussion. Thanks for the tip.

I'm still not convinced that putting quotation marks around it is the right approach; these are scare quotes, which are used for ideas that are disputed or skeptical, so I think it's a bit of a contradiction to put scare quotes around "steal" when we seem to have coined the term. It makes us seem like we don't trust the term or are taking it from somewhere else, which isn't true, unless I'm missing some history here.

encukou · 2026-02-06T12:40:19Z

AFAIK, “we” minted it but the few-decades-older “we” don't like the term any more.
From the older docs -- PyTuple_SetItem or PyList_SetItem -- it looks like it was minted with the quotes on.

I personally think the term is fine (“transfer ownership” is better, but too unwieldy). But that means I need to be careful :)
In a discussion to remove the quotes, I'd support that -- but this PR is not that, and I don't think that's a discussion to have now.

ZeroIntensity · 2026-02-06T17:02:25Z

In a discussion to remove the quotes, I'd support that -- but this PR is not that, and I don't think that's a discussion to have now.

Yeah, that's fine, but this PR does add quotes in places where there weren't quotes before.

encukou · 2026-02-09T13:05:18Z

Yes, it makes all references use the same style.

ZeroIntensity · 2026-02-09T16:06:50Z

Would it be okay to keep things the same style here, and only add the link? The rest of the PR looks good to me otherwise.

vstinner · 2026-02-10T10:54:33Z

Since the term is added to the glossary, I don't think that it's worth it to put it in quotes.

encukou · 2026-02-11T15:05:03Z

I spent some time reconciling this with capi-workgroup/problems#11, and ended up with a slightly different reason for putting the term in quotes.

Think of it as a placeholder; a TODO. The proper term is transfer ownership. But, defining ownership is a larger change, since I'd like to not limit it to PyObject* references. You can own, borrow or steal a malloc'd buffer in exactly the same way as a reference; the only difference is that you can't INCREF (i.e. create an additional owner).

Here's a draft: main...encukou:cpython:ownership-docs#diff-dfb52ee6e68075f904da6e69ed1799c5cbf1185c279968a807787d69ae2e8cf5R1152

I'd prefer putting this smaller imperfect (and quote-ful) change in now, but, well, it can wait for a rewrite.

vstinner

LGTM. I would prefer avoiding quotes around "steal", but I don't want to block the change just for that.

github-actions · 2026-05-06T00:29:27Z

This PR is stale because it has been open for 30 days with no activity.

wr-web · 2026-05-18T06:43:15Z

I believe the revision of this document is very valuable, as the issue may have led to a large number of potential software defects.

ytsaurus/ytsaurus#1713 （1） 2.2k stars
hyperion-project/hyperion.ng#2009 （2） 3.8k stars
astropy/astropy#19718 （5） 5.2k stars
astropy/astropy#19720
domoticz/domoticz#6813 （1） 3.8k stars
kovidgoyal/calibre#3119 （1） 24.8k stars
ravynsoft/ravynos#557 （1，upstream） 6.7k stars
pygame-community/pygame-ce#3792 （3） 1.5k stars
alan-turing-institute/CleverCSV#162 （2） 1.3k stars
igraph/python-igraph#884 （45）1.4k stars
morloc-project/morloc#52 （1） 215 stars
brgl/libgpiod#187 （3）429 stars，Linux Kernel Related
ninia/jep#635 （1） 1.5k stars
tahoe-lafs/zfec#136 （2） 423 stars
rpmuller/pyquante2#19 （4） 159 stars
ikegami-yukino/neologdn#30 （1） 288 stars
apache/arrow#49917 （1） 16.7k stars
cisagov/Malcolm#960 （1） 2.4k stars

Snape3058 · 2026-06-16T14:50:53Z

Ping. What's the current progress of this PR?

encukou · 2026-06-17T13:08:24Z

The status is awaiting merge :)

It's not the highest priority for me, and the last few times I got to it there was a conflict or CI failure to fix.

read-the-docs-community · 2026-06-17T13:12:06Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33182877 | 📁 Comparing bac55f7 against main (a173a6d)

🔍 Preview build

12 files changed · ± 12 modified

± Modified

encukou · 2026-07-01T11:46:45Z

Now the stars aligned :)

miss-islington-app · 2026-07-01T11:47:04Z

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

miss-islington-app · 2026-07-01T11:47:13Z

Sorry, @encukou, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 34503f39532279efb12653754bb3a7e535fb66cc 3.14

bedevere-app · 2026-07-01T11:47:17Z

GH-152771 is a backport of this pull request to the 3.15 branch.

miss-islington-app · 2026-07-01T11:47:17Z

Sorry, @encukou, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 34503f39532279efb12653754bb3a7e535fb66cc 3.13

bedevere-app · 2026-07-01T11:49:52Z

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

… error (GH-144502) (GH-152772) With one exception, all "stealing" functions also steal on error, but it makes sense to note this in each case. (cherry picked from commit 34503f3) Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

…error (GH-144502) (GH-152772) (GH-152779) With one exception, all "stealing" functions also steal on error, but it makes sense to note this in each case. (cherry picked from commit 34503f3) (cherry picked from commit f8fb02d) Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

… error (GH-144502) (GH-152771) With one exception, all "stealing" functions also steal on error, but it makes sense to note this in each case. (cherry picked from commit 34503f3) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

encukou and others added 3 commits February 5, 2026 14:26

Add "steal" term to glossary; clarify stealing on error

b8fc5c3

With one exception, all "stealing" functions also steal on error, but it makes sense to note this in each case.

Update Doc/c-api/list.rst

d74ff52

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

The caller must not use that reference after the call.

6e0e498

encukou requested review from ZeroIntensity and vstinner February 5, 2026 13:28

encukou requested a review from ericsnowcurrently as a code owner February 5, 2026 13:28

encukou added docs Documentation in the Doc dir topic-C-API needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Feb 5, 2026

github-project-automation Bot added this to Docs PRs Feb 5, 2026

github-project-automation Bot moved this to Todo in Docs PRs Feb 5, 2026

bedevere-app Bot added the awaiting core review label Feb 5, 2026

bedevere-app Bot mentioned this pull request Feb 5, 2026

Docs: Clarify/unify “stealing” docs #144473

Closed

bedevere-app Bot added the skip news label Feb 5, 2026

vstinner approved these changes Mar 10, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Mar 10, 2026

wr-web mentioned this pull request May 4, 2026

Reference Counting (Use-After-Free) Bugs for PyList_SetItem ionelmc/python-hunter#128

Closed

github-actions Bot added the stale Stale PR or inactive for long period of time. label May 6, 2026

github-actions Bot removed the stale Stale PR or inactive for long period of time. label May 25, 2026

serhiy-storchaka added the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label May 30, 2026

Merge in the main branch

bac55f7

encukou merged commit 34503f3 into python:main Jul 1, 2026
30 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Jul 1, 2026

encukou deleted the steal-doc branch July 1, 2026 11:47

bedevere-app Bot removed the awaiting merge label Jul 1, 2026

miss-islington-app Bot assigned encukou Jul 1, 2026

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 1, 2026

encukou removed the needs backport to 3.13 bugs and security fixes label Jul 1, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 1, 2026

Uh oh!

Uh oh!

Conversation

encukou commented Feb 5, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

encukou commented Feb 5, 2026

Uh oh!

ZeroIntensity commented Feb 5, 2026

Uh oh!

encukou commented Feb 6, 2026

Uh oh!

ZeroIntensity commented Feb 6, 2026

Uh oh!

encukou commented Feb 9, 2026

Uh oh!

ZeroIntensity commented Feb 9, 2026

Uh oh!

vstinner commented Feb 10, 2026

Uh oh!

encukou commented Feb 11, 2026

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

wr-web commented May 18, 2026

Uh oh!

Snape3058 commented Jun 16, 2026

Uh oh!

encukou commented Jun 17, 2026

Uh oh!

read-the-docs-community Bot commented Jun 17, 2026

Documentation build overview

Uh oh!

encukou commented Jul 1, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Jul 1, 2026

Uh oh!

miss-islington-app Bot commented Jul 1, 2026

Uh oh!

bedevere-app Bot commented Jul 1, 2026

Uh oh!

miss-islington-app Bot commented Jul 1, 2026

Uh oh!

bedevere-app Bot commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

encukou commented Feb 5, 2026 •

edited by github-actions Bot

Loading