From f8204f5e0f338ffad588e56704e596e6678dc4f4 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 8 Jun 2025 00:01:43 +0200
Subject: [PATCH] DOC: Document assertion comparison behavior between scalar
 and empty array

Noted in #27457. The minimal thing we should do is document this behavior.

While at it, I slightly homogenized the notes.
---
 numpy/testing/_private/utils.py | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/numpy/testing/_private/utils.py b/numpy/testing/_private/utils.py
index d7ceaeab72cc..9bc60d28b160 100644
--- a/numpy/testing/_private/utils.py
+++ b/numpy/testing/_private/utils.py
@@ -293,9 +293,10 @@ def assert_equal(actual, desired, err_msg='', verbose=True, *, strict=False):
 
     Notes
     -----
-    By default, when one of `actual` and `desired` is a scalar and the other is
-    an array, the function checks that each element of the array is equal to
-    the scalar. This behaviour can be disabled by setting ``strict==True``.
+    When one of `actual` and `desired` is a scalar and the other is array_like, the
+    function checks that each element of the array_like is equal to the scalar.
+    Note that empty arrays are therefore considered equal to scalars.
+    This behaviour can be disabled by setting ``strict==True``.
 
     Examples
     --------
@@ -980,9 +981,10 @@ def assert_array_equal(actual, desired, err_msg='', verbose=True, *,
 
     Notes
     -----
-    When one of `actual` and `desired` is a scalar and the other is array_like,
-    the function checks that each element of the array_like object is equal to
-    the scalar. This behaviour can be disabled with the `strict` parameter.
+    When one of `actual` and `desired` is a scalar and the other is array_like, the
+    function checks that each element of the array_like is equal to the scalar.
+    Note that empty arrays are therefore considered equal to scalars.
+    This behaviour can be disabled by setting ``strict==True``.
 
     Examples
     --------
@@ -1651,10 +1653,10 @@ def assert_allclose(actual, desired, rtol=1e-7, atol=0, equal_nan=True,
 
     Notes
     -----
-    When one of `actual` and `desired` is a scalar and the other is
-    array_like, the function performs the comparison as if the scalar were
-    broadcasted to the shape of the array.
-    This behaviour can be disabled with the `strict` parameter.
+    When one of `actual` and `desired` is a scalar and the other is array_like, the
+    function performs the comparison as if the scalar were broadcasted to the shape
+    of the array. Note that empty arrays are therefore considered equal to scalars.
+    This behaviour can be disabled by setting ``strict==True``.
 
     Examples
     --------