plain.models 0.44.0__py3-none-any.whl → 0.46.0__py3-none-any.whl

plain/models/fields/json.py

@@ -23,7 +23,7 @@ class JSONField(CheckFieldDefaultMixin, Field):
     default_error_messages = {
         "invalid": "Value must be valid JSON.",
     }
-    _default_hint = ("dict", "{}")
+    _default_fix = ("dict", "{}")
 
     def __init__(
         self,
@@ -40,31 +40,31 @@ class JSONField(CheckFieldDefaultMixin, Field):
         self.decoder = decoder
         super().__init__(**kwargs)
 
-    def check(self, **kwargs):
-        errors = super().check(**kwargs)
-        database = kwargs.get("database", False)
-        errors.extend(self._check_supported(database))
+    def preflight(self, **kwargs):
+        errors = super().preflight(**kwargs)
+        errors.extend(self._check_supported())
         return errors
 
-    def _check_supported(self, database):
+    def _check_supported(self):
         errors = []
-        if database:
-            if (
-                self.model._meta.required_db_vendor
-                and self.model._meta.required_db_vendor != db_connection.vendor
-            ):
-                return errors
-            if not (
-                "supports_json_field" in self.model._meta.required_db_features
-                or db_connection.features.supports_json_field
-            ):
-                errors.append(
-                    preflight.Error(
-                        f"{db_connection.display_name} does not support JSONFields.",
-                        obj=self.model,
-                        id="fields.E180",
-                    )
+
+        if (
+            self.model._meta.required_db_vendor
+            and self.model._meta.required_db_vendor != db_connection.vendor
+        ):
+            return errors
+
+        if not (
+            "supports_json_field" in self.model._meta.required_db_features
+            or db_connection.features.supports_json_field
+        ):
+            errors.append(
+                preflight.PreflightResult(
+                    fix=f"{db_connection.display_name} does not support JSONFields. Consider using a TextField with JSON serialization or upgrade to a database that supports JSON fields.",
+                    obj=self.model,
+                    id="fields.json_field_unsupported",
                 )
+            )
         return errors
 
     def deconstruct(self):

plain/models/fields/mixins.py

@@ -1,4 +1,4 @@
-from plain import preflight
+from plain.preflight import PreflightResult
 
 NOT_PROVIDED = object()
 
@@ -29,7 +29,7 @@ class FieldCacheMixin:
 
 
 class CheckFieldDefaultMixin:
-    _default_hint = ("<valid default>", "<invalid default>")
+    _default_fix = ("<valid default>", "<invalid default>")
 
     def _check_default(self):
         if (
@@ -38,21 +38,22 @@ class CheckFieldDefaultMixin:
             and not callable(self.default)
         ):
             return [
-                preflight.Warning(
-                    f"{self.__class__.__name__} default should be a callable instead of an instance "
-                    "so that it's not shared between all field instances.",
-                    hint=(
+                PreflightResult(
+                    fix=(
+                        f"{self.__class__.__name__} default should be a callable instead of an instance "
+                        "so that it's not shared between all field instances. "
                         "Use a callable instead, e.g., use `{}` instead of "
-                        "`{}`.".format(*self._default_hint)
+                        "`{}`.".format(*self._default_fix)
                     ),
                     obj=self,
-                    id="fields.E010",
+                    id="fields.invalid_choice_mixin_default",
+                    warning=True,
                 )
             ]
         else:
             return []
 
-    def check(self, **kwargs):
-        errors = super().check(**kwargs)
+    def preflight(self, **kwargs):
+        errors = super().preflight(**kwargs)
         errors.extend(self._check_default())
         return errors

plain/models/fields/related.py

@@ -1,10 +1,11 @@
 from functools import cached_property, partial
 
-from plain import exceptions, preflight
+from plain import exceptions
 from plain.models.constants import LOOKUP_SEP
 from plain.models.deletion import SET_DEFAULT, SET_NULL
 from plain.models.query_utils import PathInfo, Q
 from plain.models.utils import make_model_tuple
+from plain.preflight import PreflightResult
 from plain.runtime import SettingsReference
 
 from ..registry import models_registry
@@ -106,9 +107,9 @@ class RelatedField(FieldCacheMixin, Field):
         models_registry.check_ready()
         return self.remote_field.model
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
+            *super().preflight(**kwargs),
             *self._check_related_name_is_valid(),
             *self._check_related_query_name_is_valid(),
             *self._check_relation_model_exists(),
@@ -126,11 +127,10 @@ class RelatedField(FieldCacheMixin, Field):
         )
         if not is_valid_id:
             return [
-                preflight.Error(
-                    f"The name '{self.remote_field.related_name}' is invalid related_name for field {self.model._meta.object_name}.{self.name}",
-                    hint="Related name must be a valid Python identifier.",
+                PreflightResult(
+                    fix=f"The name '{self.remote_field.related_name}' is invalid related_name for field {self.model._meta.object_name}.{self.name}. Related name must be a valid Python identifier.",
                     obj=self,
-                    id="fields.E306",
+                    id="fields.invalid_related_name",
                 )
             ]
         return []
@@ -142,26 +142,26 @@ class RelatedField(FieldCacheMixin, Field):
         errors = []
         if rel_query_name.endswith("_"):
             errors.append(
-                preflight.Error(
-                    f"Reverse query name '{rel_query_name}' must not end with an underscore.",
-                    hint=(
+                PreflightResult(
+                    fix=(
+                        f"Reverse query name '{rel_query_name}' must not end with an underscore. "
                         "Add or change a related_name or related_query_name "
                         "argument for this field."
                     ),
                     obj=self,
-                    id="fields.E308",
+                    id="fields.related_field_accessor_clash",
                 )
             )
         if LOOKUP_SEP in rel_query_name:
             errors.append(
-                preflight.Error(
-                    f"Reverse query name '{rel_query_name}' must not contain '{LOOKUP_SEP}'.",
-                    hint=(
+                PreflightResult(
+                    fix=(
+                        f"Reverse query name '{rel_query_name}' must not contain '{LOOKUP_SEP}'. "
                         "Add or change a related_name or related_query_name "
                         "argument for this field."
                     ),
                     obj=self,
-                    id="fields.E309",
+                    id="fields.related_field_query_name_clash",
                 )
             )
         return errors
@@ -178,11 +178,13 @@ class RelatedField(FieldCacheMixin, Field):
         )
         if rel_is_missing and rel_is_string:
             return [
-                preflight.Error(
-                    f"Field defines a relation with model '{model_name}', which is either "
-                    "not installed, or is abstract.",
+                PreflightResult(
+                    fix=(
+                        f"Field defines a relation with model '{model_name}', which is either "
+                        "not installed, or is abstract. Ensure the model is installed and not abstract."
+                    ),
                     obj=self,
-                    id="fields.E300",
+                    id="fields.related_model_not_installed",
                 )
             ]
         return []
@@ -230,29 +232,29 @@ class RelatedField(FieldCacheMixin, Field):
             clash_name = f"{rel_opts.label}.{clash_field.name}"
             if not rel_is_hidden and clash_field.name == rel_name:
                 errors.append(
-                    preflight.Error(
-                        f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
-                        f"for '{field_name}' clashes with field name "
-                        f"'{clash_name}'.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
+                            f"for '{field_name}' clashes with field name "
+                            f"'{clash_name}'. "
                             f"Rename field '{clash_name}', or add/change a related_name "
                             f"argument to the definition for field '{field_name}'."
                         ),
                         obj=self,
-                        id="fields.E302",
+                        id="fields.related_accessor_clash_field",
                     )
                 )
 
             if clash_field.name == rel_query_name:
                 errors.append(
-                    preflight.Error(
-                        f"Reverse query name for '{field_name}' clashes with field name '{clash_name}'.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            f"Reverse query name for '{field_name}' clashes with field name '{clash_name}'. "
                             f"Rename field '{clash_name}', or add/change a related_name "
                             f"argument to the definition for field '{field_name}'."
                         ),
                         obj=self,
-                        id="fields.E303",
+                        id="fields.related_accessor_clash_manager",
                     )
                 )
 
@@ -267,30 +269,30 @@ class RelatedField(FieldCacheMixin, Field):
             )
             if not rel_is_hidden and clash_field.get_accessor_name() == rel_name:
                 errors.append(
-                    preflight.Error(
-                        f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
-                        f"for '{field_name}' clashes with reverse accessor for "
-                        f"'{clash_name}'.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
+                            f"for '{field_name}' clashes with reverse accessor for "
+                            f"'{clash_name}'. "
                             "Add or change a related_name argument "
                             f"to the definition for '{field_name}' or '{clash_name}'."
                         ),
                         obj=self,
-                        id="fields.E304",
+                        id="fields.related_name_clash",
                     )
                 )
 
             if clash_field.get_accessor_name() == rel_query_name:
                 errors.append(
-                    preflight.Error(
-                        f"Reverse query name for '{field_name}' clashes with reverse query name "
-                        f"for '{clash_name}'.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            f"Reverse query name for '{field_name}' clashes with reverse query name "
+                            f"for '{clash_name}'. "
                             "Add or change a related_name argument "
                             f"to the definition for '{field_name}' or '{clash_name}'."
                         ),
                         obj=self,
-                        id="fields.E305",
+                        id="fields.related_query_name_clash",
                     )
                 )
 
@@ -600,9 +602,9 @@ class ForeignKey(RelatedField):
                     self.remote_field.limit_choices_to
                 )
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
+            *super().preflight(**kwargs),
             *self._check_on_delete(),
         ]
 
@@ -610,23 +612,24 @@ class ForeignKey(RelatedField):
         on_delete = getattr(self.remote_field, "on_delete", None)
         if on_delete == SET_NULL and not self.allow_null:
             return [
-                preflight.Error(
-                    "Field specifies on_delete=SET_NULL, but cannot be null.",
-                    hint=(
-                        "Set allow_null=True argument on the field, or change the on_delete "
-                        "rule."
+                PreflightResult(
+                    fix=(
+                        "Field specifies on_delete=SET_NULL, but cannot be null. "
+                        "Set allow_null=True argument on the field, or change the on_delete rule."
                     ),
                     obj=self,
-                    id="fields.E320",
+                    id="fields.foreign_key_null_constraint_violation",
                 )
             ]
         elif on_delete == SET_DEFAULT and not self.has_default():
             return [
-                preflight.Error(
-                    "Field specifies on_delete=SET_DEFAULT, but has no default value.",
-                    hint="Set a default value, or change the on_delete rule.",
+                PreflightResult(
+                    fix=(
+                        "Field specifies on_delete=SET_DEFAULT, but has no default value. "
+                        "Set a default value, or change the on_delete rule."
+                    ),
                     obj=self,
-                    id="fields.E321",
+                    id="fields.foreign_key_set_default_no_default",
                 )
             ]
         else:
@@ -834,9 +837,9 @@ class ManyToManyField(RelatedField):
             **kwargs,
         )
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
+            *super().preflight(**kwargs),
             *self._check_relationship_model(**kwargs),
             *self._check_ignored_options(**kwargs),
             *self._check_table_uniqueness(**kwargs),
@@ -847,36 +850,43 @@ class ManyToManyField(RelatedField):
 
         if self.has_null_arg:
             warnings.append(
-                preflight.Warning(
-                    "null has no effect on ManyToManyField.",
+                PreflightResult(
+                    fix="The 'null' option has no effect on ManyToManyField. Remove the 'null' argument.",
                     obj=self,
-                    id="fields.W340",
+                    id="fields.m2m_null_has_no_effect",
+                    warning=True,
                 )
             )
 
         if self._validators:
             warnings.append(
-                preflight.Warning(
-                    "ManyToManyField does not support validators.",
+                PreflightResult(
+                    fix="ManyToManyField does not support validators. Remove validators from this field.",
                     obj=self,
-                    id="fields.W341",
+                    id="fields.m2m_validators_not_supported",
+                    warning=True,
                 )
             )
         if self.remote_field.symmetrical and self._related_name:
             warnings.append(
-                preflight.Warning(
-                    "related_name has no effect on ManyToManyField "
-                    'with a symmetrical relationship, e.g. to "self".',
+                PreflightResult(
+                    fix=(
+                        "The 'related_name' argument has no effect on ManyToManyField "
+                        'with a symmetrical relationship, e.g. to "self". '
+                        "Remove the 'related_name' argument or set symmetrical=False."
+                    ),
                     obj=self,
-                    id="fields.W345",
+                    id="fields.m2m_related_name_no_effect_symmetrical",
+                    warning=True,
                 )
             )
         if self.db_comment:
             warnings.append(
-                preflight.Warning(
-                    "db_comment has no effect on ManyToManyField.",
+                PreflightResult(
+                    fix="The 'db_comment' option has no effect on ManyToManyField. Remove the 'db_comment' argument.",
                     obj=self,
-                    id="fields.W346",
+                    id="fields.m2m_db_comment_has_no_effect",
+                    warning=True,
                 )
             )
 
@@ -893,11 +903,14 @@ class ManyToManyField(RelatedField):
         if self.remote_field.through not in self.opts.models_registry.get_models():
             # The relationship model is not installed.
             errors.append(
-                preflight.Error(
-                    "Field specifies a many-to-many relation through model "
-                    f"'{qualified_model_name}', which has not been installed.",
+                PreflightResult(
+                    fix=(
+                        "Field specifies a many-to-many relation through model "
+                        f"'{qualified_model_name}', which has not been installed. "
+                        "Ensure the through model is properly defined and installed."
+                    ),
                     obj=self,
-                    id="fields.E331",
+                    id="fields.m2m_through_model_not_installed",
                 )
             )
 
@@ -925,18 +938,16 @@ class ManyToManyField(RelatedField):
 
                 if seen_self > 2 and not self.remote_field.through_fields:
                     errors.append(
-                        preflight.Error(
-                            "The model is used as an intermediate model by "
-                            f"'{self}', but it has more than two foreign keys "
-                            f"to '{from_model_name}', which is ambiguous. You must specify "
-                            "which two foreign keys Plain should use via the "
-                            "through_fields keyword argument.",
-                            hint=(
+                        PreflightResult(
+                            fix=(
+                                "The model is used as an intermediate model by "
+                                f"'{self}', but it has more than two foreign keys "
+                                f"to '{from_model_name}', which is ambiguous. "
                                 "Use through_fields to specify which two foreign keys "
                                 "Plain should use."
                             ),
                             obj=self.remote_field.through,
-                            id="fields.E333",
+                            id="fields.m2m_through_model_ambiguous_fks",
                         )
                     )
 
@@ -953,47 +964,48 @@ class ManyToManyField(RelatedField):
 
                 if seen_from > 1 and not self.remote_field.through_fields:
                     errors.append(
-                        preflight.Error(
-                            (
+                        PreflightResult(
+                            fix=(
                                 "The model is used as an intermediate model by "
                                 f"'{self}', but it has more than one foreign key "
                                 f"from '{from_model_name}', which is ambiguous. You must specify "
                                 "which foreign key Plain should use via the "
-                                "through_fields keyword argument."
-                            ),
-                            hint=(
+                                "through_fields keyword argument. "
                                 "If you want to create a recursive relationship, "
                                 f'use ManyToManyField("{RECURSIVE_RELATIONSHIP_CONSTANT}", through="{relationship_model_name}").'
                             ),
                             obj=self,
-                            id="fields.E334",
+                            id="fields.m2m_through_model_invalid_recursive_from",
                         )
                     )
 
                 if seen_to > 1 and not self.remote_field.through_fields:
                     errors.append(
-                        preflight.Error(
-                            "The model is used as an intermediate model by "
-                            f"'{self}', but it has more than one foreign key "
-                            f"to '{to_model_name}', which is ambiguous. You must specify "
-                            "which foreign key Plain should use via the "
-                            "through_fields keyword argument.",
-                            hint=(
+                        PreflightResult(
+                            fix=(
+                                "The model is used as an intermediate model by "
+                                f"'{self}', but it has more than one foreign key "
+                                f"to '{to_model_name}', which is ambiguous. You must specify "
+                                "which foreign key Plain should use via the "
+                                "through_fields keyword argument. "
                                 "If you want to create a recursive relationship, "
                                 f'use ManyToManyField("{RECURSIVE_RELATIONSHIP_CONSTANT}", through="{relationship_model_name}").'
                             ),
                             obj=self,
-                            id="fields.E335",
+                            id="fields.m2m_through_model_invalid_recursive_to",
                         )
                     )
 
                 if seen_from == 0 or seen_to == 0:
                     errors.append(
-                        preflight.Error(
-                            "The model is used as an intermediate model by "
-                            f"'{self}', but it does not have a foreign key to '{from_model_name}' or '{to_model_name}'.",
+                        PreflightResult(
+                            fix=(
+                                "The model is used as an intermediate model by "
+                                f"'{self}', but it does not have a foreign key to '{from_model_name}' or '{to_model_name}'. "
+                                "Add the required foreign keys to the through model."
+                            ),
                             obj=self.remote_field.through,
-                            id="fields.E336",
+                            id="fields.m2m_through_model_missing_fk",
                         )
                     )
 
@@ -1007,16 +1019,16 @@ class ManyToManyField(RelatedField):
                 and self.remote_field.through_fields[1]
             ):
                 errors.append(
-                    preflight.Error(
-                        "Field specifies 'through_fields' but does not provide "
-                        "the names of the two link fields that should be used "
-                        f"for the relation through model '{qualified_model_name}'.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            "Field specifies 'through_fields' but does not provide "
+                            "the names of the two link fields that should be used "
+                            f"for the relation through model '{qualified_model_name}'. "
                             "Make sure you specify 'through_fields' as "
-                            "through_fields=('field1', 'field2')"
+                            "through_fields=('field1', 'field2')."
                         ),
                         obj=self,
-                        id="fields.E337",
+                        id="fields.m2m_through_fields_wrong_length",
                     )
                 )
 
@@ -1051,7 +1063,7 @@ class ManyToManyField(RelatedField):
                         ):
                             possible_field_names.append(f.name)
                     if possible_field_names:
-                        hint = (
+                        fix = (
                             "Did you mean one of the following foreign keys to '{}': "
                             "{}?".format(
                                 related_model._meta.object_name,
@@ -1059,17 +1071,16 @@ class ManyToManyField(RelatedField):
                             )
                         )
                     else:
-                        hint = None
+                        fix = ""
 
                     try:
                         field = through._meta.get_field(field_name)
                     except exceptions.FieldDoesNotExist:
                         errors.append(
-                            preflight.Error(
-                                f"The intermediary model '{qualified_model_name}' has no field '{field_name}'.",
-                                hint=hint,
+                            PreflightResult(
+                                fix=f"The intermediary model '{qualified_model_name}' has no field '{field_name}'. {fix}",
                                 obj=self,
-                                id="fields.E338",
+                                id="fields.m2m_through_field_not_found",
                             )
                         )
                     else:
@@ -1079,11 +1090,10 @@ class ManyToManyField(RelatedField):
                             == related_model
                         ):
                             errors.append(
-                                preflight.Error(
-                                    f"'{through._meta.object_name}.{field_name}' is not a foreign key to '{related_model._meta.object_name}'.",
-                                    hint=hint,
+                                PreflightResult(
+                                    fix=f"'{through._meta.object_name}.{field_name}' is not a foreign key to '{related_model._meta.object_name}'. {fix}",
                                     obj=self,
-                                    id="fields.E339",
+                                    id="fields.m2m_through_field_not_fk_to_model",
                                 )
                             )
 
@@ -1108,12 +1118,14 @@ class ManyToManyField(RelatedField):
         ):
             clashing_obj = model._meta.label
             return [
-                preflight.Error(
-                    f"The field's intermediary table '{m2m_db_table}' clashes with the "
-                    f"table name of '{clashing_obj}'.",
+                PreflightResult(
+                    fix=(
+                        f"The field's intermediary table '{m2m_db_table}' clashes with the "
+                        f"table name of '{clashing_obj}'. "
+                        "Change the through model's db_table or use a different model."
+                    ),
                     obj=self,
-                    hint=None,
-                    id="fields.E340",
+                    id="fields.m2m_table_name_clash",
                 )
             ]
         return []

plain/models/migrations/state.py

@@ -521,7 +521,7 @@ class StateModelsRegistry(ModelsRegistry):
         from plain.models.preflight import _check_lazy_references
 
         if errors := _check_lazy_references(self, packages_registry):
-            raise ValueError("\n".join(error.msg for error in errors))
+            raise ValueError("\n".join(error.message for error in errors))
 
     @contextmanager
     def bulk_update(self):