chore: clarify comments and error messages for generic annotations

Author: georgeh0

python/cocoindex/tests/test_typing.py

@@ -539,5 +539,8 @@ def test_invalid_list_kind() -> None:
 
 def test_unsupported_type() -> None:
     typ = set
-    with pytest.raises(ValueError, match="type unsupported yet: <class 'set'>"):
+    with pytest.raises(
+        ValueError,
+        match="Unsupported as a specific type annotation for CocoIndex data type.*: <class 'set'>",
+    ):
         analyze_type_info(typ)

python/cocoindex/typing.py

@@ -169,7 +169,7 @@ class AnalyzedTypeInfo:
 def analyze_type_info(t: Any) -> AnalyzedTypeInfo:
     """
     Analyze a Python type annotation and extract CocoIndex-specific type information.
-    Only concrete CocoIndex type annotations are supported. Raises ValueError for Any, empty, or untyped dict types.
+    Type annotations for specific CocoIndex types are expected. Raises ValueError for Any, empty, or untyped dict types.
     """
     if isinstance(t, tuple) and len(t) == 2:
         kt, vt = t
@@ -240,11 +240,12 @@ def analyze_type_info(t: Any) -> AnalyzedTypeInfo:
         _ = DtypeRegistry.validate_dtype_and_get_kind(elem_type)
         vector_info = VectorInfo(dim=None) if vector_info is None else vector_info
 
-    elif base_type is collections.abc.Mapping or base_type is dict:
+    elif base_type is collections.abc.Mapping or base_type is dict or t is dict:
         args = typing.get_args(t)
         if len(args) == 0:  # Handle untyped dict
             raise ValueError(
-                "Untyped dict is not supported; please provide a concrete type, e.g., dict[str, Any]."
+                "Untyped dict is not accepted as a specific type annotation; please provide a concrete type, "
+                "e.g. a dataclass or namedtuple for Struct types, a dict[str, T] for KTable types."
             )
         else:
             elem_type = (args[0], args[1])
@@ -288,12 +289,10 @@ def analyze_type_info(t: Any) -> AnalyzedTypeInfo:
             kind = "OffsetDateTime"
         elif t is datetime.timedelta:
             kind = "TimeDelta"
-        elif t is dict:
+        else:
             raise ValueError(
-                "Untyped dict is not supported; please provide a concrete type, e.g., dict[str, Any]."
+                f"Unsupported as a specific type annotation for CocoIndex data type (https://cocoindex.io/docs/core/data_types): {t}"
             )
-        else:
-            raise ValueError(f"type unsupported yet: {t}")
 
     return AnalyzedTypeInfo(
         kind=kind,