[issue35514] Docs on reference count detail. enhancement.

[Cheryl Sabella]

Change by Cheryl Sabella :


--
keywords: +patch
pull_requests: +10518
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35514] Docs on reference count detail. enhancement.

[Terry J. Reedy]

Change by Terry J. Reedy :


--
nosy: +serhiy.storchaka

__
Python tracker 

__
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35514] Docs on reference count detail. enhancement.

[bombs]

New submission from bombs :

https://docs.python.org/3/c-api/intro.html#reference-count-details

When I read that section of the docs first time, I found it hard to grasp what 
transferring of ownership is, which is an important and repeating concept 
throughout the docs. Some explanations were confusing. For example,

> When a function passes ownership of a reference on to its caller, the
> caller is said to receive a new reference

This part tries to explain what is to receive a new reference, in terms of 
passing ownership, when readers have no ideas of what transferring of ownership 
is. I think it is kind of a circular definition fallacy.

I think this section should've explained transferring of ownership, a high 
level concept, in terms of reference count changes, which are concrete 
operations.


(original version)
When a function passes ownership of a reference on to its caller, the caller is 
said to receive a new reference. When no ownership is transferred, the caller 
is said to borrow the reference. Nothing needs to be done for a borrowed 
reference.
Conversely, when a calling function passes in a reference to an object, there 
are two possibilities: the function steals a reference to the object, or it 
does not. Stealing a reference means that when you pass a reference to a 
function, that function assumes that it now owns that reference, and you are 
not responsible for it any longer.

(revision)
When a function returns an object and effectively increases the reference count 
of it, the function is said to give ownership of a new reference to its caller. 
When a function returns an object without changing the reference count of it, 
the caller is said to borrow the reference. Nothing needs to be done for a 
borrowed reference.
Conversely, if a function decreases the reference count of an object, it is 
said to steal the ownership of the reference from its owner. Stealing a 
reference means that when you pass a reference to a stealing function, that 
function assumes that it now owns that reference, and you are not responsible 
for it any longer.

--
assignee: docs@python
components: Documentation
messages: 331946
nosy: bluewhale8202, docs@python
priority: normal
severity: normal
status: open
title: Docs on reference count detail. enhancement.
type: enhancement
versions: Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com