Uh oh!
There was an error while loading. Please reload this page.
docs: improved reference_internal documentation - #5528
Conversation
Improved the wording to make it easier to understand and added a note about the policy falling back to move if the return value is not an lvalue reference or pointer.
gentlegiantJGC
commented
Feb 18, 2025
The test failure is unrelated to changes I made |
| | :enum:`return_value_policy::reference_internal` | If the return value is an lvalue reference or a pointer, the parent object | | ||
| | | (the implicit ``this``, or ``self`` argument of the called method or | | ||
| | | property) is kept alive for at least the lifespan of the return value. | | ||
| | | Otherwise this policy falls back to the policy | |
There was a problem hiding this comment.
That's a great and much needed clarification!
What do you think about:
- Making the "Otherwise ..." sentence bold, and ending it with "
(see #5528)."
?
gentlegiantJGC
commented
Feb 20, 2025
I considered adding a line pointing out that keep_alive doesn't work when explicitly passed to the def_property methods because that is the users natural next response but it felt beyond the scope of it. |
rwgk
left a comment
There was a problem hiding this comment.
Thanks @gentlegiantJGC!
Sorry I'm too busy right now to carefully think about your ideas for a more ambitious fix. I'll merge this, it's definitely useful!
| | :enum:`return_value_policy::reference_internal` | If the return value is an lvalue reference or a pointer, the parent object | | ||
| | | (the implicit ``this``, or ``self`` argument of the called method or | | ||
| | | property) is kept alive for at least the lifespan of the return value. | | ||
| | | **Otherwise this policy falls back to :enum:`return_value_policy::move` | |
There was a problem hiding this comment.
In Sphinx, the enum here does not render correctly, likely because of the bold part?
* Remove enum from bold in doc * [skip ci] Remove bold formatting around (see #5528) --------- Co-authored-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>
Description
The documentation for the reference_internal return policy implies that
py::keep_alive<0, 1>()is always applied but this isn't true.There is quite a bit of confusion about the reference_internal return policy (myself included) stemming from this documentation.
Here are the related issues I have found.
#1764
#2618
#4124
#4236
#5046
These changes:
As documented thoroughtly in #4236 and #5046 the
def_propertyfamily does not honor thekeep_aliveargument passed to it and #2618 also mentions it does not honor thecall_guardargument. I think these issues should be fixed but should it be documented here until it is? The workaround is to usecpp_functionand add those arguments there.Fixes#1764
Fixes#2618
Fixes#4124
Suggested changelog entry:
Improved ``reference_internal`` policy documentation