API: Always allow sorted=False and make a note about it

User intent for `sorted=False` is very clear, so I think we can
really just allow it.
However, note in the docs that it could change.  Also add a bigger
note in the `unique_*` functions that still always return a sorted
result but would change in the future (whenever `sorted=False` does
work).

Author: seberg

numpy/lib/_arraysetops_impl.py

@@ -186,7 +186,9 @@ def unique(ar, return_index=False, return_inverse=False,
         .. versionadded:: 1.24
 
     sorted : bool, optional
-        If True, the unique elements are sorted.
+        If True, the unique elements are sorted. Elements may be sorted in
+        practice even if ``sorted=False``, but this could change without
+        notice.
 
         .. versionadded:: 2.3
 
@@ -361,12 +363,6 @@ def _unique1d(ar, return_index=False, return_inverse=False,
 
     optional_indices = return_index or return_inverse
 
-    if (optional_indices or return_counts) and not sorted:
-        raise ValueError(
-            "Currently, `sorted` can only be False if `return_index`, "
-            "`return_inverse`, and `return_counts` are all False."
-        )
-
     # masked arrays are not supported yet.
     if not optional_indices and not return_counts and not np.ma.is_masked(ar):
         # First we convert the array to a numpy array, later we wrap it back
@@ -448,10 +444,14 @@ def unique_all(x):
     This function is an Array API compatible alternative to::
 
         np.unique(x, return_index=True, return_inverse=True,
-                  return_counts=True, equal_nan=False)
+                  return_counts=True, equal_nan=False, sorted=False)
 
     but returns a namedtuple for easier access to each output.
 
+    .. note::
+        This function currently always returns a sorted result, however,
+        this could change in any NumPy minor release.
+
     Parameters
     ----------
     x : array_like
@@ -507,10 +507,14 @@ def unique_counts(x):
 
     This function is an Array API compatible alternative to::
 
-        np.unique(x, return_counts=True, equal_nan=False)
+        np.unique(x, return_counts=True, equal_nan=False, sorted=False)
 
     but returns a namedtuple for easier access to each output.
 
+    .. note::
+        This function currently always returns a sorted result, however,
+        this could change in any NumPy minor release.
+
     Parameters
     ----------
     x : array_like
@@ -559,10 +563,14 @@ def unique_inverse(x):
 
     This function is an Array API compatible alternative to::
 
-        np.unique(x, return_inverse=True, equal_nan=False)
+        np.unique(x, return_inverse=True, equal_nan=False, sorted=False)
 
     but returns a namedtuple for easier access to each output.
 
+    .. note::
+        This function currently always returns a sorted result, however,
+        this could change in any NumPy minor release.
+
     Parameters
     ----------
     x : array_like

numpy/lib/tests/test_arraysetops.py

@@ -838,14 +838,19 @@ class Subclass(np.ndarray):
 
     @pytest.mark.parametrize("arg", ["return_index", "return_inverse", "return_counts"])
     def test_unsupported_hash_based(self, arg):
-        """Test that hash based unique is not supported when either of
-        return_index, return_inverse, or return_counts is True.
+        """These currently never use the hash-based solution.  However,
+        it seems easier to just allow it.
 
-        This is WIP and the above will gradually be supported in the future.
+        When the hash-based solution is added, this test should fail and be
+        replaced with something more comprehensive.
         """
-        msg = "Currently, `sorted` can only be False"
-        with pytest.raises(ValueError, match=msg):
-            np.unique([1, 1], sorted=False, **{arg: True})
+        a = np.array([1, 5, 2, 3, 4, 8, 199, 1, 3, 5])
+
+        res_not_sorted = np.unique([1, 1], sorted=False, **{arg: True})
+        res_sorted = np.unique([1, 1], sorted=True, **{arg: True})
+        # The following should fail without first sorting `res_not_sorted`.
+        for arr, expected in zip(res_not_sorted, res_sorted):
+            assert_array_equal(arr, expected)
 
     def test_unique_axis_errors(self):
         assert_raises(TypeError, self._run_axis_tests, object)