plain.postgres 0.99.1__tar.gz → 0.100.0__tar.gz

plain_postgres-0.99.1/plain/postgres/README.md → plain_postgres-0.100.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.100.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0,>=0.134.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Requires-Dist: sqlparse>=0.3.1
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -1003,7 +1017,7 @@ author.books.query.published()
 
 ### Validation
 
-You can validate models before saving:
+`save()` runs `full_clean()` by default — field validators, model `clean()`, and any constraints with a `validate()` method are all checked, raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads).
 
 ```python
 @postgres.register_model
@@ -1020,10 +1034,6 @@ class User(postgres.Model):
     def clean(self):
         if self.age < 18:
             raise ValidationError("User must be 18 or older")
-
-    def save(self, *args, **kwargs):
-        self.full_clean()  # Runs validation
-        super().save(*args, **kwargs)
 ```
 
 Field-level validation happens automatically based on field types and constraints.
@@ -1050,6 +1060,38 @@ class User(postgres.Model):
     )
 ```
 
+Constraints are also checked during `full_clean()` (which `save()` runs by default — see [Validation](#validation)). Pass `violation_error` to customize the resulting `ValidationError`. It accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, or a fully-formed `ValidationError`:
+
+```python
+# Simple message — lands on NON_FIELD_ERRORS
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error="Age must be zero or greater.",
+)
+
+# Dict form — routes to a specific field
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error={"age": "Age must be zero or greater."},
+)
+
+# Full ValidationError — for code, params, multiple fields
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error=ValidationError(
+        {"age": "Age must be zero or greater."},
+        code="age_negative",
+    ),
+)
+```
+
+A `code` becomes `ValidationError.code` — useful for test assertions, error tracking buckets, and code that branches on specific error types without string-matching.
+
+`UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
+
 ### Schema design
 
 #### Index fields used in filters and ordering

{plain_postgres-0.99.1 → plain_postgres-0.100.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,21 @@
 # plain-postgres changelog
 
+## [0.100.0](https://github.com/dropseed/plain/releases/plain-postgres@0.100.0) (2026-04-28)
+
+### What's changed
+
+- **Replaced the `violation_error_message` / `violation_error_code` triad on `CheckConstraint` and `UniqueConstraint` with a single `violation_error` kwarg.** The new kwarg accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, a list, or a fully-formed `ValidationError` — so message text, error code, and field routing all live on one object. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Single-field `UniqueConstraint` now auto-routes flat errors to its field.** A `violation_error="That email is taken."` on `UniqueConstraint(fields=["email"])` lands on the `email` form field instead of `NON_FIELD_ERRORS`. A caller-built `ValidationError({"other_field": ...})` is preserved as-is. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Dropped the hardcoded `code == "unique"` routing in `validate_constraints()`.** Routing is now uniform across constraint types: dict-form errors land on fields, flat errors go to `NON_FIELD_ERRORS`. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Removed the `%(name)s` interpolation magic** on `BaseConstraint.default_violation_error_message`. The default message still includes the constraint name; users wanting runtime interpolation can pass `ValidationError(..., params={"name": ...})`. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- Documented that `save()` runs `full_clean()` by default (`clean_and_validate=True`); fixed the README's Validation example which previously implied users had to override `save()` to call `full_clean()` manually. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+
+### Upgrade instructions
+
+- Replace `violation_error_message="..."` and `violation_error_code="..."` on `CheckConstraint` / `UniqueConstraint` with a single `violation_error=ValidationError("...", code="...")` (or a string if you only need the message).
+- If you relied on the implicit single-field-unique routing for a constraint with a custom `violation_error_code`, no change needed — single-field `UniqueConstraint` still auto-routes by default.
+- If you used `%(name)s` in `violation_error_message`, switch to `ValidationError("...", params={"name": "your_constraint_name"})` or hardcode the name.
+
 ## [0.99.1](https://github.com/dropseed/plain/releases/plain-postgres@0.99.1) (2026-04-26)
 
 ### What's changed

plain_postgres-0.99.1/PKG-INFO → plain_postgres-0.100.0/plain/postgres/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.99.1
-Summary: Model your data and store it in a database.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0,>=0.134.0
-Requires-Dist: psycopg-pool>=3.2
-Requires-Dist: psycopg>=3.2
-Requires-Dist: sqlparse>=0.3.1
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -1017,7 +1003,7 @@ author.books.query.published()
 
 ### Validation
 
-You can validate models before saving:
+`save()` runs `full_clean()` by default — field validators, model `clean()`, and any constraints with a `validate()` method are all checked, raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads).
 
 ```python
 @postgres.register_model
@@ -1034,10 +1020,6 @@ class User(postgres.Model):
     def clean(self):
         if self.age < 18:
             raise ValidationError("User must be 18 or older")
-
-    def save(self, *args, **kwargs):
-        self.full_clean()  # Runs validation
-        super().save(*args, **kwargs)
 ```
 
 Field-level validation happens automatically based on field types and constraints.
