plain.models 0.49.2__py3-none-any.whl → 0.51.0__py3-none-any.whl

plain/models/fields/json.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import json
+from typing import TYPE_CHECKING, Any, cast
 
 from plain import exceptions, preflight
 from plain.models import expressions, lookups
@@ -14,6 +17,13 @@ from plain.models.lookups import (
 from . import Field
 from .mixins import CheckFieldDefaultMixin
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.backends.mysql.base import MySQLDatabaseWrapper
+    from plain.models.backends.sqlite3.base import SQLiteDatabaseWrapper
+    from plain.models.sql.compiler import SQLCompiler
+    from plain.preflight.results import PreflightResult
+
 __all__ = ["JSONField"]
 
 
@@ -28,9 +38,9 @@ class JSONField(CheckFieldDefaultMixin, Field):
     def __init__(
         self,
         *,
-        encoder=None,
-        decoder=None,
-        **kwargs,
+        encoder: type[json.JSONEncoder] | None = None,
+        decoder: type[json.JSONDecoder] | None = None,
+        **kwargs: Any,
     ):
         if encoder and not callable(encoder):
             raise ValueError("The encoder parameter must be a callable object.")
@@ -40,22 +50,22 @@ class JSONField(CheckFieldDefaultMixin, Field):
         self.decoder = decoder
         super().__init__(**kwargs)
 
-    def preflight(self, **kwargs):
+    def preflight(self, **kwargs: Any) -> list[PreflightResult]:
         errors = super().preflight(**kwargs)
         errors.extend(self._check_supported())
         return errors
 
-    def _check_supported(self):
+    def _check_supported(self) -> list[PreflightResult]:
         errors = []
 
         if (
-            self.model._meta.required_db_vendor
-            and self.model._meta.required_db_vendor != db_connection.vendor
+            self.model.model_options.required_db_vendor
+            and self.model.model_options.required_db_vendor != db_connection.vendor
         ):
             return errors
 
         if not (
-            "supports_json_field" in self.model._meta.required_db_features
+            "supports_json_field" in self.model.model_options.required_db_features
             or db_connection.features.supports_json_field
         ):
             errors.append(
@@ -67,7 +77,7 @@ class JSONField(CheckFieldDefaultMixin, Field):
             )
         return errors
 
-    def deconstruct(self):
+    def deconstruct(self) -> tuple[str, str, list[Any], dict[str, Any]]:
         name, path, args, kwargs = super().deconstruct()
         if self.encoder is not None:
             kwargs["encoder"] = self.encoder
@@ -75,7 +85,9 @@ class JSONField(CheckFieldDefaultMixin, Field):
             kwargs["decoder"] = self.decoder
         return name, path, args, kwargs
 
-    def from_db_value(self, value, expression, connection):
+    def from_db_value(
+        self, value: Any, expression: Any, connection: BaseDatabaseWrapper
+    ) -> Any:
         if value is None:
             return value
         # Some backends (SQLite at least) extract non-string values in their
@@ -87,10 +99,12 @@ class JSONField(CheckFieldDefaultMixin, Field):
         except json.JSONDecodeError:
             return value
 
-    def get_internal_type(self):
+    def get_internal_type(self) -> str:
         return "JSONField"
 
-    def get_db_prep_value(self, value, connection, prepared=False):
+    def get_db_prep_value(
+        self, value: Any, connection: BaseDatabaseWrapper, prepared: bool = False
+    ) -> Any:
         if isinstance(value, expressions.Value) and isinstance(
             value.output_field, JSONField
         ):
@@ -99,18 +113,18 @@ class JSONField(CheckFieldDefaultMixin, Field):
             return value
         return connection.ops.adapt_json_value(value, self.encoder)
 
-    def get_db_prep_save(self, value, connection):
+    def get_db_prep_save(self, value: Any, connection: BaseDatabaseWrapper) -> Any:
         if value is None:
             return value
         return self.get_db_prep_value(value, connection)
 
-    def get_transform(self, name):
+    def get_transform(self, name: str) -> KeyTransformFactory | type[Transform]:
         transform = super().get_transform(name)
         if transform:
             return transform
         return KeyTransformFactory(name)
 
-    def validate(self, value, model_instance):
+    def validate(self, value: Any, model_instance: Any) -> None:
         super().validate(value, model_instance)
         try:
             json.dumps(value, cls=self.encoder)
@@ -121,11 +135,11 @@ class JSONField(CheckFieldDefaultMixin, Field):
                 params={"value": value},
             )
 
-    def value_to_string(self, obj):
+    def value_to_string(self, obj: Any) -> Any:
         return self.value_from_object(obj)
 
 
