deprecate super class initialization from tuples

[Icxolu]

This deprecates the tuple syntax for super class initialization as per #5739 (review).

In #[new] this will emit a deprecation warning when detected. As for the From<(S, B)> for PyClassInitializer<S> impl, I'm not sure we can do more that mentioning it in the changelog and migration guide.

[davidhewitt]

Thanks, this looks good to me. Some thoughts:

• We should probably touch up the docs and guide to make it easier for users to understand how to use PyClassInitializer.
• Should we be figuring out how to pass arguments to super __new__ before asking users to migrate existing code? I am not entirely sure we won't have to change the PyClassInitializer API to make that possible, and it might be unfortunate if we push users to use this API just for us to change it again.

[davidhewitt]

This doc needs updating, probably should just mention PyClassInitializer here.

[davidhewitt]

Should remove this too.

[Icxolu]

• Should we be figuring out how to pass arguments to super __new__ before asking users to migrate existing code? I am not entirely sure we won't have to change the PyClassInitializer API to make that possible, and it might be unfortunate if we push users to use this API just for us to change it again.

Good question. I think this depends on how we want that API to look like. The simple solution would probably be to add something like PyClassInitializer::add_native_base_args and store them inside of the PyClassInitializer. I think this could work to provide that functionality, but I'm not sure if that's the best api we can come up with...

For example something like this:

impl<T: PyClass> PyClassInitializer<T> {
    ...

    pub fn add_args(mut self, args: Bound<'_, PyTuple>) -> Self
    where
        T::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<T::BaseType>>,
    {
        self.args = Some(args.unbind());
        self
    }
    
    pub fn add_kwargs(mut self, kwargs: Bound<'_, PyDict>) -> Self
    where
        T::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<T::BaseType>>,
    {
        self.kwargs = Some(kwargs.unbind());
        self
    }

    ...
}

And usage like this:

#[pyclass(subclass, extends=PyDict)]
struct Foo {}

#[pyclass(extends=Foo)]
struct Bar;

#[pymethods]
impl Bar {
    #[new]
    fn new(py: Python<'_>) -> PyClassInitializer<Self> {
        let args = todo!();
        PyClassInitializer::from(Foo {}).add_args(args).add_subclass(Bar)
    }
}