guide: add type overview

[birkenfeld]

fixes #789

[birkenfeld]

Obviously unfinished, but I'd like feedback if the style is ok...

[davidhewitt]

I like what you've written so far. Thanks so much for doing this. When I first came to pyo3 my head was totally boggled by all this too.

Is it also worth adding a note somewhere about references, e.g. that we must use &PyAny rather than PyAny (at least until improvements from #679 land)?

[davidhewitt]

It's worth noting (either for your own benefit, or as part of this section) that we (well, at least myself and @kngwyu) are hoping to one day merge PyAny and PyObject - Py<PyAny> is pretty much the same as PyObject.

See #679

[birkenfeld]

Indeed, that was one question I was going to pose to y'all :)

[davidhewitt]

I think I'd like Py::new() to be able to do this one day, but that's a breaking API change.

[kngwyu]

We can use obj.as_ref(py).extract::<Py<ConcreteType>>

[birkenfeld]

OK, that's good to know!

[kngwyu]

Thank you, it's really easy to read.
My concern is it lacks a section that explains how we should use native types(&PyDict, &PyList, or so).
And it would be good to explain that we allow mutable operations for &PyDict or so since it's really hard to track mutability of them

[birkenfeld]

Thank you, it's really easy to read.
My concern is it lacks a section that explains how we should use native types(&PyDict, &PyList, or so).

What specifically do you have in mind here?

And it would be good to explain that we allow mutable operations for &PyDict or so since it's really hard to track mutability of them

OK, I'll try to find a spot to integrate this.

[kngwyu]

What specifically do you have in mind here?

Just like what you've added as ### PyTuple, PyDict, and many more.

[kngwyu]

Thank you!