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

plain/models/fields/__init__.py

@@ -9,11 +9,12 @@ import warnings
 from base64 import b64decode, b64encode
 from functools import cached_property, partialmethod, total_ordering
 
-from plain import exceptions, preflight, validators
+from plain import exceptions, validators
 from plain.models.constants import LOOKUP_SEP
 from plain.models.db import db_connection
 from plain.models.enums import ChoicesMeta
 from plain.models.query_utils import DeferredAttribute, RegisterLookupMixin
+from plain.preflight import PreflightResult
 from plain.utils import timezone
 from plain.utils.datastructures import DictWrapper
 from plain.utils.dateparse import (
@@ -36,7 +37,6 @@ __all__ = [
     "BinaryField",
     "BooleanField",
     "CharField",
-    "CommaSeparatedIntegerField",
     "DateField",
     "DateTimeField",
     "DecimalField",
@@ -46,10 +46,8 @@ __all__ = [
     "Field",
     "FloatField",
     "GenericIPAddressField",
-    "IPAddressField",
     "IntegerField",
     "NOT_PROVIDED",
-    "NullBooleanField",
     "PositiveBigIntegerField",
     "PositiveIntegerField",
     "PositiveSmallIntegerField",
@@ -125,8 +123,6 @@ class Field(RegisterLookupMixin):
         "required": "This field is be required.",
         "unique": "A %(model_name)s with this %(field_label)s already exists.",
     }
-    system_check_deprecated_details = None
-    system_check_removed_details = None
 
     # Attributes that don't affect a column definition.
     # These attributes are ignored when altering the field.
@@ -218,15 +214,14 @@ class Field(RegisterLookupMixin):
             return f"<{path}: {name}>"
         return f"<{path}>"
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
             *self._check_field_name(),
             *self._check_choices(),
-            *self._check_db_comment(**kwargs),
+            *self._check_db_comment(),
             *self._check_null_allowed_for_primary_keys(),
-            *self._check_backend_specific_checks(**kwargs),
+            *self._check_backend_specific_checks(),
             *self._check_validators(),
-            *self._check_deprecation_details(),
         ]
 
     def _check_field_name(self):
@@ -236,26 +231,26 @@ class Field(RegisterLookupMixin):
         """
         if self.name.endswith("_"):
             return [
-                preflight.Error(
-                    "Field names must not end with an underscore.",
+                PreflightResult(
+                    fix="Field names must not end with an underscore.",
                     obj=self,
-                    id="fields.E001",
+                    id="fields.name_ends_with_underscore",
                 )
             ]
         elif LOOKUP_SEP in self.name:
             return [
-                preflight.Error(
-                    f'Field names must not contain "{LOOKUP_SEP}".',
+                PreflightResult(
+                    fix=f'Field names must not contain "{LOOKUP_SEP}".',
                     obj=self,
-                    id="fields.E002",
+                    id="fields.name_contains_lookup_separator",
                 )
             ]
         elif self.name == "id":
             return [
-                preflight.Error(
-                    "'id' is a reserved word that cannot be used as a field name.",
+                PreflightResult(
+                    fix="'id' is a reserved word that cannot be used as a field name.",
                     obj=self,
-                    id="fields.E003",
+                    id="fields.reserved_field_name_id",
                 )
             ]
         else:
@@ -271,10 +266,10 @@ class Field(RegisterLookupMixin):
 
         if not is_iterable(self.choices) or isinstance(self.choices, str):
             return [
-                preflight.Error(
-                    "'choices' must be an iterable (e.g., a list or tuple).",
+                PreflightResult(
+                    fix="'choices' must be an iterable (e.g., a list or tuple).",
                     obj=self,
-                    id="fields.E004",
+                    id="fields.choices_not_iterable",
                 )
             ]
 
@@ -319,26 +314,26 @@ class Field(RegisterLookupMixin):
         else:
             if self.max_length is not None and choice_max_length > self.max_length:
                 return [
-                    preflight.Error(
-                        "'max_length' is too small to fit the longest value "  # noqa: UP031
+                    PreflightResult(
+                        fix="'max_length' is too small to fit the longest value "  # noqa: UP031
                         "in 'choices' (%d characters)." % choice_max_length,
                         obj=self,
-                        id="fields.E009",
+                        id="fields.max_length_too_small_for_choices",
                     ),
                 ]
             return []
 
         return [
-            preflight.Error(
-                "'choices' must be an iterable containing "
+            PreflightResult(
+                fix="'choices' must be an iterable containing "
                 "(actual value, human readable name) tuples.",
                 obj=self,
-                id="fields.E005",
+                id="fields.choices_invalid_format",
             )
         ]
 
-    def _check_db_comment(self, database=False, **kwargs):
-        if not self.db_comment or not database:
+    def _check_db_comment(self):
+        if not self.db_comment:
             return []
         errors = []
         if not (
@@ -346,11 +341,12 @@ class Field(RegisterLookupMixin):
             or "supports_comments" in self.model._meta.required_db_features
         ):
             errors.append(
-                preflight.Warning(
-                    f"{db_connection.display_name} does not support comments on "
+                PreflightResult(
+                    fix=f"{db_connection.display_name} does not support comments on "
                     f"columns (db_comment).",
                     obj=self,
-                    id="fields.W163",
+                    id="fields.db_comment_unsupported",
+                    warning=True,
                 )
             )
         return errors
@@ -361,24 +357,20 @@ class Field(RegisterLookupMixin):
             # consider NULL and '' to be equal (and thus set up
             # character-based fields a little differently).
             return [
-                preflight.Error(
-                    "Primary keys must not have allow_null=True.",
-                    hint=(
-                        "Set allow_null=False on the field, or "
-                        "remove primary_key=True argument."
-                    ),
+                PreflightResult(
+                    fix="Primary keys must not have allow_null=True. "
+                    "Set allow_null=False on the field, or "
+                    "remove primary_key=True argument.",
                     obj=self,
-                    id="fields.E007",
+                    id="fields.primary_key_allows_null",
                 )
             ]
         else:
             return []
 
-    def _check_backend_specific_checks(self, database=False, **kwargs):
-        if not database:
-            return []
+    def _check_backend_specific_checks(self):
         errors = []
-        errors.extend(db_connection.validation.check_field(self, **kwargs))
+        errors.extend(db_connection.validation.check_field(self))
         return errors
 
     def _check_validators(self):
@@ -386,45 +378,18 @@ class Field(RegisterLookupMixin):
         for i, validator in enumerate(self.validators):
             if not callable(validator):
                 errors.append(
-                    preflight.Error(
-                        "All 'validators' must be callable.",
-                        hint=(
+                    PreflightResult(
+                        fix=(
+                            "All 'validators' must be callable. "
                             f"validators[{i}] ({repr(validator)}) isn't a function or "
                             "instance of a validator class."
                         ),
                         obj=self,
-                        id="fields.E008",
+                        id="fields.invalid_validator",
                     )
                 )
         return errors
 
-    def _check_deprecation_details(self):
-        if self.system_check_removed_details is not None:
-            return [
-                preflight.Error(
-                    self.system_check_removed_details.get(
-                        "msg",
-                        f"{self.__class__.__name__} has been removed except for support in historical "
-                        "migrations.",
-                    ),
-                    hint=self.system_check_removed_details.get("hint"),
-                    obj=self,
-                    id=self.system_check_removed_details.get("id", "fields.EXXX"),
-                )
-            ]
-        elif self.system_check_deprecated_details is not None:
-            return [
-                preflight.Warning(
-                    self.system_check_deprecated_details.get(
-                        "msg", f"{self.__class__.__name__} has been deprecated."
-                    ),
-                    hint=self.system_check_deprecated_details.get("hint"),
-                    obj=self,
-                    id=self.system_check_deprecated_details.get("id", "fields.WXXX"),
-                )
-            ]
-        return []
-
     def get_col(self, alias, output_field=None):
         if alias == self.model._meta.db_table and (
             output_field is None or output_field == self
@@ -985,12 +950,11 @@ class CharField(Field):
         else:
             return "String (unlimited)"
 
-    def check(self, **kwargs):
-        database = kwargs.get("database", False)
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
-            *self._check_db_collation(database),
-            *self._check_max_length_attribute(**kwargs),
+            *super().preflight(**kwargs),
+            *self._check_db_collation(),
+            *self._check_max_length_attribute(),
         ]
 
     def _check_max_length_attribute(self, **kwargs):
@@ -1002,10 +966,10 @@ class CharField(Field):
             ):
                 return []
             return [
-                preflight.Error(
-                    "CharFields must define a 'max_length' attribute.",
+                PreflightResult(
+                    fix="CharFields must define a 'max_length' attribute.",
                     obj=self,
-                    id="fields.E120",
+                    id="fields.charfield_missing_max_length",
                 )
             ]
         elif (
@@ -1014,29 +978,29 @@ class CharField(Field):
             or self.max_length <= 0
         ):
             return [
-                preflight.Error(
-                    "'max_length' must be a positive integer.",
+                PreflightResult(
+                    fix="'max_length' must be a positive integer.",
                     obj=self,
-                    id="fields.E121",
+                    id="fields.charfield_invalid_max_length",
                 )
             ]
         else:
             return []
 
-    def _check_db_collation(self, database):
+    def _check_db_collation(self):
         errors = []
-        if database and not (
+        if not (
             self.db_collation is None
             or "supports_collation_on_charfield"
             in self.model._meta.required_db_features
             or db_connection.features.supports_collation_on_charfield
         ):
             errors.append(
-                preflight.Error(
-                    f"{db_connection.display_name} does not support a database collation on "
+                PreflightResult(
+                    fix=f"{db_connection.display_name} does not support a database collation on "
                     "CharFields.",
                     obj=self,
-                    id="fields.E190",
+                    id="fields.db_collation_unsupported",
                 ),
             )
         return errors
@@ -1070,21 +1034,6 @@ class CharField(Field):
         return name, path, args, kwargs
 
 
-class CommaSeparatedIntegerField(CharField):
-    default_validators = [validators.validate_comma_separated_integer_list]
-    description = "Comma-separated integers"
-    system_check_removed_details = {
-        "msg": (
-            "CommaSeparatedIntegerField is removed except for support in "
-            "historical migrations."
-        ),
-        "hint": (
-            "Use CharField(validators=[validate_comma_separated_integer_list]) instead."
-        ),
-        "id": "fields.E901",
-    }
-
-
 def _to_naive(value):
     if timezone.is_aware(value):
         value = timezone.make_naive(value, datetime.UTC)
@@ -1096,9 +1045,9 @@ def _get_naive_now():
 
 
 class DateTimeCheckMixin:
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
+            *super().preflight(**kwargs),
             *self._check_mutually_exclusive_options(),
             *self._check_fix_default_value(),
         ]
@@ -1117,12 +1066,12 @@ class DateTimeCheckMixin:
         ].count(True)
         if enabled_options > 1:
             return [
-                preflight.Error(
-                    "The options auto_now, auto_now_add, and default "
+                PreflightResult(
+                    fix="The options auto_now, auto_now_add, and default "
                     "are mutually exclusive. Only one of these options "
                     "may be present.",
                     obj=self,
-                    id="fields.E160",
+                    id="fields.datetime_auto_options_mutually_exclusive",
                 )
             ]
         else:
@@ -1153,16 +1102,15 @@ class DateTimeCheckMixin:
             upper = upper.date()
         if lower <= value <= upper:
             return [
-                preflight.Warning(
-                    "Fixed default value provided.",
-                    hint=(
-                        "It seems you set a fixed date / time / datetime "
-                        "value as default for this field. This may not be "
-                        "what you want. If you want to have the current date "
-                        "as default, use `plain.utils.timezone.now`"
-                    ),
+                PreflightResult(
+                    fix="Fixed default value provided. "
+                    "It seems you set a fixed date / time / datetime "
+                    "value as default for this field. This may not be "
+                    "what you want. If you want to have the current date "
+                    "as default, use `plain.utils.timezone.now`",
                     obj=self,
-                    id="fields.W161",
+                    id="fields.datetime_naive_default_value",
+                    warning=True,
                 )
             ]
         return []
@@ -1422,15 +1370,15 @@ class DecimalField(Field):
         self.max_digits, self.decimal_places = max_digits, decimal_places
         super().__init__(**kwargs)
 
-    def check(self, **kwargs):
-        errors = super().check(**kwargs)
+    def preflight(self, **kwargs):
+        errors = super().preflight(**kwargs)
 
         digits_errors = [
             *self._check_decimal_places(),
             *self._check_max_digits(),
         ]
         if not digits_errors:
-            errors.extend(self._check_decimal_places_and_max_digits(**kwargs))
+            errors.extend(self._check_decimal_places_and_max_digits())
         else:
             errors.extend(digits_errors)
         return errors
@@ -1442,18 +1390,18 @@ class DecimalField(Field):
                 raise ValueError()
         except TypeError:
             return [
-                preflight.Error(
-                    "DecimalFields must define a 'decimal_places' attribute.",
+                PreflightResult(
+                    fix="DecimalFields must define a 'decimal_places' attribute.",
                     obj=self,
-                    id="fields.E130",
+                    id="fields.decimalfield_missing_decimal_places",
                 )
             ]
         except ValueError:
             return [
-                preflight.Error(
-                    "'decimal_places' must be a non-negative integer.",
+                PreflightResult(
+                    fix="'decimal_places' must be a non-negative integer.",
                     obj=self,
-                    id="fields.E131",
+                    id="fields.decimalfield_invalid_decimal_places",
                 )
             ]
         else:
@@ -1466,30 +1414,30 @@ class DecimalField(Field):
                 raise ValueError()
         except TypeError:
             return [
-                preflight.Error(
-                    "DecimalFields must define a 'max_digits' attribute.",
+                PreflightResult(
+                    fix="DecimalFields must define a 'max_digits' attribute.",
                     obj=self,
-                    id="fields.E132",
+                    id="fields.decimalfield_missing_max_digits",
                 )
             ]
         except ValueError:
             return [
-                preflight.Error(
-                    "'max_digits' must be a positive integer.",
+                PreflightResult(
+                    fix="'max_digits' must be a positive integer.",
                     obj=self,
-                    id="fields.E133",
+                    id="fields.decimalfield_invalid_max_digits",
                 )
             ]
         else:
             return []
 
-    def _check_decimal_places_and_max_digits(self, **kwargs):
+    def _check_decimal_places_and_max_digits(self):
         if int(self.decimal_places) > int(self.max_digits):
             return [
-                preflight.Error(
-                    "'max_digits' must be greater or equal to 'decimal_places'.",
+                PreflightResult(
+                    fix="'max_digits' must be greater or equal to 'decimal_places'.",
                     obj=self,
-                    id="fields.E134",
+                    id="fields.decimalfield_decimal_places_exceeds_max_digits",
                 )
             ]
         return []
@@ -1662,20 +1610,20 @@ class IntegerField(Field):
     }
     description = "Integer"
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
+            *super().preflight(**kwargs),
             *self._check_max_length_warning(),
         ]
 
     def _check_max_length_warning(self):
         if self.max_length is not None:
             return [
-                preflight.Warning(
-                    f"'max_length' is ignored when used with {self.__class__.__name__}.",
-                    hint="Remove 'max_length' from field",
+                PreflightResult(
+                    fix=f"'max_length' is ignored when used with {self.__class__.__name__}. Remove 'max_length' from field.",
                     obj=self,
-                    id="fields.W122",
+                    id="fields.max_length_ignored",
+                    warning=True,
                 )
             ]
         return []
@@ -1760,37 +1708,6 @@ class SmallIntegerField(IntegerField):
         return "SmallIntegerField"
 
 
-class IPAddressField(Field):
-    empty_strings_allowed = False
-    description = "IPv4 address"
-    system_check_removed_details = {
-        "msg": (
-            "IPAddressField has been removed except for support in "
-            "historical migrations."
-        ),
-        "hint": "Use GenericIPAddressField instead.",
-        "id": "fields.E900",
-    }
-
-    def __init__(self, **kwargs):
-        kwargs["max_length"] = 15
-        super().__init__(**kwargs)
-
-    def deconstruct(self):
-        name, path, args, kwargs = super().deconstruct()
-        del kwargs["max_length"]
-        return name, path, args, kwargs
-
-    def get_prep_value(self, value):
-        value = super().get_prep_value(value)
-        if value is None:
-            return None
-        return str(value)
-
-    def get_internal_type(self):
-        return "IPAddressField"
-
-
 class GenericIPAddressField(Field):
     empty_strings_allowed = False
     description = "IP address"
@@ -1813,22 +1730,22 @@ class GenericIPAddressField(Field):
         kwargs["max_length"] = 39
         super().__init__(**kwargs)
 
-    def check(self, **kwargs):
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
-            *self._check_required_and_null_values(**kwargs),
+            *super().preflight(**kwargs),
+            *self._check_required_and_null_values(),
         ]
 
-    def _check_required_and_null_values(self, **kwargs):
+    def _check_required_and_null_values(self):
         if not getattr(self, "allow_null", False) and not getattr(
             self, "required", True
         ):
             return [
-                preflight.Error(
-                    "GenericIPAddressFields cannot have required=False if allow_null=False, "
+                PreflightResult(
+                    fix="GenericIPAddressFields cannot have required=False if allow_null=False, "
                     "as blank values are stored as nulls.",
                     obj=self,
-                    id="fields.E150",
+                    id="fields.generic_ip_field_null_blank_config",
                 )
             ]
         return []
@@ -1875,32 +1792,6 @@ class GenericIPAddressField(Field):
         return str(value)
 
 
-class NullBooleanField(BooleanField):
-    default_error_messages = {
-        "invalid": "“%(value)s” value must be either None, True or False.",
-        "invalid_nullable": "“%(value)s” value must be either None, True or False.",
-    }
-    description = "Boolean (Either True, False or None)"
-    system_check_removed_details = {
-        "msg": (
-            "NullBooleanField is removed except for support in historical migrations."
-        ),
-        "hint": "Use BooleanField(allow_null=True) instead.",
-        "id": "fields.E903",
-    }
-
-    def __init__(self, **kwargs):
-        kwargs["allow_null"] = True
-        kwargs["required"] = False
-        super().__init__(**kwargs)
-
-    def deconstruct(self):
-        name, path, args, kwargs = super().deconstruct()
-        del kwargs["allow_null"]
-        del kwargs["required"]
-        return name, path, args, kwargs
-
-
 class PositiveIntegerRelDbTypeMixin:
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
@@ -1957,27 +1848,26 @@ class TextField(Field):
         super().__init__(**kwargs)
         self.db_collation = db_collation
 
-    def check(self, **kwargs):
-        database = kwargs.get("database", False)
+    def preflight(self, **kwargs):
         return [
-            *super().check(**kwargs),
-            *self._check_db_collation(database),
+            *super().preflight(**kwargs),
+            *self._check_db_collation(),
         ]
 
-    def _check_db_collation(self, database):
+    def _check_db_collation(self):
         errors = []
-        if database and not (
+        if not (
             self.db_collation is None
             or "supports_collation_on_textfield"
             in self.model._meta.required_db_features
             or db_connection.features.supports_collation_on_textfield
         ):
             errors.append(
-                preflight.Error(
-                    f"{db_connection.display_name} does not support a database collation on "
+                PreflightResult(
+                    fix=f"{db_connection.display_name} does not support a database collation on "
                     "TextFields.",
                     obj=self,
-                    id="fields.E190",
+                    id="fields.db_collation_unsupported",
                 ),
             )
         return errors
@@ -2130,17 +2020,17 @@ class BinaryField(Field):
         if self.max_length is not None:
             self.validators.append(validators.MaxLengthValidator(self.max_length))
 
-    def check(self, **kwargs):
-        return [*super().check(**kwargs), *self._check_str_default_value()]
+    def preflight(self, **kwargs):
+        return [*super().preflight(**kwargs), *self._check_str_default_value()]
 
     def _check_str_default_value(self):
         if self.has_default() and isinstance(self.default, str):
             return [
-                preflight.Error(
-                    "BinaryField's default cannot be a string. Use bytes "
+                PreflightResult(
+                    fix="BinaryField's default cannot be a string. Use bytes "
                     "content instead.",
                     obj=self,
-                    id="fields.E170",
+                    id="fields.filefield_upload_to_not_callable",
                 )
             ]
         return []
@@ -2236,10 +2126,10 @@ class PrimaryKeyField(BigIntegerField):
         self.creation_counter = Field.auto_creation_counter
         Field.auto_creation_counter -= 1
 
-    def check(self, **kwargs):
-        errors = super().check(**kwargs)
-        # Remove the E003 error for 'id' field name since PrimaryKeyField is allowed to use it
-        errors = [e for e in errors if e.id != "fields.E003"]
+    def preflight(self, **kwargs):
+        errors = super().preflight(**kwargs)
+        # Remove the reserved_field_name_id error for 'id' field name since PrimaryKeyField is allowed to use it
+        errors = [e for e in errors if e.id != "fields.reserved_field_name_id"]
         return errors
 
     def deconstruct(self):