Remove unsound custom element example.

Author: adamreichold

src/dtype.rs

@@ -169,7 +169,7 @@ impl DataType {
 
 /// Represents that a type can be an element of `PyArray`.
 ///
-/// Currently, only integer/float/complex types are supported.
+/// Currently, only integer/float/complex/object types are supported.
 /// If you come up with a nice implementation for some other types, we're happy to receive your PR :)
 /// You may refer to the [numpy document](https://numpy.org/doc/stable/reference/c-api/dtype.html#enumerated-types)
 /// for all types that numpy supports.
@@ -184,38 +184,9 @@ impl DataType {
 ///
 /// # Custom element types
 ///
-/// You can implement this trait to manage arrays of custom element types, but they still need to be stored
-/// on Python's heap using PyO3's [Py](pyo3::Py) type.
-///
-/// ```
-/// use numpy::{ndarray::Array2, DataType, Element, PyArray, PyArrayDescr, ToPyArray};
-/// use pyo3::{pyclass, Py, Python};
-///
-/// #[pyclass]
-/// pub struct CustomElement;
-///
-/// // The transparent wrapper is necessary as one cannot implement
-/// // a foreign trait (`Element`) on a foreign type (`Py`) directly.
-/// #[derive(Clone)]
-/// #[repr(transparent)]
-/// pub struct Wrapper(pub Py<CustomElement>);
-///
-/// unsafe impl Element for Wrapper {
-///     const DATA_TYPE: DataType = DataType::Object;
-///
-///     fn is_same_type(dtype: &PyArrayDescr) -> bool {
-///         dtype.get_datatype() == Some(DataType::Object)
-///     }
-/// }
-///
-/// Python::with_gil(|py| {
-///     let array = Array2::<Wrapper>::from_shape_fn((2, 3), |(_i, _j)| {
-///         Wrapper(Py::new(py, CustomElement).unwrap())
-///     });
-///
-///     let _array: &PyArray<Wrapper, _> = array.to_pyarray(py);
-/// });
-/// ```
+/// Note that it is currently not possible to safely store custom element types of the form `Py<T>` with `T: PyClass`
+/// as we only check the data type during downcasting and not the dynamic type of each element stored in the array.
+/// Therefore, the only safe type to store in object arrays is `Py<PyAny>` also known as `PyObject` for now.
 pub unsafe trait Element: Clone + Send {
     /// `DataType` corresponding to this type.
     const DATA_TYPE: DataType;