class validators

Wauplin · Wauplin · commit 27ca2d712cca · 2025-05-14T16:18:55.000+02:00
diff --git a/docs/source/en/package_reference/dataclasses.md b/docs/source/en/package_reference/dataclasses.md
@@ -36,29 +36,49 @@ def positive_int(value: int):
 @dataclass
 class Config:
     model_type: str
-    hidden_size: int = positive_int(default=32)
-    vocab_size: int = 16  # Default value
+    hidden_size: int = positive_int(default=16)
+    vocab_size: int = 32  # Default value
+
+    def validate_big_enough_vocab(self):
+        if self.vocab_size < self.hidden_size:
+            raise ValueError(f"vocab_size ({self.vocab_size}) must be greater than hidden_size ({self.hidden_size})")
 ```
 
 Fields are validated during initialization:
 
 ```python
-config = Config(model_type="bert", hidden_size=768)  # Valid
+config = Config(model_type="bert", hidden_size=24)   # Valid
 config = Config(model_type="bert", hidden_size=-1)   # Raises StrictDataclassFieldValidationError
 ```
 
+Consistency between fields is also validated during initialization (class-wise validation):
+
+```python
+# `vocab_size` too small compared to `hidden_size`
+config = Config(model_type="bert", hidden_size=32, vocab_size=16)   # Raises StrictDataclassClassValidationError
+```
+
 Fields are also validated during assignment:
 
 ```python
 config.hidden_size = 512  # Valid
 config.hidden_size = -1   # Raises StrictDataclassFieldValidationError
 ```
 
+To re-run class-wide validation after assignment, you must call `.validate` explicitly:
+
+```python
+config.validate()  # Runs all class validators
+```
+
 ### Custom Validators
 
 You can attach multiple custom validators to fields using [`validated_field`]. A validator is a callable that takes a single argument and raises an exception if the value is invalid.
 
 ```python
+from dataclasses import dataclass
+from huggingface_hub.dataclasses import strict, validated_field
+
 def multiple_of_64(value: int):
     if value % 64 != 0:
         raise ValueError(f"Value must be a multiple of 64, got {value}")
@@ -76,6 +96,9 @@ In this example, both validators are applied to the `hidden_size` field.
 By default, strict dataclasses only accept fields defined in the class. You can allow additional keyword arguments by setting `accept_kwargs=True` in the `@strict` decorator.
 
 ```python
+from dataclasses import dataclass
+from huggingface_hub.dataclasses import strict
+
 @strict(accept_kwargs=True)
 @dataclass
 class ConfigWithKwargs:
@@ -94,6 +117,8 @@ Strict dataclasses respect type hints and validate them automatically. For examp
 
 ```python
 from typing import List
+from dataclasses import dataclass
+from huggingface_hub.dataclasses import strict
 
 @strict
 @dataclass
@@ -116,6 +141,42 @@ Supported types include:
 
 And any combination of these types.
 
+### Class validators
+
+Methods named `validate_xxx` are treated as class validators. These methods must only take `self` as an argument. Class validators are run once during initialization, right after `__post_init__`. You can define as many of them as needed—they'll be executed sequentially in the order they appear.
+
+Note that class validators are not automatically re-run when a field is updated after initialization. To manually re-validate the object, you need to call `obj.validate()`.
+
+```py
+from dataclasses import dataclass
+from huggingface_hub.dataclasses import strict
+
+@strict
+@dataclass
+class Config:
+    foo: str
+    foo_length: int
+    upper_case: bool = False
+
+    def validate_foo_length(self):
+        if len(self.foo) != self.foo_length:
+            raise ValueError(f"foo must be {self.foo_length} characters long, got {len(self.foo)}")
+
+    def validate_foo_casing(self):
+        if self.upper_case and self.foo.upper() != self.foo:
+            raise ValueError(f"foo must be uppercase, got {self.foo}")
+
+config = Config(foo="bar", foo_length=3) # ok
+
+config.upper_case = True
+config.validate() # Raises StrictDataclassFieldValidationError
+
+Config(foo="abcd", foo_length=3) # Raises StrictDataclassFieldValidationError
+Config(foo="Bar", foo_length=3, upper_case=True) # Raises StrictDataclassFieldValidationError
+
+
+```
+
 ## API Reference
 
 ### `@strict`
