Merge pull request #25300 from timhoffm/doc-check-dtype

ngoldbaum · web-flow · commit 15211edc733c · 2023-12-03T16:41:45.000-07:00
DOC: Document how to check for a specific dtype
diff --git a/doc/source/reference/arrays.dtypes.rst b/doc/source/reference/arrays.dtypes.rst
@@ -469,6 +469,50 @@ Type strings
        >>> dt = np.dtype(('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')]))
 
 
+Checking the data type
+======================
+When checking for a specific data type, use ``==`` comparison.
+
+.. admonition:: Example
+
+   >>> a = np.array([1, 2], dtype=np.float32)
+   >>> a.dtype == np.float32
+   True
+
+As opposed to python types, a comparison using ``is`` should not be used.
+
+First, NumPy treats data type specifications (everything that can be passed to
+the :class:`dtype` constructor) as equivalent to the data type object itself.
+This equivalence can only be handled through ``==``, not through ``is``.
+
+.. admonition:: Example
+
+   A :class:`dtype` object is equal to all data type specifications that are
+   equivalent to it.
+
+   >>> a = np.array([1, 2], dtype=float)
+   >>> a.dtype == np.dtype(np.float64)
+   True
+   >>> a.dtype == np.float64
+   True
+   >>> a.dtype == float
+   True
+   >>> a.dtype == "float64"
+   True
+   >>> a.dtype == "d"
+   True
+
+Second, there is no guarantee that data type objects are singletons.
+
+.. admonition:: Example
+
+   Do not use ``is`` because data type objects may or may not be singletons.
+
+   >>> np.dtype(float) is np.dtype(float)
+   True
+   >>> np.dtype([('a', float)]) is np.dtype([('a', float)])
+   False
+
 :class:`dtype`
 ==============
 