@@ -1064,6 +1046,38 @@ class User(postgres.Model):
     )
 ```
 
+Constraints are also checked during `full_clean()` (which `save()` runs by default — see [Validation](#validation)). Pass `violation_error` to customize the resulting `ValidationError`. It accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, or a fully-formed `ValidationError`:
+
+```python
+# Simple message — lands on NON_FIELD_ERRORS
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error="Age must be zero or greater.",
+)
+
+# Dict form — routes to a specific field
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error={"age": "Age must be zero or greater."},
+)
+
+# Full ValidationError — for code, params, multiple fields
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error=ValidationError(
+        {"age": "Age must be zero or greater."},
+        code="age_negative",
+    ),
+)
+```
+
+A `code` becomes `ValidationError.code` — useful for test assertions, error tracking buckets, and code that branches on specific error types without string-matching.
+
+`UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
+
 ### Schema design
 
 #### Index fields used in filters and ordering

{plain_postgres-0.99.1 → plain_postgres-0.100.0}/plain/postgres/base.py

@@ -812,19 +812,13 @@ class Model(metaclass=ModelBase):
     def validate_constraints(self, exclude: set[str] | None = None) -> None:
         constraints = self.get_constraints()
 
-        errors = {}
+        errors: dict[str, list[ValidationError]] = {}
         for model_class, model_constraints in constraints:
             for constraint in model_constraints:
                 try:
                     constraint.validate(model_class, self, exclude=exclude)
                 except ValidationError as e:
-                    if (
-                        getattr(e, "code", None) == "unique"
-                        and len(constraint.fields) == 1
-                    ):
-                        errors.setdefault(constraint.fields[0], []).append(e)
-                    else:
-                        errors = e.update_error_dict(errors)
+                    errors = e.update_error_dict(errors)
         if errors:
             raise ValidationError(errors)
 

{plain_postgres-0.99.1 → plain_postgres-0.100.0}/plain/postgres/constraints.py

@@ -28,25 +28,20 @@ if TYPE_CHECKING:
 __all__ = ["BaseConstraint", "CheckConstraint", "Deferrable", "UniqueConstraint"]
 
 
+ViolationError = str | dict[str, Any] | list[Any] | ValidationError
+
+
 class BaseConstraint:
-    default_violation_error_message = 'Constraint "%(name)s" is violated.'
-    violation_error_code: str | None = None
-    violation_error_message: str | None = None
+    violation_error: ViolationError | None = None
 
     def __init__(
         self,
         *,
         name: str,
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         self.name = name
-        if violation_error_code is not None:
-            self.violation_error_code = violation_error_code
-        if violation_error_message is not None:
-            self.violation_error_message = violation_error_message
-        else:
-            self.violation_error_message = self.default_violation_error_message
+        self.violation_error = violation_error
 
     @property
     def contains_expressions(self) -> bool:
@@ -64,21 +59,19 @@ class BaseConstraint:
             "subclasses of BaseConstraint must provide a validate() method"
         )
 
-    def get_violation_error_message(self) -> str:
-        assert self.violation_error_message is not None
-        return self.violation_error_message % {"name": self.name}
+    def _build_violation_error(self) -> ValidationError:
+        if self.violation_error is None:
+            return ValidationError(f'Constraint "{self.name}" is violated.')
+        if isinstance(self.violation_error, ValidationError):
+            return self.violation_error
+        return ValidationError(self.violation_error)
 
     def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
         path = f"{self.__class__.__module__}.{self.__class__.__name__}"
         path = path.replace("plain.postgres.constraints", "plain.postgres")
         kwargs: dict[str, Any] = {"name": self.name}
-        if (
-            self.violation_error_message is not None
-            and self.violation_error_message != self.default_violation_error_message
-        ):
-            kwargs["violation_error_message"] = self.violation_error_message
-        if self.violation_error_code is not None:
-            kwargs["violation_error_code"] = self.violation_error_code
+        if self.violation_error is not None:
+            kwargs["violation_error"] = self.violation_error
         return (path, (), kwargs)
 
     def clone(self) -> BaseConstraint:
