deprecate PyCell::new in favor of Py::new or Bound::new

[Icxolu]

Part of #3684

This deprecates PyCell::new in favor of Py::new or Bound::new, depending on whether the GIL attachment is required.

For the tests I used Py if that was enough, and Bound otherwise. In the docs I updated the test-only code and examples unrelated to PyCell. The PyCell specific sections need separate updating, so I #[allow(deprecated)] usage there, same for PyCell specific tests.

[codspeed-hq]

CodSpeed Performance Report

Merging #3872 will degrade performances by 15.02%

_{Comparing Icxolu:pycell-new (5207092) with main (0bb9cab)}

Summary

⚡ 3 improvements
❌ 2 regressions
✅ 74 untouched benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

	Benchmark	main	Icxolu:pycell-new	Change
⚡	mapping_from_dict	327.8 ns	272.2 ns	+20.41%
❌	f64_from_pyobject	405.6 ns	461.1 ns	-12.05%
❌	list_via_downcast	157.2 ns	185 ns	-15.02%
⚡	not_a_list_via_downcast	244.4 ns	216.7 ns	+12.82%
⚡	sequence_from_list	355.6 ns	272.2 ns	+30.61%

[davidhewitt]

Thanks! What did you think of moving from PyCell to Py / Bound.

I'm a little torn. I like the fact that it simplifies PyO3's API and makes Py / Bound the only way to interact with all Python objects, regardless of whether they are native or #[pyclass] types.

On the other hand, the "PyCell" concept is easy for users to see the link to RefCell, and I think we will lose this a bit by removing this type. To be honest, that might not matter so much if we also go further and make #[pyclass(frozen)] the default, because then users will see this concept less anyway. Then we can have a section of the guide dedicated to #[pyclass(frozen = false)] to explain it in detail, even if it's hidden away a bit.

I guess even further down the road, with nogil I half expect that PyCell borrow tracking doesn't work so well because it'll be much easier to hit conflicts with concurrency.

... so maybe in the end I convinced myself it's not such a bad thing if we start slowly killing off the "PyCell" concept now 😂

---

Other than that, just two small comments.

[davidhewitt]

These .as_any() and .into_any() calls are probably a consequence of the same thing as #3867 (comment)

I suggest we merge here anyway and then can tidy up a bunch of .as_any() and .into_any() calls after figuring out a solution.

[Icxolu]

Yes, I've just added some thoughts to that thread.

[Icxolu]

I think it makes sense to try to push to make Py and Bound to be the only way of interacting with Python object. I believe this simplifies the mental model, because the only decision to make is whether the object needs to be attached to the GIL or not.

The functionality will still be there with .borrow() and .borrow_mut(), from the users perspective it will just be combined into Bound. So I guess the concept and mental model of RefCell can still be applied, it might just be not obvious from the name itself.