Support numpy StringDType in from_dtype

from_dtype now natively supports numpy 2.0+ variable-width strings
(StringDType, kind 'T'), generating arbitrary strings via text().

Passing a dtype class such as np.dtypes.StringDType where an instance
was expected now raises a clear error, instead of the previous confusing
message (or silent coercion to the object dtype in arrays).

Author: claude

hypothesis/RELEASE.rst

@@ -0,0 +1,10 @@
+RELEASE_TYPE: minor
+
+:func:`~hypothesis.extra.numpy.from_dtype` now supports the variable-width
+string dtype :attr:`numpy:numpy.dtypes.StringDType`, generating arbitrary
+strings via :func:`~hypothesis.strategies.text` (:issue:`4039`).
+
+Additionally, passing a dtype *class* such as ``np.dtypes.StringDType`` where an
+instance like ``np.dtypes.StringDType()`` was expected now raises a clear error,
+rather than the previous confusing message (or silent coercion to the object
+dtype in :func:`~hypothesis.extra.numpy.arrays`).

hypothesis/src/hypothesis/extra/numpy.py

@@ -110,6 +110,19 @@ def _try_import(mod_name: str, attr_name: str) -> Any:
 NP_FIXED_UNICODE = tuple(int(x) for x in np.__version__.split(".")[:2]) >= (1, 19)
 
 
+def _reject_dtype_class(dtype: object) -> None:
+    # A common mistake is to pass a dtype *class*, e.g. np.dtypes.StringDType,
+    # rather than an instance such as np.dtypes.StringDType().  numpy silently
+    # coerces such classes to the object dtype, so we reject them with a more
+    # helpful message than the resulting confusion further down the line.
+    if isinstance(dtype, type) and issubclass(dtype, np.dtype):
+        name = getattr(dtype, "__name__", repr(dtype))
+        raise InvalidArgument(
+            f"Cannot infer a strategy from the dtype class {name}; pass an "
+            f"instance instead, e.g. {name}() rather than {name}."
+        )
+
+
 @defines_strategy(force_reusable_values=True)
 def from_dtype(
     dtype: np.dtype,
@@ -137,6 +150,7 @@ def from_dtype(
     :func:`arrays` which allow a variety of numeric dtypes, as it seamlessly
     handles the ``width`` or representable bounds for you.
     """
+    _reject_dtype_class(dtype)
     check_type(np.dtype, dtype, "dtype")
     kwargs = {k: v for k, v in locals().items() if k != "dtype" and v is not None}
 
@@ -214,6 +228,14 @@ def compat_kw(*args, **kw):
         result = st.text(**compat_kw("alphabet", "min_size", max_size=max_size)).filter(
             lambda b: b[-1:] != "\0"
         )
+    elif dtype.kind == "T":
+        # NumPy 2.0+ variable-width strings (StringDType).  Unlike the fixed-width
+        # "U"/"S" dtypes, these store arbitrary Python strings with no length
+        # limit and no null-termination, so we can use st.text() directly - but
+        # the UTF-8 backing storage means we must exclude lone surrogates.
+        if "alphabet" not in kwargs:
+            kwargs["alphabet"] = st.characters(codec="utf-8")
+        result = st.text(**compat_kw("alphabet", "min_size", "max_size"))
     elif dtype.kind in ("m", "M"):
         if "[" in dtype.str:
             res = st.just(dtype.str.split("[")[-1][:-1])
@@ -555,6 +577,7 @@ def arrays(
             lambda s: arrays(dtype, s, elements=elements, fill=fill, unique=unique)
         )
     # From here on, we're only dealing with values and it's relatively simple.
+    _reject_dtype_class(dtype)
     dtype = np.dtype(dtype)  # type: ignore[arg-type]
     assert isinstance(dtype, np.dtype)  # help mypy out a bit...
     if elements is None or isinstance(elements, Mapping):

hypothesis/tests/numpy/test_from_dtype.py

@@ -23,6 +23,12 @@
 
 np_version = tuple(int(x) for x in np.__version__.split(".")[:2])
 
+skipif_no_stringdtype = pytest.mark.skipif(
+    not hasattr(getattr(np, "dtypes", None), "StringDType"),
+    reason="StringDType was added in NumPy 2.0",
+)
+
+
 STANDARD_TYPES = [
     np.dtype(t)
     for t in (
@@ -281,6 +287,42 @@ def test_float_subnormal_generation(allow_subnormal, width):
         assert_no_examples(strat, lambda n: -smallest_normal < n < smallest_normal)
 
 
+@skipif_no_stringdtype
+@given(st.data())
+def test_stringdtype_generates_strings(data):
+    dt = np.dtypes.StringDType()
+    result = data.draw(nps.from_dtype(dt))
+    assert isinstance(result, str)
+
+
+@skipif_no_stringdtype
+@given(st.data())
+def test_stringdtype_respects_kwargs(data):
+    dt = np.dtypes.StringDType()
+    result = data.draw(nps.from_dtype(dt, min_size=2, max_size=4, alphabet="abc"))
+    assert 2 <= len(result) <= 4
+    assert set(result).issubset("abc")
+
+
+@skipif_no_stringdtype
+@given(st.data())
+def test_stringdtype_arrays_roundtrip(data):
+    # StringDType stores arbitrary strings, so anything we generate (including
+    # null bytes and arbitrarily-long strings) must read back unchanged.
+    dt = np.dtypes.StringDType()
+    ex = data.draw(nps.from_dtype(dt))
+    arr = np.array([""], dtype=dt)
+    arr[0] = ex
+    assert arr[0] == ex
+
+
+@skipif_no_stringdtype
+@pytest.mark.parametrize("func", [nps.from_dtype, lambda dt: nps.arrays(dt, 3)])
+def test_helpful_error_on_uninstantiated_dtype_class(func):
+    with pytest.raises(InvalidArgument, match="dtype class StringDType"):
+        check_can_generate_examples(func(np.dtypes.StringDType))
+
+
 @pytest.mark.parametrize("allow_subnormal", [False, True])
 @pytest.mark.parametrize("width", [64, 128])
 def test_complex_subnormal_generation(allow_subnormal, width):