@@ -92,19 +85,14 @@ class CheckConstraint(BaseConstraint):
         *,
         check: Q,
         name: str,
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         self.check = check
         if not getattr(check, "conditional", False):
             raise TypeError(
                 "CheckConstraint.check must be a Q instance or boolean expression."
             )
-        super().__init__(
-            name=name,
-            violation_error_code=violation_error_code,
-            violation_error_message=violation_error_message,
-        )
+        super().__init__(name=name, violation_error=violation_error)
 
     def to_sql(self, model: type[Model], *, not_valid: bool = False) -> str:
         """Generate ALTER TABLE ADD CONSTRAINT CHECK SQL as a plain string."""
@@ -122,27 +110,19 @@ class CheckConstraint(BaseConstraint):
         against = instance._get_field_value_map(meta=model._model_meta, exclude=exclude)
         try:
             if not Q(self.check).check(against):
-                raise ValidationError(
-                    self.get_violation_error_message(), code=self.violation_error_code
-                )
+                raise self._build_violation_error()
         except FieldError:
             pass
 
     def __repr__(self) -> str:
-        return "<{}: check={} name={}{}{}>".format(
+        return "<{}: check={} name={}{}>".format(
             self.__class__.__qualname__,
             self.check,
             repr(self.name),
             (
                 ""
-                if self.violation_error_code is None
-                else f" violation_error_code={self.violation_error_code!r}"
-            ),
-            (
-                ""
-                if self.violation_error_message is None
-                or self.violation_error_message == self.default_violation_error_message
-                else f" violation_error_message={self.violation_error_message!r}"
+                if self.violation_error is None
+                else f" violation_error={self.violation_error!r}"
             ),
         )
 
@@ -151,8 +131,7 @@ class CheckConstraint(BaseConstraint):
             return (
                 self.name == other.name
                 and self.check == other.check
-                and self.violation_error_code == other.violation_error_code
-                and self.violation_error_message == other.violation_error_message
+                and self.violation_error == other.violation_error
             )
         return super().__eq__(other)
 
@@ -183,8 +162,7 @@ class UniqueConstraint(BaseConstraint):
         deferrable: Deferrable | None = None,
         include: tuple[str, ...] | list[str] | None = None,
         opclasses: tuple[str, ...] | list[str] = (),
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         if not name:
             raise ValueError("A unique constraint must be named.")
@@ -234,11 +212,7 @@ class UniqueConstraint(BaseConstraint):
             F(expression) if isinstance(expression, str) else expression
             for expression in expressions
         )
-        super().__init__(
-            name=name,
-            violation_error_code=violation_error_code,
-            violation_error_message=violation_error_message,
-        )
+        super().__init__(name=name, violation_error=violation_error)
 
     @property
     def contains_expressions(self) -> bool:
@@ -299,7 +273,7 @@ class UniqueConstraint(BaseConstraint):
         return sql
 
     def __repr__(self) -> str:
-        return "<{}:{}{}{}{}{}{}{}{}{}>".format(
+        return "<{}:{}{}{}{}{}{}{}{}>".format(
             self.__class__.__qualname__,
             "" if not self.fields else f" fields={repr(self.fields)}",
             "" if not self.expressions else f" expressions={repr(self.expressions)}",
@@ -310,14 +284,8 @@ class UniqueConstraint(BaseConstraint):
             "" if not self.opclasses else f" opclasses={repr(self.opclasses)}",
             (
                 ""
-                if self.violation_error_code is None
-                else f" violation_error_code={self.violation_error_code!r}"
-            ),
-            (
-                ""
-                if self.violation_error_message is None
-                or self.violation_error_message == self.default_violation_error_message
-                else f" violation_error_message={self.violation_error_message!r}"
+                if self.violation_error is None
+                else f" violation_error={self.violation_error!r}"
             ),
         )
 
@@ -331,8 +299,7 @@ class UniqueConstraint(BaseConstraint):
                 and self.include == other.include
                 and self.opclasses == other.opclasses
                 and self.expressions == other.expressions
-                and self.violation_error_code == other.violation_error_code
-                and self.violation_error_message == other.violation_error_message
+                and self.violation_error == other.violation_error
             )
         return super().__eq__(other)
 
@@ -395,22 +362,7 @@ class UniqueConstraint(BaseConstraint):
             queryset = queryset.exclude(id=model_class_id)
         if not self.condition:
             if queryset.exists():
