`#[pyclass(frozen)]` implementation

[davidhewitt]

As of merging #1979 we now have a basic #[pyclass(frozen)] working on main. However, it is still undocumented, and the implementation was a bit rough around the edges. Below is a list of things that I wrote down that would be good to clean up / finish off before the 0.17 release is ready to go:

• I moved a few associated types from PyClass to PyClassImpl (i.e. make them not public). This was necessary to allow some other trait bounds to be just on PyClassImpl. I think this is fine to do, however we should mention in the CHANGELOG.
• I added a second associated type in PyClassImpl - Mutability and PyClassMutability. It should be possible to just have one.
• (Internal) documentation for how the new traits work.
• Documentation for #[pyclass(frozen)] in the guide.
• Might be nice to benchmark / optimise these new code paths.
• Now that it's not actually doing borrow checking in the immutable case, I'd like to propose renaming PyCell<T> to PyClassObject<T>.

@mejrs if you're picking up any of these bits feel free to ping on here, just so we don't duplicate work. I'll do the same.

[mejrs]

I was thinking - can we use this to avoid having to acquire the GIL for things like Py<T>'s Display and Serialize impls?

Also, I plan on rewriting the docs around the pointer types, I can probably include some bits about this :)

[davidhewitt]

I think... maybe from a correctness standpoint yes, but I fear that the implementation would require specialization or a big big refactor.

[davidhewitt]

A thought... should this be called #[pyclass(frozen)]? That would match the pattern from dataclasses and attrs libraries e.g. @dataclass(frozen = True).

Just realised this because if we do add #[pyclass(dataclass)] we would then have #[pyclass(dataclass, frozen)] 🤔

[mejrs]

A thought... should this be called #[pyclass(frozen)]?

That mirrors the python api a lot better 👍

What should we name the Mutability/Mutable/Immutable traits and structs then? Those are user-visible.

[davidhewitt]

I added a second associated type in PyClassImpl - Mutability and PyClassMutability. It should be possible to just have one.

So I'm going to call this item done; the current implementation has type Frozen in PyClass trait, and then PyClassImpl does still need PyClassMutability to make the underlying implementation compile. (From experimenting it seems like removing concrete PyClassMutability and asking the compiler to infer it leads to an explosion in where bounds all over the place.)

[davidhewitt]

I moved a few associated types from PyClass to PyClassImpl (i.e. make them not public). This was necessary to allow some other trait bounds to be just on PyClassImpl. I think this is fine to do, however we should mention in the CHANGELOG.

Done in #2572

[davidhewitt]

With this I'm going to close this issue. The rest of the items are nice-to-haves which I expect will happen over time anyway, and this code is now in a state ready to release for 0.17.