Py::as_ref and Py::into_ref (remove AsPyRef)

[davidhewitt]

I introduce Py::as_ref and Py::into_ref. We spoke about Py::into_ref in #1041.

I moved AsPyRef::as_ref to Py::as_ref because I think it's easier to document and for users to discover. Also means one more trait can be removed!

Closes #1041

[kngwyu]

Nice 💯

[birkenfeld]

I'm confused by into_ref. In what cases do you need to / should you use this instead of using as_ref and letting the Py be dropped naturally?

[davidhewitt]

I'm confused by into_ref. In what cases do you need to / should you use this instead of using as_ref and letting the Py be dropped naturally?

Great feedback. We've seen in rare cases APIs want to return a reference but have a Py value they have created (e.g. from into_py()). This has come up in #1041 as well as #1083.

I'll rework documentation later based on the comments here.

[birkenfeld]

Ah, good point. I did not realize that as_ref had the self lifetime and the Python lifetime tied to the return's lifetime. (I'm sure there is a reason this is necessary?)

[davidhewitt]

Yep - the returned reference for as_ref needs to be the shorter of the two lifetimes, which is why they're both set the same.

(It cannot outlive &self because that's the data it's borrowing, and it cannot outlive Python because it's GIL-bound.)

[davidhewitt]

Thanks for the feedback; I've pushed the suggested improvements to the docs.