-def compile_json_path(key_transforms, include_root=True):
+def compile_json_path(key_transforms: list[Any], include_root: bool = True) -> str:
     path = ["$"] if include_root else []
     for key_transform in key_transforms:
         try:
@@ -142,7 +156,9 @@ class DataContains(FieldGetDbPrepValueMixin, PostgresOperatorLookup):
     lookup_name = "contains"
     postgres_operator = "@>"
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         if not connection.features.supports_json_field_contains:
             raise NotSupportedError(
                 "contains lookup is not supported on this database backend."
@@ -157,7 +173,9 @@ class ContainedBy(FieldGetDbPrepValueMixin, PostgresOperatorLookup):
     lookup_name = "contained_by"
     postgres_operator = "<@"
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         if not connection.features.supports_json_field_contains:
             raise NotSupportedError(
                 "contained_by lookup is not supported on this database backend."
@@ -169,13 +187,18 @@ class ContainedBy(FieldGetDbPrepValueMixin, PostgresOperatorLookup):
 
 
 class HasKeyLookup(PostgresOperatorLookup):
-    logical_operator = None
+    logical_operator: str | None = None
 
-    def compile_json_path_final_key(self, key_transform):
+    def compile_json_path_final_key(self, key_transform: Any) -> str:
         # Compile the final key without interpreting ints as array elements.
         return f".{json.dumps(key_transform)}"
 
-    def as_sql(self, compiler, connection, template=None):
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        template: str | None = None,
+    ) -> tuple[str, tuple[Any, ...]]:
         # Process JSON path from the left-hand side.
         if isinstance(self.lhs, KeyTransform):
             lhs, lhs_params, lhs_key_transforms = self.lhs.preprocess_lhs(
@@ -205,12 +228,16 @@ class HasKeyLookup(PostgresOperatorLookup):
             sql = f"({self.logical_operator.join([sql] * len(rhs_params))})"
         return sql, tuple(lhs_params) + tuple(rhs_params)
 
-    def as_mysql(self, compiler, connection):
+    def as_mysql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         return self.as_sql(
             compiler, connection, template="JSON_CONTAINS_PATH(%s, 'one', %%s)"
         )
 
-    def as_postgresql(self, compiler, connection):
+    def as_postgresql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         if isinstance(self.rhs, KeyTransform):
             *_, rhs_key_transforms = self.rhs.preprocess_lhs(compiler, connection)
             for key in rhs_key_transforms[:-1]:
@@ -218,7 +245,9 @@ class HasKeyLookup(PostgresOperatorLookup):
             self.rhs = rhs_key_transforms[-1]
         return super().as_postgresql(compiler, connection)
 
-    def as_sqlite(self, compiler, connection):
+    def as_sqlite(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         return self.as_sql(
             compiler, connection, template="JSON_TYPE(%s, %%s) IS NOT NULL"
         )
@@ -235,7 +264,7 @@ class HasKeys(HasKeyLookup):
     postgres_operator = "?&"
     logical_operator = " AND "
 
-    def get_prep_lookup(self):
+    def get_prep_lookup(self) -> list[str]:
         return [str(item) for item in self.rhs]
 
 
@@ -246,7 +275,7 @@ class HasAnyKeys(HasKeys):
 
 
 class HasKeyOrArrayIndex(HasKey):
-    def compile_json_path_final_key(self, key_transform):
+    def compile_json_path_final_key(self, key_transform: Any) -> str:
         return compile_json_path([key_transform], include_root=False)
 
 
@@ -258,14 +287,18 @@ class CaseInsensitiveMixin:
     case-sensitive.
     """
 
-    def process_lhs(self, compiler, connection):
-        lhs, lhs_params = super().process_lhs(compiler, connection)
+    def process_lhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, list[Any]]:
+        lhs, lhs_params = super().process_lhs(compiler, connection)  # type: ignore[misc]
         if connection.vendor == "mysql":
             return f"LOWER({lhs})", lhs_params
         return lhs, lhs_params
 
-    def process_rhs(self, compiler, connection):
-        rhs, rhs_params = super().process_rhs(compiler, connection)
+    def process_rhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, list[Any]]:
+        rhs, rhs_params = super().process_rhs(compiler, connection)  # type: ignore[misc]
         if connection.vendor == "mysql":
             return f"LOWER({rhs})", rhs_params
         return rhs, rhs_params
@@ -274,7 +307,9 @@ class CaseInsensitiveMixin:
 class JSONExact(lookups.Exact):
     can_use_none_as_rhs = True
 
-    def process_rhs(self, compiler, connection):
+    def process_rhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, list[Any]]:
         rhs, rhs_params = super().process_rhs(compiler, connection)
         # Treat None lookup values as null.
         if rhs == "%s" and rhs_params == [None]:
@@ -302,11 +337,13 @@ class KeyTransform(Transform):
     postgres_operator = "->"
     postgres_nested_operator = "#>"
 
-    def __init__(self, key_name, *args, **kwargs):
+    def __init__(self, key_name: str, *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
         self.key_name = str(key_name)
 
-    def preprocess_lhs(self, compiler, connection):
+    def preprocess_lhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...], list[str]]:
         key_transforms = [self.key_name]
         previous = self.lhs
         while isinstance(previous, KeyTransform):
@@ -315,12 +352,16 @@ class KeyTransform(Transform):
         lhs, params = compiler.compile(previous)
         return lhs, params, key_transforms
 
-    def as_mysql(self, compiler, connection):
+    def as_mysql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         lhs, params, key_transforms = self.preprocess_lhs(compiler, connection)
         json_path = compile_json_path(key_transforms)
         return f"JSON_EXTRACT({lhs}, %s)", tuple(params) + (json_path,)
 
-    def as_postgresql(self, compiler, connection):
+    def as_postgresql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         lhs, params, key_transforms = self.preprocess_lhs(compiler, connection)
         if len(key_transforms) > 1:
             sql = f"({lhs} {self.postgres_nested_operator} %s)"
@@ -331,11 +372,17 @@ class KeyTransform(Transform):
             lookup = self.key_name
         return f"({lhs} {self.postgres_operator} %s)", tuple(params) + (lookup,)
 
-    def as_sqlite(self, compiler, connection):
+    def as_sqlite(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
+        sqlite_connection = cast(SQLiteDatabaseWrapper, connection)
         lhs, params, key_transforms = self.preprocess_lhs(compiler, connection)
         json_path = compile_json_path(key_transforms)
         datatype_values = ",".join(
-            [repr(datatype) for datatype in connection.ops.jsonfield_datatype_values]
+            [
+                repr(datatype)
+                for datatype in sqlite_connection.ops.jsonfield_datatype_values  # type: ignore[attr-defined]
+            ]
         )
         return (
             f"(CASE WHEN JSON_TYPE({lhs}, %s) IN ({datatype_values}) "
@@ -348,8 +395,11 @@ class KeyTextTransform(KeyTransform):
     postgres_nested_operator = "#>>"
     output_field = TextField()
 
-    def as_mysql(self, compiler, connection):
-        if connection.mysql_is_mariadb:
+    def as_mysql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
+        mysql_connection = cast(MySQLDatabaseWrapper, connection)
+        if mysql_connection.mysql_is_mariadb:
             # MariaDB doesn't support -> and ->> operators (see MDEV-13594).
             sql, params = super().as_mysql(compiler, connection)
             return f"JSON_UNQUOTE({sql})", params
@@ -359,7 +409,7 @@ class KeyTextTransform(KeyTransform):
             return f"({lhs} ->> %s)", tuple(params) + (json_path,)
 
     @classmethod
-    def from_lookup(cls, lookup):
+    def from_lookup(cls, lookup: str) -> Any:
         transform, *keys = lookup.split(LOOKUP_SEP)
         if not keys:
             raise ValueError("Lookup must contain key or index transforms.")
@@ -379,7 +429,7 @@ class KeyTransformTextLookupMixin:
     representation.
     """
 
-    def __init__(self, key_transform, *args, **kwargs):
+    def __init__(self, key_transform: Any, *args: Any, **kwargs: Any):
         if not isinstance(key_transform, KeyTransform):
             raise TypeError(
                 "Transform should be an instance of KeyTransform in order to "
@@ -390,12 +440,14 @@ class KeyTransformTextLookupMixin:
             *key_transform.source_expressions,
             **key_transform.extra,
         )
-        super().__init__(key_text_transform, *args, **kwargs)
+        super().__init__(key_text_transform, *args, **kwargs)  # type: ignore[misc]
 
 
 class KeyTransformIsNull(lookups.IsNull):
     # key__isnull=False is the same as has_key='key'
-    def as_sqlite(self, compiler, connection):
+    def as_sqlite(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         template = "JSON_TYPE(%s, %%s) IS NULL"
         if not self.rhs:
             template = "JSON_TYPE(%s, %%s) IS NOT NULL"
@@ -407,7 +459,13 @@ class KeyTransformIsNull(lookups.IsNull):
 
 
 class KeyTransformIn(lookups.In):
-    def resolve_expression_parameter(self, compiler, connection, sql, param):
+    def resolve_expression_parameter(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        sql: str,
+        param: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         sql, params = super().resolve_expression_parameter(
             compiler,
             connection,
@@ -418,25 +476,31 @@ class KeyTransformIn(lookups.In):
             not hasattr(param, "as_sql")
             and not connection.features.has_native_json_field
         ):
-            if connection.vendor == "mysql" or (
-                connection.vendor == "sqlite"
-                and params[0] not in connection.ops.jsonfield_datatype_values
-            ):
+            if connection.vendor == "mysql":
                 sql = "JSON_EXTRACT(%s, '$')"
-        if connection.vendor == "mysql" and connection.mysql_is_mariadb:
-            sql = f"JSON_UNQUOTE({sql})"
+            elif connection.vendor == "sqlite":
+                sqlite_connection = cast(SQLiteDatabaseWrapper, connection)
+                if params[0] not in sqlite_connection.ops.jsonfield_datatype_values:  # type: ignore[attr-defined]
+                    sql = "JSON_EXTRACT(%s, '$')"
+        if connection.vendor == "mysql":
+            mysql_connection = cast(MySQLDatabaseWrapper, connection)
+            if mysql_connection.mysql_is_mariadb:
+                sql = f"JSON_UNQUOTE({sql})"
         return sql, params
 
 
 class KeyTransformExact(JSONExact):
-    def process_rhs(self, compiler, connection):
+    def process_rhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, list[Any]]:
         if isinstance(self.rhs, KeyTransform):
             return super(lookups.Exact, self).process_rhs(compiler, connection)
         rhs, rhs_params = super().process_rhs(compiler, connection)
         if connection.vendor == "sqlite":
+            sqlite_connection = cast(SQLiteDatabaseWrapper, connection)
             func = []
             for value in rhs_params:
-                if value in connection.ops.jsonfield_datatype_values:
+                if value in sqlite_connection.ops.jsonfield_datatype_values:  # type: ignore[attr-defined]
                     func.append("%s")
                 else:
                     func.append("JSON_EXTRACT(%s, '$')")
@@ -487,8 +551,10 @@ class KeyTransformIRegex(
 
 
 class KeyTransformNumericLookupMixin:
-    def process_rhs(self, compiler, connection):
-        rhs, rhs_params = super().process_rhs(compiler, connection)
+    def process_rhs(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, list[Any]]:
+        rhs, rhs_params = super().process_rhs(compiler, connection)  # type: ignore[misc]
         if not connection.features.has_native_json_field:
             rhs_params = [json.loads(value) for value in rhs_params]
         return rhs, rhs_params
@@ -529,8 +595,8 @@ KeyTransform.register_lookup(KeyTransformGte)
 
 
 class KeyTransformFactory:
-    def __init__(self, key_name):
+    def __init__(self, key_name: str):
         self.key_name = key_name
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args: Any, **kwargs: Any) -> KeyTransform:
         return KeyTransform(self.key_name, *args, **kwargs)

plain/models/fields/mixins.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.preflight import PreflightResult
 
 NOT_PROVIDED = object()
@@ -6,10 +10,10 @@ NOT_PROVIDED = object()
 class FieldCacheMixin:
     """Provide an API for working with the model's fields value cache."""
 
-    def get_cache_name(self):
+    def get_cache_name(self) -> str:
         raise NotImplementedError
 
-    def get_cached_value(self, instance, default=NOT_PROVIDED):
+    def get_cached_value(self, instance: Any, default: Any = NOT_PROVIDED) -> Any:
         cache_name = self.get_cache_name()
         try:
             return instance._state.fields_cache[cache_name]
@@ -18,20 +22,20 @@ class FieldCacheMixin:
                 raise
             return default
 
-    def is_cached(self, instance):
+    def is_cached(self, instance: Any) -> bool:
         return self.get_cache_name() in instance._state.fields_cache
 
-    def set_cached_value(self, instance, value):
+    def set_cached_value(self, instance: Any, value: Any) -> None:
         instance._state.fields_cache[self.get_cache_name()] = value
 
-    def delete_cached_value(self, instance):
+    def delete_cached_value(self, instance: Any) -> None:
         del instance._state.fields_cache[self.get_cache_name()]
 
 
 class CheckFieldDefaultMixin:
     _default_fix = ("<valid default>", "<invalid default>")
 
-    def _check_default(self):
+    def _check_default(self) -> list[PreflightResult]:  # type: ignore[misc]
         if (
             self.has_default()
             and self.default is not None
@@ -53,7 +57,7 @@ class CheckFieldDefaultMixin:
         else:
             return []
 
-    def preflight(self, **kwargs):
-        errors = super().preflight(**kwargs)
+    def preflight(self, **kwargs: Any) -> list[PreflightResult]:  # type: ignore[misc]
+        errors = super().preflight(**kwargs)  # type: ignore[misc]
         errors.extend(self._check_default())
         return errors