diff --git a/src/huggingface_hub/dataclasses.py b/src/huggingface_hub/dataclasses.py
@@ -17,7 +17,11 @@
     overload,
 )
 
-from .errors import StrictDataclassDefinitionError, StrictDataclassFieldValidationError
+from .errors import (
+    StrictDataclassClassValidationError,
+    StrictDataclassDefinitionError,
+    StrictDataclassFieldValidationError,
+)
 
 
 Validator_T = Callable[[Any], None]
@@ -174,6 +178,46 @@ def __repr__(self) -> str:
 
             cls.__repr__ = __repr__  # type: ignore [method-assign]
 
+        # List all public methods starting with `validate_` => class validators.
+        class_validators = []
+        if hasattr(cls, "__class_validators__"):
+            # If inheriting from a class with class validators, add them to the list
+            class_validators += cls.__class_validators__  # type: ignore [attr-defined]
+
+        for name, method in cls.__dict__.items():
+            if name.startswith("validate_") and callable(method):
+                if len(inspect.signature(method).parameters) != 1:
+                    raise StrictDataclassDefinitionError(
+                        f"Class '{cls.__name__}' has a class validator '{name}' that takes more than one argument."
+                        " Class validators must take only 'self' as an argument. Methods starting with 'validate_'"
+                        " are considered to be class validators."
+                    )
+                class_validators.append(method)
+
+        cls.__class_validators__ = class_validators  # type: ignore [attr-defined]
+
+        # Add `validate` method to the class
+        def validate(self: T) -> None:
+            """Run class validators on the instance."""
+            for validator in cls.__class_validators__:  # type: ignore [attr-defined]
+                try:
+                    validator(self)
+                except (ValueError, TypeError) as e:
+                    raise StrictDataclassClassValidationError(validator=validator.__name__, cause=e) from e
+
+        cls.validate = validate  # type: ignore
+
+        # Run class validators after initialization
+        initial_init = cls.__init__
+
+        @wraps(initial_init)
+        def init_with_validate(self, *args, **kwargs) -> None:
+            """Run class validators after initialization."""
+            initial_init(self, *args, **kwargs)  # type: ignore [call-arg]
+            cls.validate(self)  # type: ignore [attr-defined]
+
+        setattr(cls, "__init__", init_with_validate)
+
         return cls
 
     # Return wrapped class or the decorator itself
@@ -441,6 +485,7 @@ def _is_validator(validator: Any) -> bool:
     "strict",
     "validated_field",
     "Validator_T",
+    "StrictDataclassClassValidationError",
     "StrictDataclassDefinitionError",
     "StrictDataclassFieldValidationError",
 ]
diff --git a/src/huggingface_hub/errors.py b/src/huggingface_hub/errors.py
@@ -349,6 +349,15 @@ def __init__(self, field: str, cause: Exception):
         super().__init__(error_message)
 
 
+class StrictDataclassClassValidationError(StrictDataclassError):
+    """Exception thrown when a strict dataclass fails validation on a class validator."""
+
+    def __init__(self, validator: str, cause: Exception):
+        error_message = f"Class validation error for validator '{validator}':"
+        error_message += f"\n    {cause.__class__.__name__}: {cause}"
+        super().__init__(error_message)
+
+
 # XET ERRORS
 
 
diff --git a/tests/test_utils_strict_dataclass.py b/tests/test_utils_strict_dataclass.py
@@ -6,7 +6,11 @@
 import pytest
 
 from huggingface_hub.dataclasses import _is_validator, as_validated_field, strict, type_validator, validated_field
