Sample and dtype validation (#1966)

This pull request introduces improvements to type safety, validation,
and schema handling for experimental dataset fields, with updates across
core modules and tests. The main changes include stricter type
validation for sample attributes, standardized handling of `dtype` for
fields, and updates to tests to reflect these improvements.

**Validation and Type Safety Enhancements**

* Added a `validate()` method to the `Sample` class to check attribute
presence and type correctness against the inferred schema, including
support for `Union` and `Callable` types. Validation is now called after
initialization.
[[1]](diffhunk://#diff-4ac196ddc4dc8e6d33daf684ded18886ff8774fadb8b6cbd4bfa88ca424bb34fL38-R41)
[[2]](diffhunk://#diff-4ac196ddc4dc8e6d33daf684ded18886ff8774fadb8b6cbd4bfa88ca424bb34fR51-R90)
* Improved attribute type validation logic to correctly handle complex
types such as `Union` and `Callable`.

**Field `dtype` Standardization**

* Updated the `Field` base class to ensure that `dtype` is always a
Polars `DataType` instance, converting from a class if necessary and
raising an error for invalid types.
* All field subclasses now explicitly declare their `dtype` using
`field(default_factory=...)` or `field(default=..., init=False)`,
ensuring consistent and correct schema generation.
[[1]](diffhunk://#diff-3098d9e238cfbc0a11faa65960430fbaadedc13fc8181e6042c44550eceff117R47-R58)
[[2]](diffhunk://#diff-3098d9e238cfbc0a11faa65960430fbaadedc13fc8181e6042c44550eceff117R138)
[[3]](diffhunk://#diff-25a01cfa1cd0bc6a78e628327b4eb8a1953cfda02cae490190eb57037b68960eR132)
[[4]](diffhunk://#diff-25a01cfa1cd0bc6a78e628327b4eb8a1953cfda02cae490190eb57037b68960eR178-R180)
[[5]](diffhunk://#diff-25a01cfa1cd0bc6a78e628327b4eb8a1953cfda02cae490190eb57037b68960eR235)
[[6]](diffhunk://#diff-25a01cfa1cd0bc6a78e628327b4eb8a1953cfda02cae490190eb57037b68960eR280)
[[7]](diffhunk://#diff-2a524f5523ceb4ac2f8edce7fcbff9268da416a550e2166ef455df966a2eb9b0L171-R171)
[[8]](diffhunk://#diff-2a524f5523ceb4ac2f8edce7fcbff9268da416a550e2166ef455df966a2eb9b0L243-R243)

**Schema and Serialization Improvements**

* The `from_dict` method for fields now skips non-init dataclass fields
during deserialization, preventing errors from fields that shouldn't be
set via the constructor.

**Test Suite Updates**

* Updated integration and unit tests to use explicit types for
callable/image/mask fields, replacing `Any` with more precise unions
(e.g., `np.ndarray | Callable[[], np.ndarray]`). This strengthens type
checking and reflects the stricter validation logic.
[[1]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L73-R73)
[[2]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L164-R164)
[[3]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L206-R208)
[[4]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L247-R247)
[[5]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L304-R304)
[[6]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L361-R361)
[[7]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L408-R408)
[[8]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L476-R476)
[[9]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L554-R554)
[[10]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L664-R664)
[[11]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L695-R695)
[[12]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L828-R833)
* Added a new unit test to verify correct validation and conversion of
field `dtype`, including error handling for invalid types.

**General Codebase Maintenance**

* Added missing imports and minor refactoring for clarity and
correctness in test and core files.
[[1]](diffhunk://#diff-4ac196ddc4dc8e6d33daf684ded18886ff8774fadb8b6cbd4bfa88ca424bb34fR7-R9)
[[2]](diffhunk://#diff-3098d9e238cfbc0a11faa65960430fbaadedc13fc8181e6042c44550eceff117L5-R11)
[[3]](diffhunk://#diff-f7d8d115b4530c510a92b0dbc1a1174ca351f0c2767fd8137a2da599fff8b484R7)
[[4]](diffhunk://#diff-f7d8d115b4530c510a92b0dbc1a1174ca351f0c2767fd8137a2da599fff8b484R54)
[[5]](diffhunk://#diff-e1e501a8f398cfac69ca16099abb40dd54bd830d7a4eeb3c2d765af75c5f6e00R1)
[[6]](diffhunk://#diff-ef7ef70a007f9bb0c6cf01021e927c6bbd39fbe5164b830620b9abb4d11ee354L16-R16)

These changes collectively improve the robustness and maintainability of
the experimental dataset system, especially around schema definition,
attribute validation, and field type safety.
<!-- Contributing guide:
https://github.com/open-edge-platform/datumaro/blob/develop/contributing.md
-->

<!--
Please add a summary of changes. You may use Copilot to auto-generate
the PR description but please consider including any other relevant
facts which Copilot may be unaware of (such as design choices and
testing procedure).

Add references to the relevant issues and pull requests if any like so:

Resolves #111 and #222.
Depends on #1000 (for series of dependent commits).
-->
Resolves #1855 

### Checklist
<!-- Put an 'x' in all the boxes that apply -->
- [x] I have added tests to cover my changes or documented any manual
tests.
- [ ] I have updated the
[documentation](https://github.com/open-edge-platform/datumaro/tree/develop/docs)
accordingly

---------

Signed-off-by: Jort Bergfeld <[email protected]>

Author: JortBergfeld

src/datumaro/experimental/converters/image_converters.py

@@ -106,7 +106,7 @@ def filter_output_spec(self) -> bool:
             name=self.output_image.name,
             field=ImageField(
                 semantic=self.input_image.field.semantic,
-                dtype=pl.Float32,
+                dtype=pl.Float32(),
                 format=self.input_image.field.format,
                 channels_first=self.output_image.field.channels_first,
             ),
@@ -161,7 +161,7 @@ def filter_output_spec(self) -> bool:
             name=self.output_image.name,
             field=ImageField(
                 semantic=self.input_path.field.semantic,
-                dtype=pl.UInt8,  # Default to UInt8 for loaded images
+                dtype=pl.UInt8(),  # Default to UInt8 for loaded images
                 format="RGB",  # Default to RGB format
                 channels_first=self.output_image.field.channels_first,
             ),
@@ -275,7 +275,7 @@ def filter_output_spec(self) -> bool:
             name=self.output_image.name,
             field=ImageField(
                 semantic=self.input_bytes.field.semantic,
-                dtype=pl.UInt8,  # Default to UInt8 for decoded images
+                dtype=pl.UInt8(),  # Default to UInt8 for decoded images
                 format="RGB",  # Default to RGB format
                 channels_first=self.output_image.field.channels_first,
             ),
@@ -342,7 +342,7 @@ def filter_output_spec(self) -> bool:
             name=self.output_image.name,
             field=ImageField(
                 semantic=self.input_callable.field.semantic,
-                dtype=pl.UInt8,  # Default to UInt8 for image data
+                dtype=pl.UInt8(),  # Default to UInt8 for image data
                 format=self.input_callable.field.format,  # Use format from callable field
                 channels_first=self.output_image.field.channels_first,
             ),

src/datumaro/experimental/converters/mask_converters.py

@@ -153,7 +153,7 @@ def apply_conversion_batch(batch_df: pl.DataFrame) -> pl.DataFrame:
 
             return pl.struct(
                 pl.Series(results_batch_polygons).alias("mask"),
-                pl.Series(results_batch_shape, dtype=pl.List(pl.Int32)).alias("shape"),
+                pl.Series(results_batch_shape, dtype=pl.List(pl.Int32())).alias("shape"),
                 eager=True,
             )
 
@@ -165,7 +165,7 @@ def apply_conversion_batch(batch_df: pl.DataFrame) -> pl.DataFrame:
             ]
         ).map_batches(
             apply_conversion_batch,
-            return_dtype=pl.Struct({"mask": pl.List(pl.UInt8), "shape": pl.List(pl.Int32)}),
+            return_dtype=pl.Struct({"mask": pl.List(pl.UInt8()), "shape": pl.List(pl.Int32())}),
         )
 
         return df.with_columns(
@@ -282,7 +282,7 @@ def apply_conversion_batch(batch_df: pl.DataFrame, **kwargs) -> pl.DataFrame:  #
 
             return pl.struct(
                 pl.Series(results_batch_mask).alias("mask"),
-                pl.Series(results_batch_shape, dtype=pl.List(pl.Int32)).alias("shape"),
+                pl.Series(results_batch_shape, dtype=pl.List(pl.Int32())).alias("shape"),
                 eager=True,
             )
 
@@ -294,7 +294,7 @@ def apply_conversion_batch(batch_df: pl.DataFrame, **kwargs) -> pl.DataFrame:  #
         ).map_batches(
             apply_conversion_batch,
             return_dtype=pl.Struct(
-                {"mask": pl.List(self.output_instance_mask.field.dtype), "shape": pl.List(pl.Int32)}
+                {"mask": pl.List(self.output_instance_mask.field.dtype), "shape": pl.List(pl.Int32())}
             ),
         )
 

src/datumaro/experimental/dataset.py

@@ -4,7 +4,9 @@
 
 from __future__ import annotations
 
+import collections.abc
 import types
+import typing
 from functools import cache
 from typing import TYPE_CHECKING, Annotated, Any, Generic, TypeGuard, Union, cast, get_args, get_origin, get_type_hints
 
@@ -35,8 +37,8 @@ def __init__(self, **kwargs: Any):
         """Initialize sample with provided attributes."""
         for key, value in kwargs.items():
             setattr(self, key, value)
-
         self.__post_init__()
+        self.validate()
 
     def __post_init__(self) -> None:
         pass
@@ -46,6 +48,46 @@ def __repr__(self):
         fields = ", ".join(f"{key}={getattr(self, key)}" for key in self.__dict__ if not key.startswith("_"))
         return f"{self.__class__.__name__}({fields})"
 
+    def validate(self) -> None:
+        """
+        Validate the sample's attributes against the inferred schema.
+
+        Raises:
+            ValueError: If required attributes are missing
+            TypeError: If attribute types do not match the schema
+        """
+        schema = self.__class__.infer_schema()  # Cached per class
+        for name, attr_info in schema.attributes.items():
+            if name not in self.__dict__:
+                continue
+            value = getattr(self, name)
+            expected_type = attr_info.type
+            field = attr_info.field
+
+            if not self._validate_attribute_type(expected_type, value):
+                raise TypeError(f"Attribute `{name}` must be of type `{expected_type}`.")
+
+            # Custom field validation (if any)
+            if hasattr(field, "validate"):
+                field.validate(value)
+
+    def _validate_attribute_type(self, expected_type: Any, value: Any) -> bool:
+        """
+        Recursively validate attribute type, handling Union and Callable types.
+        """
+        # Union and Callable types have to be handled separately,
+        # because isinstance() does not work with Callable types.
+        origin = get_origin(expected_type)
+        if origin is Union:
+            # Check each type in the Union
+            return any(self._validate_attribute_type(typ, value) for typ in get_args(expected_type))
+        if origin in {typing.Callable, collections.abc.Callable} or expected_type in {
+            typing.Callable,
+            collections.abc.Callable,
+        }:
+            return callable(value)
+        return isinstance(value, expected_type)
+
     @classmethod
     @cache
     def infer_schema(cls) -> Schema:

src/datumaro/experimental/export_import.py

@@ -393,10 +393,10 @@ def _update_dataframe_with_field(
     if is_path_field:
         if field_name in df.columns:
             df = df.drop(field_name)
-        return df.with_columns(pl.Series(field_name, values, dtype=pl.String))
+        return df.with_columns(pl.Series(field_name, values, dtype=pl.String()))
     if field_name in df.columns:
         return df.with_columns(pl.Series(field_name, values))
-    return df.with_columns(pl.Series(field_name, values, dtype=pl.Object))
+    return df.with_columns(pl.Series(field_name, values, dtype=pl.Object()))
 
 
 def _reconstruct_image_fields(
@@ -430,7 +430,7 @@ def _add_missing_object_columns(
     """Add back any object columns that weren't reconstructed from images."""
     for col_name in object_columns:
         if col_name not in df.columns:
-            df = df.with_columns(pl.Series(col_name, [None] * len(df), dtype=pl.Object))
+            df = df.with_columns(pl.Series(col_name, [None] * len(df), dtype=pl.Object()))
     return df
 
 

src/datumaro/experimental/fields/annotations.py

@@ -6,7 +6,7 @@
 
 import polars as pl
 
-from datumaro.experimental.fields.base import Field, PolarsDataType, Semantic, T, convert_numpy_object_array_to_series
+from datumaro.experimental.fields.base import Field, Semantic, T, convert_numpy_object_array_to_series
 from datumaro.experimental.type_registry import from_polars_data, to_numpy
 
 
@@ -26,7 +26,7 @@ class BBoxField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     format: str = "x1y1x2y2"
     normalize: bool = False
 
@@ -95,7 +95,7 @@ class RotatedBBoxField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     format: str = "cxcywhr"
     normalize: bool = False
 
@@ -159,7 +159,7 @@ class LabelField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.UInt8)
+    dtype: pl.DataType = field(default_factory=pl.UInt8)
     multi_label: bool = False  # Flag to indicate if this field should handle multi-labels
     is_list: bool = False
 
@@ -217,7 +217,7 @@ class ScoreField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     is_list: bool = False
 
     @property
@@ -276,7 +276,7 @@ class PolygonField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     format: str = "xy"
     normalize: bool = False
 
@@ -335,7 +335,7 @@ class KeypointsField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     normalize: bool = False
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
@@ -395,7 +395,7 @@ class EllipseField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.Float32)
+    dtype: pl.DataType = field(default_factory=pl.Float32)
     format: str = "x1y1x2y2"
     normalize: bool = False
 

src/datumaro/experimental/fields/base.py

@@ -12,15 +12,13 @@
 from dataclasses import fields as dataclass_fields
 from dataclasses import is_dataclass
 from enum import Flag, auto
-from typing import Any, TypeAlias, TypeVar
+from typing import Any, TypeVar
 
 import numpy as np
 import polars as pl
 
 T = TypeVar("T")
 
-PolarsDataType: TypeAlias = type[pl.DataType] | pl.DataType
-
 
 class Semantic(Flag):
     """
@@ -48,6 +46,17 @@ class Field:
     """
 
     semantic: Semantic
+    dtype: pl.DataType
+
+    def __post_init__(self):
+        dtype = getattr(self, "dtype")
+        if isinstance(dtype, type) and issubclass(dtype, pl.DataType):
+            raise TypeError(
+                f"dtype must be a Polars 'DataType' (instance), not a Polars 'DataTypeClass' (type). "
+                f"Make sure your dtype declaration uses parentheses ({dtype.__name__}() instead of {dtype.__name__})"
+            )
+        if not isinstance(dtype, pl.DataType):
+            raise TypeError(f"dtype must be a Polars 'DataType', got '{dtype.__name__}' instead.")
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """
@@ -165,6 +174,9 @@ def from_dict(cls, field_dict: dict[str, Any]) -> "Field":
         # Use dataclass introspection to get all expected fields
         if is_dataclass(field_class):
             for dc_field in dataclass_fields(field_class):
+                if not dc_field.init:
+                    continue  # Skip fields that are not in __init__
+
                 field_name = dc_field.name
 
                 # Skip if not in the serialized data

src/datumaro/experimental/fields/datasets.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: MIT
 import types
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum, auto
 from typing import Any, Union, get_args, get_origin
 
@@ -44,6 +44,18 @@ class TileField(Field):
     """
 
     semantic: Semantic
+    dtype: pl.DataType = field(
+        default_factory=lambda: pl.Struct(
+            [
+                pl.Field("source_sample_idx", pl.Int32()),
+                pl.Field("x", pl.Int32()),
+                pl.Field("y", pl.Int32()),
+                pl.Field("width", pl.Int32()),
+                pl.Field("height", pl.Int32()),
+            ]
+        ),
+        init=False,
+    )
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Generate Polars schema for tile information."""
@@ -123,6 +135,7 @@ class SubsetField(Field):
 
     semantic: Semantic
     categories: list[str] | None = None
+    dtype: pl.DataType = field(default_factory=pl.Categorical, init=False)
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Generate schema with categorical type for subset values."""
@@ -141,7 +154,7 @@ def to_polars(self, name: str, value: Any) -> dict[str, pl.Series]:
             polars_value = str(value)
 
         # Create categorical series with predefined categories if available
-        return {name: pl.Series(name, [polars_value], dtype=pl.Categorical)}
+        return {name: pl.Series(name, [polars_value], dtype=pl.Categorical())}
 
     def from_polars(self, name: str, row_index: int, df: pl.DataFrame, target_type: type[T]) -> T:
         """Reconstruct subset value from Polars data.

src/datumaro/experimental/fields/images.py

@@ -7,7 +7,7 @@
 import numpy as np
 import polars as pl
 
-from datumaro.experimental.fields.base import Field, PolarsDataType, Semantic, T
+from datumaro.experimental.fields.base import Field, Semantic, T
 from datumaro.experimental.type_registry import from_polars_data, to_numpy
 
 
@@ -26,7 +26,7 @@ class TensorField(Field):
     """
 
     semantic: Semantic
-    dtype: PolarsDataType = field(default_factory=pl.UInt8)
+    dtype: pl.DataType = field(default_factory=pl.UInt8)
     channels_first: bool = False
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
@@ -129,6 +129,7 @@ class ImageBytesField(Field):
     """
 
     semantic: Semantic
+    dtype: pl.DataType = field(default_factory=pl.Binary, init=False)
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Generate schema for image bytes as binary data."""
@@ -174,6 +175,9 @@ class ImageInfoField(Field):
     """
 
     semantic: Semantic
+    dtype: pl.DataType = field(
+        default_factory=lambda: pl.Struct([pl.Field("width", pl.Int32()), pl.Field("height", pl.Int32())]), init=False
+    )
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         return {
@@ -228,6 +232,7 @@ class ImagePathField(Field):
     """
 
     semantic: Semantic
+    dtype: pl.DataType = field(default_factory=pl.String, init=False)
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Generate schema for string path column."""
@@ -272,10 +277,11 @@ class ImageCallableField(Field):
 
     semantic: Semantic
     format: str = "RGB"
+    dtype: pl.DataType = field(default_factory=pl.Object, init=False)
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Return schema with Object type to store callable."""
-        return {name: pl.Object}
+        return {name: pl.Object()}
 
     def to_polars(self, name: str, value: callable) -> dict[str, pl.Series]:
         """Store callable as Object in Polars series."""