Rename PyObjectRef with PyAny

[kngwyu]

See #356 (comment) and around comments for the motivation.
Some related ideas:

• Maybe should we remove FromPyObject rather than renaming it? This trait remains unchanged and doesn't fit to our semantics
• We should also rename PyTryFrom with PyDowncast?

[pganssle]

As someone who doesn't really understand what PyObjectRef does at the moment, I will say that changing this name to PyAny doesn't help me much, if at all.

I wonder if it might be a good idea to start by adding clear documentation about the difference between PyObject and PyObjectRef, and then propose a change to the name?

[konstin]

@pganssle I'm convinced that this is a better name and, in combination with more documentation, it will make more sense than PyObjectRef.

For short, the new name means that

from typing import List, Any


def foo(x: List, y: Any):
    ...

translates into

fn foo(x: &PyList, y: &PyAny) {
    unimplemented!()
}

[konstin]

Big 👍

[konstin]

Maybe should we remove FromPyObject rather than renaming it? This trait remains unchanged and doesn't fit to our semantics

It should be replaced by FromPy at some point.

We should also rename PyTryFrom with PyDowncast?

I like the idea, but that should be discussed separately.

[konstin]

I'd say we wait a bit before merging so everyone has time to add comments.

Oh, and @kngwyu could you please add a changelog entry?

[pganssle]

@konstin

For short, the new name means that
...
translates into
...

Yes, this is is a nice parallel, but this is very specific to the Python typing module. The equivalent for things other than annotations would be "derived from PyObject". I think you don't want to start using "mixed metaphors", where the Rust type system parallels type annotations in some respects, and parallels the C API / inheritance model in other respects. It will prevent newcomers from forming a useful mental model of how to use pyo3 types.

I haven't looked into this closely, but it may be worth considering other parts of the type system to see if the parallels break down. or if they hold up. What about Callable? Sequence?

I think in the end you should only adopt this Any if the idea is that PyO3's type system will generally try to have a fairly consistent relationship to the typing type system, and that you want to abandon the idea of inheritance.

[konstin]

As I've said in the issue thread, PyObject would indeed be the ideal name. Unfortunately that is already taken twice (for the ffi type and for our wrapper) and PyAny was second best I could come up with. If you have a better name, I'm happy to discuss that.

Callable isn't implemented yet, PySequence exists. The types module doc page has a good overview, and I'd say it's kinda consistent.

I think in the end you should only adopt this Any if the idea is that PyO3's type system will generally try to have a fairly consistent relationship to the typing type system, and that you want to abandon the idea of inheritance.

I don't want to base pyo3 on typing, I just want to use the resemblance to make it easier understandable (I'd also say that "any" makes sense even without typing). I don't see how this related to inheritance, especially given that pyo3 can only emulate inheritance.

[kngwyu]

@pganssle
I'm not the author, but I think the reason why both PyObject and PyObjectRef exist is the mostly historical one.
PyObject remains unchanged since rust-cpython age and PyObjectRef is added after this project started.
PyObjectRef behaves like other python native types like PyDict and mostly we use it as &'gil PyObjectRef. It has a life time same as GIL, which is forced by our object stack.
Other than that, PyObject behaves like Py<PyObjectRef>. It's used as PyObject and not has a lifetime same as GIL, though it also does refcnt -= 1 when a GILGuard drops.

So while renaming PyObjectRef with PyObject is good, it needs a lots of refactoring, especially around ToPyObject and IntoPyObject.
But I think it's still possible and worth trying, though how to change ToPyObject is unclear.