Add utilities for Struct-like checks (#950)

Author: ofek

docs/api.rst

@@ -140,6 +140,8 @@ Inspect
 
 .. currentmodule:: msgspec.inspect
 
+.. autofunction:: is_struct
+.. autofunction:: is_struct_type
 .. autofunction:: type_info
 .. autofunction:: multi_type_info
 .. autoclass:: Type

docs/changelog.md

@@ -4,6 +4,7 @@
 
 - Support Python 3.14, including freethreaded mode ({pr}`852`, {pr}`877`).
 - Expose the `StructMeta` metaclass ({pr}`890`, {pr}`927`, {pr}`928`, {pr}`940`, {pr}`945`).
+- Add `msgspec.inspect.is_struct` and `msgspec.inspect.is_struct_type` functions for checking whether an object is a `msgspec.Struct`-like instance or class ({pr}`950`).
 - Support Windows `arm64` builds ({pr}`943`).
 - Enable ThinLTO on macOS `aarch64` builds ({pr}`937`).
 - Fix leaks of `re.Pattern` objects when using `pattern` constraints of `msgspec.Meta` ({pr}`899`).

src/msgspec/_typing_utils.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from . import StructMeta
+
+
+def is_struct(obj: object) -> bool:
+    """Check whether ``obj`` is a `msgspec.Struct`-like instance.
+
+    Parameters
+    ----------
+    obj:
+        Object to check.
+
+    Returns
+    -------
+    bool
+        `True` if ``obj`` is an instance of a class whose metaclass is
+        `msgspec.StructMeta` (or a subclass of it), and `False` otherwise.
+        Static type checkers treat a successful ``is_struct(obj)`` check as
+        narrowing ``obj`` to `msgspec.Struct` within the true branch, even if
+        the runtime class does not literally inherit `msgspec.Struct`.
+    """
+    return isinstance(type(obj), StructMeta)
+
+
+def is_struct_type(tp: object) -> bool:
+    """Check whether ``tp`` is a `msgspec.Struct`-like class.
+
+    Parameters
+    ----------
+    tp:
+        Object to check, typically a class object.
+
+    Returns
+    -------
+    bool
+        `True` if ``tp`` is a class whose metaclass is `msgspec.StructMeta`
+        (or a subclass of it), and `False` otherwise. Static type checkers
+        treat a successful ``is_struct_type(tp)`` check as narrowing
+        ``tp`` to `type[msgspec.Struct]` within the true branch.
+    """
+    return isinstance(tp, StructMeta)

src/msgspec/_typing_utils.pyi

@@ -0,0 +1,6 @@
+from typing_extensions import TypeGuard
+
+from . import Struct
+
+def is_struct(obj: object) -> TypeGuard[Struct]: ...
+def is_struct_type(tp: object) -> TypeGuard[type[Struct]]: ...

src/msgspec/inspect.py

@@ -32,6 +32,7 @@
     Factory as _Factory,
     to_builtins as _to_builtins,
 )
+from ._typing_utils import is_struct, is_struct_type
 from ._utils import (  # type: ignore
     _CONCRETE_TYPES,
     _AnnotatedAlias,
@@ -78,6 +79,8 @@
     "NamedTupleType",
     "DataclassType",
     "StructType",
+    "is_struct",
+    "is_struct_type",
 )
 
 
@@ -674,10 +677,6 @@ def _origin_args_metadata(t):
     return origin, args, tuple(metadata)
 
 
-def _is_struct(t):
-    return isinstance(t, msgspec.StructMeta)
-
-
 def _is_enum(t):
     return type(t) is enum.EnumMeta
 
@@ -889,7 +888,7 @@ def _translate_inner(
             return LiteralType(tuple(sorted(args)))
         elif _is_enum(t):
             return EnumType(t)
-        elif _is_struct(t):
+        elif is_struct_type(t):
             cls = t[args] if args else t
             if cls in self.cache:
                 return self.cache[cls]

tests/typing/basic_typing_examples.py

@@ -1070,6 +1070,40 @@ def check_consume_inspect_types() -> None:
     reveal_type(t.includes_none)  # assert "bool" in typ.lower()
 
 
+def check_inspect_is_struct() -> None:
+    class Point(msgspec.Struct):
+        x: int
+
+    obj: object = Point(1)
+    if msgspec.inspect.is_struct(obj):
+        reveal_type(obj)  # assert "Struct" in typ
+    else:
+        reveal_type(obj)  # assert "Struct" not in typ
+
+    ns: object = object()
+    if msgspec.inspect.is_struct(ns):
+        reveal_type(ns)  # assert "Struct" in typ
+    else:
+        reveal_type(ns)  # assert "Struct" not in typ
+
+
+def check_inspect_is_struct_type() -> None:
+    class Point(msgspec.Struct):
+        x: int
+
+    tp: type[Any] = Point
+    if msgspec.inspect.is_struct_type(tp):
+        reveal_type(tp)  # assert "type" in typ and "Struct" in typ
+    else:
+        reveal_type(tp)  # assert "Struct" not in typ
+
+    other: type[Any] = type("NotStruct", (), {})
+    if msgspec.inspect.is_struct_type(other):
+        reveal_type(other)  # assert "Struct" in typ
+    else:
+        reveal_type(other)  # assert "Struct" not in typ
+
+
 ##########################################################
 # JSON Schema                                            #
 ##########################################################

tests/unit/test_inspect.py

@@ -815,3 +815,61 @@ class Model(Base):
         array_like=False,
         forbid_unknown_fields=False,
     )
+
+
+def test_is_struct_runtime():
+    class Base(msgspec.Struct):
+        x: int
+
+    class Derived(Base):
+        pass
+
+    Generated = msgspec.defstruct("InspectStructRuntime", ["x"])
+
+    class CustomMeta(msgspec.StructMeta):
+        pass
+
+    class CustomBase(metaclass=CustomMeta):
+        x: int
+
+    class Custom(CustomBase):
+        pass
+
+    class NotStruct:
+        pass
+
+    assert mi.is_struct(Base(1))
+    assert mi.is_struct(Derived(1))
+    assert mi.is_struct(Generated(1))
+    assert mi.is_struct(Custom(1))
+    assert not mi.is_struct(NotStruct())
+    assert not mi.is_struct(object())
+
+
+def test_is_struct_type_runtime():
+    class Base(msgspec.Struct):
+        x: int
+
+    class Derived(Base):
+        pass
+
+    Generated = msgspec.defstruct("InspectStructTypeRuntime", ["x"])
+
+    class CustomMeta(msgspec.StructMeta):
+        pass
+
+    class CustomBase(metaclass=CustomMeta):
+        pass
+
+    class Custom(CustomBase):
+        x: int
+
+    class NotStruct:
+        pass
+
+    assert mi.is_struct_type(Base)
+    assert mi.is_struct_type(Derived)
+    assert mi.is_struct_type(Generated)
+    assert mi.is_struct_type(Custom)
+    assert not mi.is_struct_type(NotStruct)
+    assert not mi.is_struct_type(object)