NEP: Make a note of Python integer "exceptions"

seberg · seberg · commit 5b2207ec449b · 2024-01-24T11:17:47.000+01:00
These are not really exceptions to the rules, but may look like
exceptions when compared to the behavior of other operations.

Also briefly notes that we should probably aspire to allowing such
"exceptions", but I don't think we should be beholden to make it
possible in every case (some of these are non-trivial to make work!).

Also added one sentence that this applies to everything of course.
diff --git a/doc/neps/nep-0050-scalar-promotion.rst b/doc/neps/nep-0050-scalar-promotion.rst
@@ -163,6 +163,9 @@ following hold::
     True + np.uint8(2) == np.uint8(3)
 
 
+Note that while this NEP uses simple operators as example, the rules described
+generally apply to all of NumPy operations.
+
 Table comparing new and old behaviour
 -------------------------------------
 
@@ -401,6 +404,27 @@ It will then continue to do the calculation with ``inf`` as usual.
    set up to raise an error due to the overflow, however).
    It is also for example the behaviour of ``pytorch`` 1.10.
 
+Particular behavior of Python integers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The NEPs promotion rules stated in terms of the resulting dtype which is
+typically also the operation dtype (in terms of result precision).
+This leads to what may seem like exceptions for Python integers:
+While ``uint8(3) + 1000`` must be rejected because operating
+in ``uint8`` is not possible, ``uint8(3) / 1000`` returns a ``float64`` and
+can convert both inputs to ``float64`` to find the result.
+
+In practice this means that arbitrary Python integer values are accepted in
+the following cases:
+* All comparisons (``==``, ``<``, etc.) between NumPy and Python integers are
+  always well defined.
+* Unary functions like ``np.sqrt`` that give a floating point result can and
+  will convert the Python integer to a float.
+* Division of integers returns floating point by casting input to ``float64``.
+
+Note that there may be additional functions where these exceptions could be
+applied but are not.  In these cases it should be considered an improvement
+to allow them, but when the user impact is low we may not do so for simplicity.
 
 
 Backward compatibility
