Please explain the meaning of 'stealing' a ref

[Alex Martelli]

Most of this discussion seems to be veering into English (and natural
language in general) and style issues, farther and farther away from
Python.  Still, in as much as Python docs are written in English, I
guess it might still be appropriate here.

Like most authors, I have very strong opinions on style, nuances, fine
points of connotation as well as denotation in phrasing, and language
in general.  Developed in long praxis as well as reflection about all
of these issues, and honed in long, bitter fights with editors and
co-authors, these opinions are unlikely to change very easily...;-)


Christos TZOTZIOY Georgiou wrote:
   ...
>>> The missing part IMO is what "owning a reference" means.  I understand
>>
>>Hmmm... what if the text was transliterated into "Owning a reference
>>means you have to dispose of it properly" from the current "When a
>>function owns a reference, it has to dispose of it properly"?  The current
>>expression and my suggested rewording are meant to convey just the
>>same meaning, but perhaps the rewording is more immediately obvious
>>to some non-native speakers of English (I'm a non-native speaker myself,
>>but sometimes I have trouble gauging what problems others may have).
> 
> For other people (if any) that have similar to my questions, all the
> information about 'owning', 'borrowing' and 'stealing' references is in
> the sections 1.2.1-1.2.2 of the "Python/C API reference", but first have
> a good grasp of the tutorial "Extending and Embedding the Python
> interpreter", subsections 1.10.1-1.10.4 .

So what about my proposed transliteration of "when X, Y" into "X
means Y"?  This is similar to (e.g.) changing "when somebody owns
a property outright, they can sell it" to "owning a property
outright means you can sell it" -- essentially equivalent in normal
English usage, but perhaps more specific or clear to non-natives?


>>> This text is obviously clear, and the misconception was my fault: since
>>> references are just pointer variables at the C level, and I never had a
>>> concept of a function (or a program) 'owning' its variables,
>>> automatically my brain converted the word 'reference' to 'reference to
>>> python object' to 'python object'.  That's it.
>>
>>Ah.  So there may be no fix for this -- we can't get any more explicit,
>>but if your brain converts this to "we talk of owning python objects,
>>never of owning objects" there's really nothing we can do:-(.
> 
> You use present tense for 'converts' above, but I assume you meant to
> use past tense, since this is what I did in the previous paragraph.
> Unusual of you to miss details.  Like I said, the text is clear; it
> needs no fix in the case of owning references|objects.

I don't think I missed any details: I was talking about making the docs
clearer to _other_ (future) readers, as opposed to borrowing Guido's
time machine to retroactively change them so they might be clearer in
the past, so the "your brain converts" in my sentence is (clearly, in
context) a typical case of "generic you"; feel free to mentally
transliterate it to "if some generic and hypothetical reader's brain
converts".  Using the tense "converted" in such a sentence would mean
one's having vague regrets about the unchangeable (save for the time
machine) past, not a particularly interesting subject; I'm focused on
how to make things better in the future.


>>> The word "exceptions" implies "exception to the previous statement".
>>
>>Yes, to the statement terminated by the semicolon - the one saying that
>>few functions steal references.
>>
>>> IIUC "exceptions" should be changed to "examples".
>>
>>Yes, this is surely a reasonable change, if it clarifies the text for some
>>readers.
> 
> Since you agree (and make more specific) that 'exceptions' means
> 'exception to the statement terminated by the semicolon', and since
> neither PyList_SetItem nor PyTuple_SetItem are exceptions to the few
> functions that steal references, doesn't that make the choice of the
> word 'exceptions' unreasonable (as in exactly the opposite of what was
> meant)?  It's not a matter of simple clarification.

No, the use of the word 'exceptions' is anything but unreasonable,
except in as much as each natural language has its typical foibles which
might, abstractly, be considered "unreasonable" if judging natural
languages from completely inappropriate viewpoints (in this case, I'd 
use exactly the same phrasing in Italian or French, so I'm going to
staunchly defend the perfect reasonableness of normal English usage).

The statement "Few people do that" is semantically equivalent to "most
people don't do that", it's just a smoother and more natural way of
expression; in _either_ case, when one continues by mentioning people
as "exceptions", it's then just as reasonable as any other idiomatic
construction -- and perfectly clear in context -- that the "exceptions"
are the (few) people who _do_ "do that".

