gh-144473: Add "steal" term to glossary; clarify "stealing" on error

[encukou]

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

---

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

[encukou]

@ZeroIntensity

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]

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]

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]

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]

Yes, it makes all references use the same style.

[ZeroIntensity]

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]

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

[encukou]

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.