New #[pyclass] system that is aware of its concrete layout

examples/rustapi_module/src/buf_and_str.rs

@@ -9,8 +9,8 @@ struct BytesExtractor {}
 #[pymethods]
 impl BytesExtractor {
     #[new]
-    pub fn __new__(obj: &PyRawObject) {
-        obj.init({ BytesExtractor {} });
+    pub fn __new__() -> Self {
+        BytesExtractor {}
     }
 
     pub fn from_bytes(&mut self, bytes: &PyBytes) -> PyResult<usize> {

examples/rustapi_module/src/datetime.rs

@@ -195,8 +195,8 @@ pub struct TzClass {}
 #[pymethods]
 impl TzClass {
     #[new]
-    fn new(obj: &PyRawObject) {
-        obj.init(TzClass {})
+    fn new() -> Self {
+        TzClass {}
     }
 
     fn utcoffset<'p>(&self, py: Python<'p>, _dt: &PyDateTime) -> PyResult<&'p PyDelta> {

examples/rustapi_module/src/dict_iter.rs

@@ -16,8 +16,8 @@ pub struct DictSize {
 #[pymethods]
 impl DictSize {
     #[new]
-    fn new(obj: &PyRawObject, expected: u32) {
-        obj.init(DictSize { expected })
+    fn new(expected: u32) -> Self {
+        DictSize { expected }
     }
 
     fn iter_dict(&mut self, _py: Python<'_>, dict: &PyDict) -> PyResult<u32> {

examples/rustapi_module/src/othermod.rs

@@ -13,10 +13,10 @@ pub struct ModClass {
 #[pymethods]
 impl ModClass {
     #[new]
-    fn new(obj: &PyRawObject) {
-        obj.init(ModClass {
+    fn new() -> Self {
+        ModClass {
             _somefield: String::from("contents"),
-        })
+        }
     }
 
     fn noop(&self, x: usize) -> usize {

examples/rustapi_module/src/subclassing.rs

@@ -8,8 +8,8 @@ pub struct Subclassable {}
 #[pymethods]
 impl Subclassable {
     #[new]
-    fn new(obj: &PyRawObject) {
-        obj.init(Subclassable {});
+    fn new() -> Self {
+        Subclassable {}
     }
 }
 

examples/word-count/src/lib.rs

@@ -16,10 +16,10 @@ struct WordCounter {
 #[pymethods]
 impl WordCounter {
     #[new]
-    fn new(obj: &PyRawObject, path: String) {
-        obj.init(WordCounter {
+    fn new(path: String) -> Self {
+        WordCounter {
             path: PathBuf::from(path),
-        });
+        }
     }
 
     /// Searches for the word, parallelized by rayon

guide/src/class.md

@@ -15,57 +15,110 @@ struct MyClass {
 }
 ```
 
-The above example generates implementations for `PyTypeInfo` and `PyTypeObject` for `MyClass`.
+The above example generates implementations for `PyTypeInfo`, `PyTypeObject`
+and `PyClass` for `MyClass`.
 
-## Get Python objects from `pyclass`
+Specifically, the following implementation is generated.
 
-You can use `pyclass`es like normal rust structs.
+```rust
+use pyo3::prelude::*;
+use pyo3::{PyClassShell, PyTypeInfo};
 
-However, if instantiated normally, you can't treat `pyclass`es as Python objects.
+struct MyClass {
+    num: i32,
+    debug: bool,
+}
+
+impl pyo3::pyclass::PyClassAlloc for MyClass {}
 
-To get a Python object which includes `pyclass`, we have to use some special methods.
+impl PyTypeInfo for MyClass {
+    type Type = MyClass;
+    type BaseType = pyo3::types::PyAny;
+    type ConcreteLayout = PyClassShell<Self>;
 
-### `PyRef`
+    const NAME: &'static str = "MyClass";
+    const MODULE: Option<&'static str> = None;
+    const DESCRIPTION: &'static str = "This is a demo class";
+    const FLAGS: usize = 0;
 
-`PyRef` is a special reference, which ensures that the referred struct is a part of
-a Python object, and you are also holding the GIL.
+    #[inline]
+    unsafe fn type_object() -> &'static mut pyo3::ffi::PyTypeObject {
+        static mut TYPE_OBJECT: pyo3::ffi::PyTypeObject = pyo3::ffi::PyTypeObject_INIT;
+        &mut TYPE_OBJECT
+    }
+}
+
+impl pyo3::pyclass::PyClass for MyClass {
+    type Dict = pyo3::pyclass_slots::PyClassDummySlot;
+    type WeakRef = pyo3::pyclass_slots::PyClassDummySlot;
+}
+
+impl pyo3::IntoPy<PyObject> for MyClass {
+    fn into_py(self, py: pyo3::Python) -> pyo3::PyObject {
+        pyo3::IntoPy::into_py(pyo3::Py::new(py, self).unwrap(), py)
+    }
+}
+
+pub struct MyClassGeneratedPyo3Inventory {
+    methods: &'static [pyo3::class::PyMethodDefType],
+}
+
+impl pyo3::class::methods::PyMethodsInventory for MyClassGeneratedPyo3Inventory {
+    fn new(methods: &'static [pyo3::class::PyMethodDefType]) -> Self {
+        Self { methods }
+    }
+
+    fn get_methods(&self) -> &'static [pyo3::class::PyMethodDefType] {
+        self.methods
+    }
+}
+
+impl pyo3::class::methods::PyMethodsInventoryDispatch for MyClass {
+    type InventoryType = MyClassGeneratedPyo3Inventory;
+}
+
+pyo3::inventory::collect!(MyClassGeneratedPyo3Inventory);
+
+# let gil = Python::acquire_gil();
+# let py = gil.python();
+# let cls = py.get_type::<MyClass>();
+# pyo3::py_run!(py, cls, "assert cls.__name__ == 'MyClass'")
+```
 
-You can get an instance of `PyRef` by `PyRef::new`, which does 3 things:
-1. Allocates a Python object in the Python heap
-2. Copies the Rust struct into the Python object
-3. Returns a reference to it
 
-You can use `PyRef` just like `&T`, because it implements `Deref<Target=T>`.
+## Get Python objects from `pyclass`
+You sometimes need to convert your `pyclass` into a Python object in Rust code (e.g., for testing it).
+
+For getting *GIL-bounded*(i.e., with `'py` lifetime) references of `pyclass`,
+you can use `PyClassShell<T>`.
+Or you can use `Py<T>` directly, for *not-GIL-bounded* references.
+
+### `PyClassShell`
+`PyClassShell` represents the actual layout of `pyclass` on the Python heap.
+
+If you want to instantiate `pyclass` in Python and get the the reference,
+you can use `PyClassShell::new_ref` or `PyClassShell::new_mut`.
+
 ```rust
 # use pyo3::prelude::*;
 # use pyo3::types::PyDict;
+# use pyo3::PyClassShell;
 #[pyclass]
 struct MyClass {
    num: i32,
    debug: bool,
 }
 let gil = Python::acquire_gil();
 let py = gil.python();
-let obj = PyRef::new(py, MyClass { num: 3, debug: true }).unwrap();
+let obj = PyClassShell::new_ref(py, MyClass { num: 3, debug: true }).unwrap();
+// You can use deref
 assert_eq!(obj.num, 3);
 let dict = PyDict::new(py);
-// You can treat a `PyRef` as a Python object
+// You can treat a `&PyClassShell` as a normal Python object
 dict.set_item("obj", obj).unwrap();
-```
 
-### `PyRefMut`
-
-`PyRefMut` is a mutable version of `PyRef`.
-```rust
-# use pyo3::prelude::*;
-#[pyclass]
-struct MyClass {
-   num: i32,
-   debug: bool,
-}
-let gil = Python::acquire_gil();
-let py = gil.python();
-let mut obj = PyRefMut::new(py, MyClass { num: 3, debug: true }).unwrap();
+// return &mut PyClassShell<MyClass>
+let obj = PyClassShell::new_mut(py, MyClass { num: 3, debug: true }).unwrap();
 obj.num = 5;
 ```
 
@@ -115,22 +168,16 @@ attribute. Only Python's `__new__` method can be specified, `__init__` is not av
 
 ```rust
 # use pyo3::prelude::*;
-# use pyo3::PyRawObject;
 #[pyclass]
 struct MyClass {
    num: i32,
 }
 
 #[pymethods]
 impl MyClass {
-
      #[new]
-     fn new(obj: &PyRawObject, num: i32) {
-         obj.init({
-             MyClass {
-                 num,
-             }
-         });
+     fn new(num: i32) -> Self {
+         MyClass { num }
      }
 }
 ```
@@ -139,24 +186,29 @@ Rules for the `new` method:
 
 * If no method marked with `#[new]` is declared, object instances can only be created
   from Rust, but not from Python.
-* The first parameter is the raw object and the custom `new` method must initialize the object
-  with an instance of the struct using the `init` method. The type of the object may be the type object of
-  a derived class declared in Python.
-* The first parameter must have type `&PyRawObject`.
+* All parameters are from Python.
+* It can return one of these types:
+  - `T`
+  - `PyResult<T>`
+  - `PyClassInitializer<T>`
+  - `PyResult<PyClassInitializer<T>>`
+* If you pyclass declared with `#[pyclass(extends=BaseType)]` and `BaseType`
+is also `#[pyclass]`, you have to return `PyClassInitializer<T>` or
+`PyResult<PyClassInitializer<T>>` with the baseclass initialized. See the
+below Inheritance section for detail.
 * For details on the parameter list, see the `Method arguments` section below.
-* The return value must be `T` or `PyResult<T>` where `T` is ignored, so it can
-  be just `()` as in the example above.
-
 
 ## Inheritance
 
 By default, `PyObject` is used as the base class. To override this default,
 use the `extends` parameter for `pyclass` with the full path to the base class.
-The `new` method of subclasses must call their parent's `new` method.
+The `new` method of subclasses must call `initializer.get_super().init`,
+where `initializer` is `PyClassInitializer<Self>`.
 
-```rust,ignore
+```rust
 # use pyo3::prelude::*;
-# use pyo3::PyRawObject;
+use pyo3::PyClassShell;
+
 #[pyclass]
 struct BaseClass {
    val1: usize,
@@ -165,12 +217,12 @@ struct BaseClass {
 #[pymethods]
 impl BaseClass {
    #[new]
-   fn new(obj: &PyRawObject) {
-       obj.init(BaseClass { val1: 10 });
+   fn new() -> Self {
+       BaseClass { val1: 10 }
    }
 
-   pub fn method(&self) -> PyResult<()> {
-      Ok(())
+   pub fn method(&self) -> PyResult<usize> {
+      Ok(5)
    }
 }
 
@@ -182,15 +234,22 @@ struct SubClass {
 #[pymethods]
 impl SubClass {
    #[new]
-   fn new(obj: &PyRawObject) {
-       obj.init(SubClass { val2: 10 });
-       BaseClass::new(obj);
+   fn new() -> PyClassInitializer<Self> {
+       let mut init = PyClassInitializer::from_value(SubClass { val2: 10 });
+       init.get_super().init(BaseClass::new());
+       init
    }
 
-   fn method2(&self) -> PyResult<()> {
-      self.get_base().method()
+   fn method2(self_: &PyClassShell<Self>) -> PyResult<usize> {
+      self_.get_super().method().map(|x| x * 2)
    }
 }
+
+
+# let gil = Python::acquire_gil();
+# let py = gil.python();
+# let sub = pyo3::PyClassShell::new_ref(py, SubClass::new()).unwrap();
+# pyo3::py_run!(py, sub, "assert sub.method2() == 10")
 ```
 
 The `ObjectProtocol` trait provides a `get_base()` method, which returns a reference
@@ -589,18 +648,16 @@ struct GCTracked {} // Fails because it does not implement PyGCProtocol
 Iterators can be defined using the
 [`PyIterProtocol`](https://docs.rs/pyo3/latest/pyo3/class/iter/trait.PyIterProtocol.html) trait.
 It includes two methods `__iter__` and `__next__`:
-  * `fn __iter__(slf: PyRefMut<Self>) -> PyResult<impl IntoPy<PyObject>>`
-  * `fn __next__(slf: PyRefMut<Self>) -> PyResult<Option<impl IntoPy<PyObject>>>`
+  * `fn __iter__(slf: &mut PyClassShell<Self>) -> PyResult<impl IntoPy<PyObject>>`
+  * `fn __next__(slf: &mut PyClassShell<Self>) -> PyResult<Option<impl IntoPy<PyObject>>>`
 
   Returning `Ok(None)` from `__next__` indicates that that there are no further items.
 
 Example:
 
 ```rust
-extern crate pyo3;
-
 use pyo3::prelude::*;
-use pyo3::PyIterProtocol;
+use pyo3::{PyIterProtocol, PyClassShell};
 
 #[pyclass]
 struct MyIterator {
@@ -609,10 +666,10 @@ struct MyIterator {
 
 #[pyproto]
 impl PyIterProtocol for MyIterator {
-    fn __iter__(slf: PyRefMut<Self>) -> PyResult<Py<MyIterator>> {
+    fn __iter__(slf: &mut PyClassShell<Self>) -> PyResult<Py<MyIterator>> {
         Ok(slf.into())
     }
-    fn __next__(mut slf: PyRefMut<Self>) -> PyResult<Option<PyObject>> {
+    fn __next__(slf: &mut PyClassShell<Self>) -> PyResult<Option<PyObject>> {
         Ok(slf.iter.next())
     }
 }

guide/src/function.md

@@ -108,8 +108,8 @@ impl MyClass {
     // the signature for the constructor is attached
     // to the struct definition instead.
     #[new]
-    fn new(obj: &PyRawObject, c: i32, d: &str) {
-        obj.init(Self {});
+    fn new(c: i32, d: &str) -> Self {
+        Self {}
     }
     // the self argument should be written $self
     #[text_signature = "($self, e, f)"]

guide/src/python_from_rust.md

@@ -35,7 +35,8 @@ Since `py_run!` can cause panic, we recommend you to use this macro only for tes
 your Python extensions quickly.
 
 ```rust
-use pyo3::{PyObjectProtocol, prelude::*, py_run};
+use pyo3::prelude::*;
+use pyo3::{PyClassShell, PyObjectProtocol, py_run};
 #  fn main() {
 #[pyclass]
 struct UserData {
@@ -60,7 +61,7 @@ let userdata = UserData {
     id: 34,
     name: "Yu".to_string(),
 };
-let userdata = PyRef::new(py, userdata).unwrap();
+let userdata = PyClassShell::new_ref(py, userdata).unwrap();
 let userdata_as_tuple = (34, "Yu");
 py_run!(py, userdata userdata_as_tuple, r#"
 assert repr(userdata) == "User Yu(id: 34)"