In an alternative phrasing such as "I don't like any ice-cream brand;
the few exceptions are... [mention of some brands]", the statement
after the semicolon would _contradict_ the one before the semicolon,
which (at least in English and Italian) doesn't sound good (although
in _spoken_ language this construct would astonish nobody, it should
really be edited when found in _written_ form).  When considering how
to edit this, I would _definitely_ want to keep the word "exceptions"
(if I knew I could count on good command of the language on readers'
parts) because its connotations are _just right_: whenever I mention
an exception, a reader is inherently attraced to think of a general
rule -- and in this case the reader finds the rule right before that
semicolon, reinforcing exactly the "rule/exceptions" message I am
trying to send.  So, rather than changing the part after the semicolon,
I look for a way to weaken the assertion before the semicolon, which
was here stated as "absolute rule".  "I don't like most ice-cream
brands" and "I like very few ice-cream brands" are semantically
equivalent, but I prefer the second: all other things being equal,
an assertion phrased in the positive form is easier for the reader
than one phrased in the negative; and the second form is smoother.

The semantics equivalence of the two forms guarantees against any
problem with what follows after the semicolon: in either case, that
part is going to be read as "the few exceptions [[to the general
rule just stated]] are" -- and _the general rule just stated is
*the same* in either case_, which is the point.

All that's in discussion, therefore, is whether to make the
whole expression not quite as strong and obvious to native readers
(missing out on the helpful connotation "exceptions" --> "general
rule") for the purpose of potentially clarifying things for those
readers who, on seeing "exceptions", do NOT immediately "read the
unwritten words" ``to this general rule''.  Unfortunately "examples",
for exactly the same readers who DO get the right connotations from
"exceptions", brings the WRONG connotation here: "examples" leads
to "reading the unwritten words" ``OF this general rule''.

But the general rule is that normally functions *do NOT* steal
references, and yet the alleged ''examples'' are _NOT_ "examples
of this general rule", they are in fact the _exceptions_ to this
general rule.  This means the connotations become, from just
right, to just wrong _for native readers_, and makes the whole
suggested change problematic.


> Either the word 'exceptions' should be changed, or it should be changed
> to 'notable exceptions to <here specify the domain to which the two
> abovementioned functions are exceptions, and which domain is not "'few
> functions steal references", since the functions do steal references>'

There's no such general concept as "exceptions to a domain", but rather
"exceptions to a general rule".  The _general rule_ *IS* "normally
functions don't steal references" (expressed in the preferable positive
form).  Redundantly repeating exactly what you're referring to in each
case is of course a possibility (I'm not very attuned to it since the
editors, quite rightly, would never tolerate such mostly-wasted
wordiness in e.g. magazine articles or Nutshell books, but a reference
manual can be weighed by other criteria).  Given that there _is_ no
ambiguity (for the mostly-intended audience of people with the right
level of idiomatic command of the language) I doubt I can defend such
redundancy, though (particularly not being enthusiastic about it:-).


> The previous two paragraphs were written only because your 'if it
> clarifies the text for some readers' seems to ignore the fact you
> yourself stated two paragraphs above in 'Yes, to the statement...'

I hope I clarified this abundantly, and thank you for forcing me to
think the issues through in such detail as needed to argue against
your contention -- I "instinctively knew" that what you said was
entirely wrong, but explaining exactly how and why meant I had to
analyze and reason in depth about the whole issue.  It's funny --
though I'll never have the easy command of a native speaker, of
course, yet 40+ years of constant practice of English do seem to 
have given me _some_ "reflex" reactions (in this case, the fact
that the applicable idioms _are_ just about the same in Italian
does, of course, also help:-).


> If the python documentation had a terminology dictionary, how would
> 'stealing', 'borrowing' and 'owning' a reference be defined in a concise
> and absolutely clear way?  I seem to not be able to write these
> definitions, although I would like to.

The concept of "owning a reference" is the crucial one.  "Stealing"
is just one way to permanently transfer ownership, "borrowing" means
no transfer of ownership takes place, and these meanings are so close
to those in everyday language that the "terminology dictionary" would
have few problems, I believe.

So, focusing on ownership, and foregoing the concision that would
probably be required in a dictionary, we might say:

"""
Ownership pertains to references, never to objects (objects are not
owned: they are always shared).  "Owning a reference" means being
responsible for calling Py_DECREF on it when the reference is no
longer needed.  Ownership can also be transferred, meaning that the
code that receives ownership of the reference then becomes
responsible for eventually decref'ing it when it's no longer needed.
"""

plus, perhaps, pointers to the various appropriate sections in
the "extending and embedding" tutorial and API reference that deal
with this concept.  Really, the true meaning of "reference
ownership" is _operational_ -- the "responsibility of eventually
decref'ing (unless the ownership is transferred)" _together_ with
the rules for how and when ownership (i.e. responsibility to
eventually decref) is transferred.


Alex