DOC: Update np.unique_all example to demonstrate namedtuple output (numpy#27385)

Update docstrings for unique_* functions to emphasize
nametuple outputs

Co-authored-by: Ross Barnowski <[email protected]>

Author: t-tasin

numpy/lib/_arraysetops_impl.py

@@ -412,14 +412,14 @@ def _unique_all_dispatcher(x, /):
 @array_function_dispatch(_unique_all_dispatcher)
 def unique_all(x):
     """
-    Find the unique elements of an array, and counts, inverse and indices.
+    Find the unique elements of an array, and counts, inverse, and indices.
 
-    This function is an Array API compatible alternative to:
+    This function is an Array API compatible alternative to::
 
-    >>> x = np.array([1, 1, 2])
-    >>> np.unique(x, return_index=True, return_inverse=True,
-    ...           return_counts=True, equal_nan=False)
-    (array([1, 2]), array([0, 2]), array([0, 0, 1]), array([2, 1]))
+        np.unique(x, return_index=True, return_inverse=True,
+                  return_counts=True, equal_nan=False)
+
+    but returns a namedtuple for easier access to each output.
 
     Parameters
     ----------
@@ -444,12 +444,16 @@ def unique_all(x):
     Examples
     --------
     >>> import numpy as np
-    >>> np.unique_all([1, 1, 2])
-    UniqueAllResult(values=array([1, 2]),
-                    indices=array([0, 2]),
-                    inverse_indices=array([0, 0, 1]),
-                    counts=array([2, 1]))
-
+    >>> x = [1, 1, 2]
+    >>> uniq = np.unique_all(x)
+    >>> uniq.values
+    array([1, 2])
+    >>> uniq.indices
+    array([0, 2])
+    >>> uniq.inverse_indices
+    array([0, 0, 1])
+    >>> uniq.counts
+    array([2, 1])
     """
     result = unique(
         x,
@@ -470,11 +474,11 @@ def unique_counts(x):
     """
     Find the unique elements and counts of an input array `x`.
 
-    This function is an Array API compatible alternative to:
+    This function is an Array API compatible alternative to::
 
-    >>> x = np.array([1, 1, 2])
-    >>> np.unique(x, return_counts=True, equal_nan=False)
-    (array([1, 2]), array([2, 1]))
+        np.unique(x, return_counts=True, equal_nan=False)
+
+    but returns a namedtuple for easier access to each output.
 
     Parameters
     ----------
@@ -496,9 +500,12 @@ def unique_counts(x):
     Examples
     --------
     >>> import numpy as np
-    >>> np.unique_counts([1, 1, 2])
-    UniqueCountsResult(values=array([1, 2]), counts=array([2, 1]))
-
+    >>> x = [1, 1, 2]
+    >>> uniq = np.unique_counts(x)
+    >>> uniq.values
+    array([1, 2])
+    >>> uniq.counts
+    array([2, 1])
     """
     result = unique(
         x,
@@ -519,11 +526,11 @@ def unique_inverse(x):
     """
     Find the unique elements of `x` and indices to reconstruct `x`.
 
-    This function is Array API compatible alternative to:
+    This function is an Array API compatible alternative to::
+
+        np.unique(x, return_inverse=True, equal_nan=False)
 
-    >>> x = np.array([1, 1, 2])
-    >>> np.unique(x, return_inverse=True, equal_nan=False)
-    (array([1, 2]), array([0, 0, 1]))
+    but returns a namedtuple for easier access to each output.
 
     Parameters
     ----------
@@ -546,9 +553,12 @@ def unique_inverse(x):
     Examples
     --------
     >>> import numpy as np
-    >>> np.unique_inverse([1, 1, 2])
-    UniqueInverseResult(values=array([1, 2]), inverse_indices=array([0, 0, 1]))
-
+    >>> x = [1, 1, 2]
+    >>> uniq = np.unique_inverse(x)
+    >>> uniq.values
+    array([1, 2])
+    >>> uniq.inverse_indices
+    array([0, 0, 1])
     """
     result = unique(
         x,
@@ -569,11 +579,9 @@ def unique_values(x):
     """
     Returns the unique elements of an input array `x`.
 
-    This function is Array API compatible alternative to:
+    This function is an Array API compatible alternative to::
 
-    >>> x = np.array([1, 1, 2])
-    >>> np.unique(x, equal_nan=False)
-    array([1, 2])
+        np.unique(x, equal_nan=False)
 
     Parameters
     ----------