New submission from bombs <bluewhale8...@gmail.com>:
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 <rep...@bugs.python.org> <https://bugs.python.org/issue35514> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
