Rename PyClassShell with PyCell and do mutability checking
#770
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -22,6 +22,7 @@ Specifically, the following implementation is generated: | |||||
|
|
||||||
| ```rust | ||||||
| use pyo3::prelude::*; | ||||||
| use pyo3::types::PyAny; | ||||||
|
|
||||||
| /// Class for demonstration | ||||||
| struct MyClass { | ||||||
|
|
@@ -33,9 +34,10 @@ impl pyo3::pyclass::PyClassAlloc for MyClass {} | |||||
|
|
||||||
| unsafe impl pyo3::PyTypeInfo for MyClass { | ||||||
| type Type = MyClass; | ||||||
| type BaseType = PyAny; | ||||||
| type BaseLayout = pyo3::pycell::PyCellBase<PyAny>; | ||||||
| type Layout = PyCell<Self>; | ||||||
| type Initializer = PyClassInitializer<Self>; | ||||||
|
|
||||||
| const NAME: &'static str = "MyClass"; | ||||||
| const MODULE: Option<&'static str> = None; | ||||||
|
|
@@ -53,6 +55,7 @@ unsafe impl pyo3::PyTypeInfo for MyClass { | |||||
| impl pyo3::pyclass::PyClass for MyClass { | ||||||
| type Dict = pyo3::pyclass_slots::PyClassDummySlot; | ||||||
| type WeakRef = pyo3::pyclass_slots::PyClassDummySlot; | ||||||
| type BaseNativeType = PyAny; | ||||||
| } | ||||||
|
|
||||||
| impl pyo3::IntoPy<PyObject> for MyClass { | ||||||
|
|
@@ -105,47 +108,56 @@ fn mymodule(_py: Python, m: &PyModule) -> PyResult<()> { | |||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ## PyCell and interior mutability | ||||||
| You sometimes need to convert your `pyclass` into a Python object and access it | ||||||
| from Rust code (e.g., for testing it). | ||||||
| [`PyCell`](https://pyo3.rs/master/doc/pyo3/pycell/struct.PyCell.html) is our primary interface for that. | ||||||
|
|
||||||
| `PyCell<T: PyClass>` is always allocated in the Python heap, so we don't have the ownership of it. | ||||||
| We can get `&PyCell<T>`, not `PyCell<T>`. | ||||||
|
|
||||||
| Thus, to mutate data behind `&PyCell` safely, we employ the | ||||||
| [Interior Mutability Pattern](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html) | ||||||
| like [std::cell::RefCell](https://doc.rust-lang.org/std/cell/struct.RefCell.html). | ||||||
|
|
||||||
| Users who are familiar with `RefCell` can use `PyCell` just like `RefCell`. | ||||||
|
|
||||||
| For users who are not very familiar with `RefCell`, here is a reminder of Rust's rules of borrowing: | ||||||
| - At any given time, you can have either (but not both of) one mutable reference or any number of immutable references. | ||||||
| - References must always be valid. | ||||||
| `PyCell` ensures these borrowing rules by tracking references at runtime. | ||||||
|
|
||||||
| ```rust | ||||||
| # use pyo3::prelude::*; | ||||||
| # use pyo3::types::PyDict; | ||||||
| #[pyclass] | ||||||
| struct MyClass { | ||||||
| #[pyo3(get)] | ||||||
| num: i32, | ||||||
| debug: bool, | ||||||
| } | ||||||
| let gil = Python::acquire_gil(); | ||||||
| let py = gil.python(); | ||||||
| let obj = PyCell::new(py, MyClass { num: 3, debug: true }).unwrap(); | ||||||
| { | ||||||
| let obj_ref = obj.borrow(); // Get PyRef | ||||||
| assert_eq!(obj_ref.num, 3); | ||||||
| // You cannot get PyRefMut unless all PyRefs are dropped | ||||||
| assert!(obj.try_borrow_mut().is_err()); | ||||||
| } | ||||||
| { | ||||||
| let mut obj_mut = obj.borrow_mut(); // Get PyRefMut | ||||||
| obj_mut.num = 5; | ||||||
| // You cannot get any other refs until the PyRefMut is dropped | ||||||
| assert!(obj.try_borrow().is_err()); | ||||||
davidhewitt marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| assert!(obj.try_borrow_mut().is_err()); | ||||||
| } | ||||||
| // You can convert `&PyCell` to Python object | ||||||
| pyo3::py_run!(py, obj, "assert obj.num == 5") | ||||||
| ``` | ||||||
|
|
||||||
| `&PyCell<T>` is bounded by the same lifetime as `GILGuard`. | ||||||
| To avoid this you can use `Py<T>`, which stores an object longer than the GIL lifetime. | ||||||
| ```rust | ||||||
| # use pyo3::prelude::*; | ||||||
| #[pyclass] | ||||||
|
|
@@ -159,7 +171,9 @@ fn return_myclass() -> Py<MyClass> { | |||||
| } | ||||||
| let gil = Python::acquire_gil(); | ||||||
| let obj = return_myclass(); | ||||||
| let cell = obj.as_ref(gil.python()); // AsPyRef::as_ref returns &PyCell | ||||||
| let obj_ref = cell.borrow(); // Get PyRef<T> | ||||||
| assert_eq!(obj_ref.num, 1); | ||||||
| ``` | ||||||
|
|
||||||
| ## Customizing the class | ||||||
|
|
@@ -228,9 +242,12 @@ baseclass of `T`. | |||||
| But for more deeply nested inheritance, you have to return `PyClassInitializer<T>` | ||||||
| explicitly. | ||||||
|
|
||||||
| To get a parent class from child, use `PyRef<T>` instead of `&self`, | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| or `PyRefMut<T>` instead of `&mut self`. | ||||||
|
|
||||||
| ```rust | ||||||
| # use pyo3::prelude::*; | ||||||
| use pyo3::PyCell; | ||||||
|
|
||||||
| #[pyclass] | ||||||
| struct BaseClass { | ||||||
|
|
@@ -261,8 +278,9 @@ impl SubClass { | |||||
| (SubClass{ val2: 15}, BaseClass::new()) | ||||||
| } | ||||||
|
|
||||||
| fn method2(self_: PyRef<Self>) -> PyResult<usize> { | ||||||
| let super_ = self_.as_ref(); // Get &BaseClass | ||||||
|
There was a problem hiding this comment. For me this is surprising, while There was a problem hiding this comment. It was initially named |
||||||
| super_.method().map(|x| x * self_.val2) | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
|
|
@@ -279,29 +297,30 @@ impl SubSubClass { | |||||
| .add_subclass(SubSubClass{val3: 20}) | ||||||
| } | ||||||
|
|
||||||
| fn method3(self_: PyRef<Self>) -> PyResult<usize> { | ||||||
| let v = self_.val3; | ||||||
| let super_ = self_.into_super(); // Get PyRef<SubClass> | ||||||
| SubClass::method2(super_).map(|x| x * v) | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
|
|
||||||
| # let gil = Python::acquire_gil(); | ||||||
| # let py = gil.python(); | ||||||
| # let subsub = pyo3::PyCell::new(py, SubSubClass::new()).unwrap(); | ||||||
| # pyo3::py_run!(py, subsub, "assert subsub.method3() == 3000") | ||||||
| ``` | ||||||
|
|
||||||
| To access the super class, you can use either of these two ways: | ||||||
| - Use `self_: &PyCell<Self>` instead of `self`, and call `get_super()` | ||||||
|
There was a problem hiding this comment. I find it a bit confusing that only There was a problem hiding this comment. Oops, this was left unchanged... thanks |
||||||
| - `ObjectProtocol::get_base` | ||||||
| We recommend `PyCell` here, since it makes the context much clearer. | ||||||
|
There was a problem hiding this comment. Maybe we can simply remove |
||||||
|
|
||||||
|
|
||||||
| If `SubClass` does not provide a baseclass initialization, the compilation fails. | ||||||
| ```compile_fail | ||||||
| # use pyo3::prelude::*; | ||||||
| use pyo3::PyCell; | ||||||
|
|
||||||
| #[pyclass] | ||||||
| struct BaseClass { | ||||||
|
|
@@ -761,16 +780,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>>` | ||||||
|
There was a problem hiding this comment. I liked that PyRefMut was replaced with PyClassShell since I find PyRef/PyRefMut unintuitive for reasons mentioned in #356 |
||||||
| * `fn __next__(slf: PyRefMut<Self>) -> PyResult<Option<impl IntoPy<PyObject>>>` | ||||||
|
|
||||||
| Returning `Ok(None)` from `__next__` indicates that that there are no further items. | ||||||
|
|
||||||
| Example: | ||||||
|
|
||||||
| ```rust | ||||||
| use pyo3::prelude::*; | ||||||
| use pyo3::{PyIterProtocol, PyCell}; | ||||||
|
|
||||||
| #[pyclass] | ||||||
| struct MyIterator { | ||||||
|
|
@@ -779,19 +798,15 @@ struct MyIterator { | |||||
|
|
||||||
| #[pyproto] | ||||||
| impl PyIterProtocol for MyIterator { | ||||||
| fn __iter__(mut slf: PyRefMut<Self>) -> PyResult<Py<MyIterator>> { | ||||||
| Ok(slf.into()) | ||||||
| } | ||||||
| fn __next__(mut slf: PyRefMut<Self>) -> PyResult<Option<PyObject>> { | ||||||
| Ok(slf.iter.next()) | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ## How methods are implemented | ||||||
|
|
||||||
| Users should be able to define a `#[pyclass]` with or without `#[pymethods]`, while PyO3 needs a | ||||||
|
|
||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.