Remove unsound custom element example.

While we do check the array data element during extract, we do not check the
type of the individual elements and hence there is no guarantee that they are of
type T or even of uniform type.

But if we did check each element, Python code having a reference the (base)
array could change the elements and thereby their types after our check leading
to type confusion in safe Rust code.

Author: adamreichold

src/dtype.rs

@@ -292,7 +292,7 @@ impl PyArrayDescr {
 
 /// 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.
@@ -310,38 +310,10 @@ impl PyArrayDescr {
 ///
 /// # 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, 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 IS_COPY: bool = false;
-///
-///     fn get_dtype(py: Python) -> &PyArrayDescr {
-///         PyArrayDescr::object(py)
-///     }
-/// }
-///
-/// 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 we cannot safely store `Py<T>` where `T: PyClass`, because the type information would be
+/// eliminated in the resulting NumPy array.
+/// In other words, objects are always treated as `Py<PyAny>` (a.k.a. `PyObject`) by Python code,
+/// and only `Py<PyAny>` can be stored in a type safe manner.
 pub unsafe trait Element: Clone + Send {
     /// Flag that indicates whether this type is trivially copyable.
     ///