DOC: Fix docs that cause an integer overflow

seberg · seberg · commit afd0b3067ab4 · 2023-09-28T14:41:30.000+02:00
diff --git a/doc/source/user/basics.creation.rst b/doc/source/user/basics.creation.rst
@@ -43,13 +43,18 @@ When you use :func:`numpy.array` to define a new array, you should
 consider the :doc:`dtype <basics.types>` of the elements in the array,
 which can be specified explicitly. This feature gives you
 more control over the underlying data structures and how the elements
-are handled in C/C++ functions. If you are not careful with ``dtype``
-assignments, you can get unwanted overflow, as such 
+are handled in C/C++ functions.
+When values do not fit and you are using a ``dtype`` NumPy may raise an
+error::
 
-::
+  >>> np.array([127, 128, 129], dtype=np.int8)
+  Traceback (most recent call last):
+  ...
+  OverflowError: Python integer 128 out of bounds for int8
+
+However, NumPy integers are force-cast and may silently overflow::
 
-  >>> a = np.array([127, 128, 129], dtype=np.int8)
-  >>> a
+  >>> np.array([127, np.int64(128), np.int64(129)], dtype=np.int8)
   array([ 127, -128, -127], dtype=int8)
 
 An 8-bit signed integer represents integers from -128 to 127.
