Irregular reference counting

[encukou]

It's not possible to tell how a function handles references (e.g. returns borrowed one, steals an argument) from usage (i.e. in a code review).

[vstinner]

Can we deprecate these functions or have a way to opt-out? We can introduce new functions with regular refcount handling at least.

See discussion in 2020: python/cpython#86460

[vstinner]

Recent discussions:

• Add PyModule_Add() which steals a reference: bpo-42327: Add PyModule_Add() (smaller). python/cpython#23443
• Add PyDict_GetItemRef() which returns a strong reference: gh-106004: Add PyDict_GetItemRef() function python/cpython#106005
• Steering Council: decision: Should we add non-borrowed-ref public C APIs, if so, is there a naming convention? python/steering-council#201

[encukou]

Proposed guideline issue: capi-workgroup/api-evolution#16