-                if self.expressions:
-                    raise ValidationError(
-                        self.get_violation_error_message(),
-                        code=self.violation_error_code,
-                    )
-                # When fields are defined, use the unique_error_message() for
-                # backward compatibility.
-                for constraint_model, constraints in instance.get_constraints():
-                    for constraint in constraints:
-                        if constraint is self:
-                            raise ValidationError(
-                                instance.unique_error_message(
-                                    constraint_model,
-                                    self.fields,
-                                ),
-                            )
+                raise self._build_unique_violation(instance, model)
         else:
             against = instance._get_field_value_map(
                 meta=model._model_meta, exclude=exclude
@@ -419,9 +371,32 @@ class UniqueConstraint(BaseConstraint):
                 if (self.condition & Exists(queryset.filter(self.condition))).check(
                     against
                 ):
-                    raise ValidationError(
-                        self.get_violation_error_message(),
-                        code=self.violation_error_code,
-                    )
+                    raise self._build_unique_violation(instance, model)
             except FieldError:
                 pass
+
+    def _build_unique_violation(
+        self, instance: Model, model: type[Model]
+    ) -> ValidationError:
+        """Build the ValidationError for a unique violation.
+
+        Single-field unique constraints route the error to that field via the
+        dict form so it surfaces under the field rather than NON_FIELD_ERRORS.
+        """
+        single_field = self.fields[0] if len(self.fields) == 1 else None
+
+        if self.violation_error is not None:
+            err = self._build_violation_error()
+            # Only auto-route flat errors. A ValidationError that already has
+            # an error_dict (from dict-form input or a caller-built instance)
+            # already declares its own field routing — don't override it.
+            if single_field and not hasattr(err, "error_dict"):
+                return ValidationError({single_field: [err]})
+            return err
+
+        if self.fields:
+            err = instance.unique_error_message(model, self.fields)
+            if single_field:
+                return ValidationError({single_field: [err]})
+            return err
+        return ValidationError(f'Constraint "{self.name}" is violated.')

{plain_postgres-0.99.1 → plain_postgres-0.100.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.99.1"
+version = "0.100.0"
 description = "Model your data and store it in a database."
 authors = [{ name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev" }]
 readme = "README.md"

plain_postgres-0.100.0/tests/test_constraint_violation_error.py

@@ -0,0 +1,216 @@
+"""Tests for the `violation_error` kwarg on CheckConstraint and
+UniqueConstraint, plus the full_clean() / save() integration that surfaces
+constraint errors."""
+
+from __future__ import annotations
+
+import pytest
+from app.examples.models.constraints import ConstraintExample
+
+from plain.exceptions import ValidationError
+from plain.postgres import CheckConstraint, Q, UniqueConstraint
+from plain.postgres.forms import ModelForm
+from plain.test import RequestFactory
+
+
+def _check_constraint() -> CheckConstraint:
+    return CheckConstraint(
+        check=Q(name__startswith="ok-"),
+        name="constraint_must_start_ok",
+        violation_error=ValidationError(
+            'Name must start with "ok-".', code="bad_prefix"
+        ),
+    )
+
+
+def _add_check_constraint(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        ConstraintExample.model_options,
+        "constraints",
+        (*ConstraintExample.model_options.constraints, _check_constraint()),
+    )
+
+
+def test_validate_uses_violation_error(db: None) -> None:
+    constraint = _check_constraint()
+    instance = ConstraintExample(name="bad", description="d")
+
+    with pytest.raises(ValidationError) as exc_info:
+        constraint.validate(ConstraintExample, instance)
+
+    err = exc_info.value.error_list[0]
+    assert err.message == 'Name must start with "ok-".'
+    assert err.code == "bad_prefix"
+
+
+def test_validate_string_violation_error(db: None) -> None:
+    constraint = CheckConstraint(
+        check=Q(name__startswith="ok-"),
+        name="c",
+        violation_error="bad name",
+    )
+    instance = ConstraintExample(name="bad", description="d")
+    with pytest.raises(ValidationError) as exc_info:
+        constraint.validate(ConstraintExample, instance)
+    assert exc_info.value.messages == ["bad name"]
+
+
+def test_validate_default_violation_error(db: None) -> None:
+    constraint = CheckConstraint(check=Q(name__startswith="ok-"), name="my_constraint")
+    instance = ConstraintExample(name="bad", description="d")
+    with pytest.raises(ValidationError) as exc_info:
+        constraint.validate(ConstraintExample, instance)
+    assert exc_info.value.messages == ['Constraint "my_constraint" is violated.']
+
+
+def test_validate_passes_when_check_satisfied(db: None) -> None:
+    constraint = _check_constraint()
+    instance = ConstraintExample(name="ok-fine", description="d")
+    constraint.validate(ConstraintExample, instance)
+
+
+def test_full_clean_runs_constraint_validation(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _add_check_constraint(monkeypatch)
+    instance = ConstraintExample(name="bad", description="d")
+    with pytest.raises(ValidationError) as exc_info:
+        instance.full_clean()
+    assert any("Name must start" in m for m in exc_info.value.messages)
+
+
+def test_save_runs_full_clean_by_default(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _add_check_constraint(monkeypatch)
+    with pytest.raises(ValidationError):
+        ConstraintExample(name="bad", description="d").save()
+    assert ConstraintExample.query.filter(name="bad").count() == 0
+
+
+def test_save_clean_and_validate_false_skips_validation(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _add_check_constraint(monkeypatch)
+    ConstraintExample(name="bad", description="d").save(clean_and_validate=False)
+    assert ConstraintExample.query.filter(name="bad").count() == 1
+
+
+def test_check_constraint_dict_violation_error_routes_to_field(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Dict-form violation_error attaches the error to the named field."""
+    constraint = CheckConstraint(
+        check=Q(name__startswith="ok-"),
+        name="must_start_ok",
+        violation_error={"name": 'Name must start with "ok-".'},
+    )
+    monkeypatch.setattr(
+        ConstraintExample.model_options,
+        "constraints",
+        (*ConstraintExample.model_options.constraints, constraint),
+    )
+
+    class Form(ModelForm):
+        class Meta:
+            model = ConstraintExample
+            fields = ["name", "description"]
+
+    rf = RequestFactory()
+    form = Form(request=rf.post("/x/", data={"name": "bad", "description": "d"}))
+    assert not form.is_valid()
+    assert form.errors.get("name"), form.errors
+    assert "name" in form.errors
+    assert "__all__" not in form.errors
+
+
+def test_check_constraint_string_violation_error_lands_on_non_field_errors(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A bare string violation_error on CheckConstraint goes to NON_FIELD_ERRORS
+    because the constraint can't infer which field to attach to from a Q
+    expression."""
+    constraint = CheckConstraint(
+        check=Q(name__startswith="ok-"),
+        name="must_start_ok",
+        violation_error='Name must start with "ok-".',
+    )
+    monkeypatch.setattr(
+        ConstraintExample.model_options,
+        "constraints",
+        (*ConstraintExample.model_options.constraints, constraint),
+    )
+
+    class Form(ModelForm):
+        class Meta:
+            model = ConstraintExample
+            fields = ["name", "description"]
+
+    rf = RequestFactory()
+    form = Form(request=rf.post("/x/", data={"name": "bad", "description": "d"}))
+    assert not form.is_valid()
+    assert "name" not in form.errors
+    assert "__all__" in form.errors
+
+
+def test_unique_constraint_explicit_validation_error_dict_preserved(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A caller-built ValidationError with an error_dict declares its own
+    field routing — single-field auto-routing must not flatten it back under
+    the constrained field."""
+    constraint = UniqueConstraint(
+        fields=["name"],
+        name="unique_name_explicit",
+        violation_error=ValidationError(
+            {"description": "Pick a different name to free this description."}
+        ),
+    )
+    monkeypatch.setattr(
+        ConstraintExample.model_options,
+        "constraints",
+        (*ConstraintExample.model_options.constraints, constraint),
+    )
+
+    ConstraintExample(name="dup", description="d1").save(clean_and_validate=False)
+    instance = ConstraintExample(name="dup", description="d2")
+
+    with pytest.raises(ValidationError) as exc_info:
+        instance.full_clean()
+
+    err = exc_info.value
+    assert hasattr(err, "error_dict")
+    assert "description" in err.error_dict
+    assert "name" not in err.error_dict
+
+
+def test_unique_constraint_single_field_string_routes_to_field(
+    db: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Single-field UniqueConstraint auto-routes a string violation_error to
+    that field (no special routing in validate_constraints — the dict-form is
+    built inside validate())."""
+    constraint = UniqueConstraint(
+        fields=["name"],
+        name="unique_name_only",
+        violation_error="That name is taken.",
+    )
+    monkeypatch.setattr(
+        ConstraintExample.model_options,
+        "constraints",
+        (*ConstraintExample.model_options.constraints, constraint),
+    )
+
+    ConstraintExample(name="dup", description="d1").save(clean_and_validate=False)
+
+    class Form(ModelForm):
+        class Meta:
+            model = ConstraintExample
+            fields = ["name", "description"]
+
+    rf = RequestFactory()
+    form = Form(request=rf.post("/x/", data={"name": "dup", "description": "d2"}))
+    assert not form.is_valid()
+    assert any("That name is taken." in m for m in form.errors.get("name", [])), (
+        form.errors
+    )