-from huggingface_hub.errors import StrictDataclassDefinitionError, StrictDataclassFieldValidationError
+from huggingface_hub.errors import (
+    StrictDataclassClassValidationError,
+    StrictDataclassDefinitionError,
+    StrictDataclassFieldValidationError,
+)
 
 
 def positive_int(value: int):
@@ -441,3 +445,96 @@ def test_strict_requires_dataclass():
         @strict
         class InvalidConfig:
             model_type: str
+
+
+class TestClassValidation:
+    @strict
+    @dataclass
+    class ParentConfig:
+        foo: str = "bar"
+        foo_length: int = 3
+
+        def validate_foo_length(self):
+            if len(self.foo) != self.foo_length:
+                raise ValueError(f"foo must be {self.foo_length} characters long, got {len(self.foo)}")
+
+    @strict
+    @dataclass
+    class ChildConfig(ParentConfig):
+        number: int = 42
+
+        def validate_number_multiple_of_foo_length(self):
+            if self.number % self.foo_length != 0:
+                raise ValueError(f"number must be a multiple of foo_length ({self.foo_length}), got {self.number}")
+
+    @strict
+    @dataclass
+    class OtherChildConfig(ParentConfig):
+        number: int = 42
+
+    @strict
+    @dataclass
+    class ChildConfigWithPostInit(ParentConfig):
+        def __post_init__(self):
+            # Let's assume post_init doubles each value
+            # Validation is ran AFTER __post_init__
+            self.foo = self.foo * 2
+            self.foo_length = self.foo_length * 2
+
+    def test_parent_config_validation(self):
+        # Test valid initialization
+        config = self.ParentConfig(foo="bar", foo_length=3)
+        assert config.foo == "bar"
+        assert config.foo_length == 3
+
+        # Test invalid initialization
+        with pytest.raises(StrictDataclassClassValidationError):
+            self.ParentConfig(foo="bar", foo_length=4)
+
+    def test_child_config_validation(self):
+        # Test valid initialization
+        config = self.ChildConfig(foo="bar", foo_length=3, number=42)
+        assert config.foo == "bar"
+        assert config.foo_length == 3
+        assert config.number == 42
+
+        # Test invalid initialization
+        with pytest.raises(StrictDataclassClassValidationError):
+            self.ChildConfig(foo="bar", foo_length=4, number=40)
+
+        with pytest.raises(StrictDataclassClassValidationError):
+            self.ChildConfig(foo="bar", foo_length=3, number=43)
+
+    def test_other_child_config_validation(self):
+        # Test valid initialization
+        config = self.OtherChildConfig(foo="bar", foo_length=3, number=43)
+        assert config.foo == "bar"
+        assert config.foo_length == 3
+        assert config.number == 43  # not validated => did not fail
+
+        # Test invalid initialization
+        with pytest.raises(StrictDataclassClassValidationError):
+            self.OtherChildConfig(foo="bar", foo_length=4, number=42)
+
+    def test_validate_after_init(self):
+        # Test valid initialization
+        config = self.ParentConfig(foo="bar", foo_length=3)
+
+        # Attributes can be updated after initialization
+        config.foo = "abcd"
+        config.foo_length = 4
+        config.validate()  # Explicit call required
+
+        # Explicit validation fails
+        config.foo_length = 5
+        with pytest.raises(StrictDataclassClassValidationError):
+            config.validate()
+
+    def test_validation_runs_after_post_init(self):
+        config = self.ChildConfigWithPostInit(foo="bar", foo_length=3)
+        assert config.foo == "barbar"
+        assert config.foo_length == 6
+
+        with pytest.raises(StrictDataclassClassValidationError, match="foo must be 4 characters long, got 6"):
+            # post init doubles the value and then the validation fails
+            self.ChildConfigWithPostInit(foo="bar", foo_length=2)
