Add the ability to specify a config to validators (#323)

This adds the ability to specify a `Config` data class to validators
when creating them. Prior to this PR, validators could be created one of
two ways:

* via a module-level singleton.
```python
import protovalidate
protovalidate.validate(msg)
```

* via explicit instantiation of the validator. i.e.
```python
import protovalidate

validator = protovalidate.Validator()
validator.validate(msg)
```

With this PR, it is now possible to create a validator with a `Config`
object, specifying various options (only `fail_fast` for now) for
configuring a validator. To use a config, users must explicitly
instantiate a validator and specify their config. They cannot use the
module singleton as this only allows for a default validator.

For example:

```python
import protovalidate
from protovalidate.config import Config

cfg = Config(fail_fast=True)
validator = protovalidate.Validator(config=cfg)

validator.validate(msg)
```

**This PR is a breaking change**. As a result of the above, the
`fail_fast` parameters have been removed from the signatures for
`validate` and `collect_violations`. Users should instead use the above
config method to specify `fail_fast`.

This also adds a bit more depth to the `validate_test` unit tests by
testing creation of a default validator via the module and via explicit
instantiation. It also tests that the violations returned by
`collect_violations` and raises as part of the exception returned from
`validate` are the same.

Author: smaye81

gen/tests/example/v1/validations_pb2.py

@@ -19,6 +19,11 @@ package tests.example.v1;
 import "buf/validate/validate.proto";
 import "google/protobuf/timestamp.proto";
 
+message MultipleValidations {
+  string title = 1 [(buf.validate.field).string.prefix = "foo"];
+  string name = 2 [(buf.validate.field).string.min_len = 5];
+}
+
 message DoubleFinite {
   double val = 1 [(buf.validate.field).double.finite = true];
 }

gen/tests/example/v1/validations_pb2.pyi

@@ -12,15 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from protovalidate import validator
+from protovalidate import config, validator
 
+Config = config.Config
 Validator = validator.Validator
 CompilationError = validator.CompilationError
 ValidationError = validator.ValidationError
 Violations = validator.Violations
 
-_validator = Validator()
-validate = _validator.validate
-collect_violations = _validator.collect_violations
+_default_validator = Validator()
+validate = _default_validator.validate
+collect_violations = _default_validator.collect_violations
 
-__all__ = ["CompilationError", "ValidationError", "Validator", "Violations", "collect_violations", "validate"]
+__all__ = ["CompilationError", "Config", "ValidationError", "Validator", "Violations", "collect_violations", "validate"]

proto/tests/example/v1/validations.proto

@@ -0,0 +1,26 @@
+# Copyright 2023-2025 Buf Technologies, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    """A class for holding configuration values for validation.
+
+    Attributes:
+        fail_fast (bool): If true, validation will stop after the first violation. Defaults to False.
+    """
+
+    fail_fast: bool = False

protovalidate/__init__.py

@@ -21,6 +21,7 @@
 from google.protobuf import any_pb2, descriptor, message, message_factory
 
 from buf.validate import validate_pb2  # type: ignore
+from protovalidate.config import Config
 from protovalidate.internal.cel_field_presence import InterpretedRunner, in_has
 
 
@@ -266,15 +267,17 @@ def __init__(self, *, field_value: typing.Any = None, rule_value: typing.Any = N
 class RuleContext:
     """The state associated with a single rule evaluation."""
 
-    def __init__(self, *, fail_fast: bool = False, violations: typing.Optional[list[Violation]] = None):
-        self._fail_fast = fail_fast
+    _cfg: Config
+
+    def __init__(self, *, config: Config, violations: typing.Optional[list[Violation]] = None):
+        self._cfg = config
         if violations is None:
             violations = []
         self._violations = violations
 
     @property
     def fail_fast(self) -> bool:
-        return self._fail_fast
+        return self._cfg.fail_fast
 
     @property
     def violations(self) -> list[Violation]:
@@ -296,13 +299,13 @@ def add_rule_path_elements(self, elements: typing.Iterable[validate_pb2.FieldPat
 
     @property
     def done(self) -> bool:
-        return self._fail_fast and self.has_errors()
+        return self.fail_fast and self.has_errors()
 
     def has_errors(self) -> bool:
         return len(self._violations) > 0
 
     def sub_context(self):
-        return RuleContext(fail_fast=self._fail_fast)
+        return RuleContext(config=self._cfg)
 
 
 class Rules:

protovalidate/config.py

@@ -17,6 +17,7 @@
 from google.protobuf import message
 
 from buf.validate import validate_pb2  # type: ignore
+from protovalidate.config import Config
 from protovalidate.internal import extra_func
 from protovalidate.internal import rules as _rules
 
@@ -35,28 +36,28 @@ class Validator:
     """
 
     _factory: _rules.RuleFactory
+    _cfg: Config
 
-    def __init__(self):
+    def __init__(self, config=None):
         self._factory = _rules.RuleFactory(extra_func.EXTRA_FUNCS)
+        self._cfg = config if config is not None else Config()
 
     def validate(
         self,
         message: message.Message,
-        *,
-        fail_fast: bool = False,
     ):
         """
         Validates the given message against the static rules defined in
         the message's descriptor.
 
         Parameters:
             message: The message to validate.
-            fail_fast: If true, validation will stop after the first violation.
         Raises:
             CompilationError: If the static rules could not be compiled.
-            ValidationError: If the message is invalid.
+            ValidationError: If the message is invalid. The violations raised as part of this error should
+            always be equal to the list of violations returned by `collect_violations`.
         """
-        violations = self.collect_violations(message, fail_fast=fail_fast)
+        violations = self.collect_violations(message)
         if len(violations) > 0:
             msg = f"invalid {message.DESCRIPTOR.name}"
             raise ValidationError(msg, violations)
@@ -65,24 +66,25 @@ def collect_violations(
         self,
         message: message.Message,
         *,
-        fail_fast: bool = False,
         into: typing.Optional[list[Violation]] = None,
     ) -> list[Violation]:
         """
         Validates the given message against the static rules defined in
-        the message's descriptor. Compared to validate, collect_violations is
-        faster but puts the burden of raising an appropriate exception on the
-        caller.
+        the message's descriptor. Compared to `validate`, `collect_violations` simply
+        returns the violations as a list and puts the burden of raising an appropriate
+        exception on the caller.
+
+        The violations returned from this method should always be equal to the violations
+        raised as part of the ValidationError in the call to `validate`.
 
         Parameters:
             message: The message to validate.
-            fail_fast: If true, validation will stop after the first violation.
             into: If provided, any violations will be appended to the
                 Violations object and the same object will be returned.
         Raises:
             CompilationError: If the static rules could not be compiled.
         """
-        ctx = _rules.RuleContext(fail_fast=fail_fast, violations=into)
+        ctx = _rules.RuleContext(config=self._cfg, violations=into)
         for rule in self._factory.get(message.DESCRIPTOR):
             rule.validate(ctx, message)
             if ctx.done:

protovalidate/internal/rules.py

@@ -0,0 +1,23 @@
+# Copyright 2023-2025 Buf Technologies, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+from protovalidate import Config
+
+
+class TestConfig(unittest.TestCase):
+    def test_defaults(self):
+        cfg = Config()
+        self.assertFalse(cfg.fail_fast)