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

plain/models/functions/comparison.py

@@ -1,11 +1,19 @@
 """Database functions that do comparisons or type conversions."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from plain.models.db import NotSupportedError
 from plain.models.expressions import Func, Value
-from plain.models.fields import TextField
+from plain.models.fields import Field, TextField
 from plain.models.fields.json import JSONField
 from plain.utils.regex_helper import _lazy_re_compile
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.sql.compiler import SQLCompiler
+
 
 class Cast(Func):
     """Coerce an expression to a new field type."""
@@ -13,14 +21,24 @@ class Cast(Func):
     function = "CAST"
     template = "%(function)s(%(expressions)s AS %(db_type)s)"
 
-    def __init__(self, expression, output_field):
+    def __init__(self, expression: Any, output_field: Field) -> None:
         super().__init__(expression, output_field=output_field)
 
-    def as_sql(self, compiler, connection, **extra_context):
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         extra_context["db_type"] = self.output_field.cast_db_type(connection)
         return super().as_sql(compiler, connection, **extra_context)
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         db_type = self.output_field.db_type(connection)
         if db_type in {"datetime", "time"}:
             # Use strftime as datetime/time don't keep fractional seconds.
@@ -38,18 +56,28 @@ class Cast(Func):
             )
         return self.as_sql(compiler, connection, **extra_context)
 
-    def as_mysql(self, compiler, connection, **extra_context):
+    def as_mysql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         template = None
         output_type = self.output_field.get_internal_type()
         # MySQL doesn't support explicit cast to float.
         if output_type == "FloatField":
             template = "(%(expressions)s + 0.0)"
         # MariaDB doesn't support explicit cast to JSON.
-        elif output_type == "JSONField" and connection.mysql_is_mariadb:
+        elif output_type == "JSONField" and connection.mysql_is_mariadb:  # type: ignore[attr-defined]
             template = "JSON_EXTRACT(%(expressions)s, '$')"
         return self.as_sql(compiler, connection, template=template, **extra_context)
 
-    def as_postgresql(self, compiler, connection, **extra_context):
+    def as_postgresql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         # CAST would be valid too, but the :: shortcut syntax is more readable.
         # 'expressions' is wrapped in parentheses in case it's a complex
         # expression.
@@ -66,13 +94,13 @@ class Coalesce(Func):
 
     function = "COALESCE"
 
-    def __init__(self, *expressions, **extra):
+    def __init__(self, *expressions: Any, **extra: Any) -> None:
         if len(expressions) < 2:
             raise ValueError("Coalesce must take at least two expressions")
         super().__init__(*expressions, **extra)
 
     @property
-    def empty_result_set_value(self):
+    def empty_result_set_value(self) -> Any:
         for expression in self.get_source_expressions():
             result = expression.empty_result_set_value
             if result is NotImplemented or result is not None:
@@ -87,13 +115,18 @@ class Collate(Func):
     # https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
     collation_re = _lazy_re_compile(r"^[\w\-]+$")
 
-    def __init__(self, expression, collation):
+    def __init__(self, expression: Any, collation: str) -> None:
         if not (collation and self.collation_re.match(collation)):
             raise ValueError(f"Invalid collation name: {collation!r}.")
         self.collation = collation
         super().__init__(expression)
 
-    def as_sql(self, compiler, connection, **extra_context):
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         extra_context.setdefault("collation", connection.ops.quote_name(self.collation))
         return super().as_sql(compiler, connection, **extra_context)
 
@@ -109,12 +142,17 @@ class Greatest(Func):
 
     function = "GREATEST"
 
-    def __init__(self, *expressions, **extra):
+    def __init__(self, *expressions: Any, **extra: Any) -> None:
         if len(expressions) < 2:
             raise ValueError("Greatest must take at least two expressions")
         super().__init__(*expressions, **extra)
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         """Use the MAX function on SQLite."""
         return super().as_sqlite(compiler, connection, function="MAX", **extra_context)
 
@@ -123,20 +161,30 @@ class JSONObject(Func):
     function = "JSON_OBJECT"
     output_field = JSONField()
 
-    def __init__(self, **fields):
+    def __init__(self, **fields: Any) -> None:
         expressions = []
         for key, value in fields.items():
             expressions.extend((Value(key), value))
         super().__init__(*expressions)
 
-    def as_sql(self, compiler, connection, **extra_context):
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         if not connection.features.has_json_object_function:
             raise NotSupportedError(
                 "JSONObject() is not supported on this database backend."
             )
         return super().as_sql(compiler, connection, **extra_context)
 
-    def as_postgresql(self, compiler, connection, **extra_context):
+    def as_postgresql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         copy = self.copy()
         copy.set_source_expressions(
             [
@@ -163,12 +211,17 @@ class Least(Func):
 
     function = "LEAST"
 
-    def __init__(self, *expressions, **extra):
+    def __init__(self, *expressions: Any, **extra: Any) -> None:
         if len(expressions) < 2:
             raise ValueError("Least must take at least two expressions")
         super().__init__(*expressions, **extra)
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         """Use the MIN function on SQLite."""
         return super().as_sqlite(compiler, connection, function="MIN", **extra_context)
 

plain/models/functions/datetime.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 from datetime import datetime
+from typing import TYPE_CHECKING, Any
 
 from plain.models.expressions import Func
 from plain.models.fields import (
@@ -19,11 +22,15 @@ from plain.models.lookups import (
 )
 from plain.utils import timezone
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.sql.compiler import SQLCompiler
+
 
 class TimezoneMixin:
     tzinfo = None
 
-    def get_tzname(self):
+    def get_tzname(self) -> str | None:
         # Timezone conversions must happen to the input datetime *before*
         # applying a function. 2015-12-31 23:00:00 -02:00 is stored in the
         # database as 2016-01-01 01:00:00 +00:00. Any results should be
@@ -38,7 +45,13 @@ class Extract(TimezoneMixin, Transform):
     lookup_name = None
     output_field = IntegerField()
 
-    def __init__(self, expression, lookup_name=None, tzinfo=None, **extra):
+    def __init__(
+        self,
+        expression: Any,
+        lookup_name: str | None = None,
+        tzinfo: Any = None,
+        **extra: Any,
+    ) -> None:
         if self.lookup_name is None:
             self.lookup_name = lookup_name
         if self.lookup_name is None:
@@ -46,7 +59,9 @@ class Extract(TimezoneMixin, Transform):
         self.tzinfo = tzinfo
         super().__init__(expression, **extra)
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         sql, params = compiler.compile(self.lhs)
         lhs_output_field = self.lhs.output_field
         if isinstance(lhs_output_field, DateTimeField):
@@ -76,11 +91,16 @@ class Extract(TimezoneMixin, Transform):
             # resolve_expression has already validated the output_field so this
             # assert should never be hit.
             raise ValueError("Tried to Extract from an invalid type.")
-        return sql, params
+        return sql, tuple(params) if isinstance(params, list) else params
 
     def resolve_expression(
-        self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False
-    ):
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Extract:
         copy = super().resolve_expression(
             query, allow_joins, reuse, summarize, for_save
         )
@@ -209,7 +229,12 @@ class Now(Func):
     template = "CURRENT_TIMESTAMP"
     output_field = DateTimeField()
 
-    def as_postgresql(self, compiler, connection, **extra_context):
+    def as_postgresql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         # PostgreSQL's CURRENT_TIMESTAMP means "the time at the start of the
         # transaction". Use STATEMENT_TIMESTAMP to be cross-compatible with
         # other databases.
@@ -217,12 +242,22 @@ class Now(Func):
             compiler, connection, template="STATEMENT_TIMESTAMP()", **extra_context
         )
 
-    def as_mysql(self, compiler, connection, **extra_context):
+    def as_mysql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         return self.as_sql(
             compiler, connection, template="CURRENT_TIMESTAMP(6)", **extra_context
         )
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         return self.as_sql(
             compiler,
             connection,
@@ -237,15 +272,17 @@ class TruncBase(TimezoneMixin, Transform):
 
     def __init__(
         self,
-        expression,
-        output_field=None,
-        tzinfo=None,
-        **extra,
-    ):
+        expression: Any,
+        output_field: Field | None = None,
+        tzinfo: Any = None,
+        **extra: Any,
+    ) -> None:
         self.tzinfo = tzinfo
         super().__init__(expression, output_field=output_field, **extra)
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         sql, params = compiler.compile(self.lhs)
         tzname = None
         if isinstance(self.lhs.output_field, DateTimeField):
@@ -268,11 +305,16 @@ class TruncBase(TimezoneMixin, Transform):
             raise ValueError(
                 "Trunc only valid on DateField, TimeField, or DateTimeField."
             )
-        return sql, params
+        return sql, tuple(params) if isinstance(params, list) else params
 
     def resolve_expression(
-        self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False
-    ):
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> TruncBase:
         copy = super().resolve_expression(
             query, allow_joins, reuse, summarize, for_save
         )
@@ -325,7 +367,9 @@ class TruncBase(TimezoneMixin, Transform):
             )
         return copy
 
-    def convert_value(self, value, expression, connection):
+    def convert_value(
+        self, value: Any, expression: Any, connection: BaseDatabaseWrapper
+    ) -> Any:
         if isinstance(self.output_field, DateTimeField):
             if value is not None:
                 value = value.replace(tzinfo=None)
@@ -348,12 +392,12 @@ class TruncBase(TimezoneMixin, Transform):
 class Trunc(TruncBase):
     def __init__(
         self,
-        expression,
-        kind,
-        output_field=None,
-        tzinfo=None,
-        **extra,
-    ):
+        expression: Any,
+        kind: str,
+        output_field: Field | None = None,
+        tzinfo: Any = None,
+        **extra: Any,
+    ) -> None:
         self.kind = kind
         super().__init__(expression, output_field=output_field, tzinfo=tzinfo, **extra)
 
@@ -385,11 +429,14 @@ class TruncDate(TruncBase):
     lookup_name = "date"
     output_field = DateField()
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         # Cast to date rather than truncate to date.
         sql, params = compiler.compile(self.lhs)
         tzname = self.get_tzname()
-        return connection.ops.datetime_cast_date_sql(sql, tuple(params), tzname)
+        sql, params = connection.ops.datetime_cast_date_sql(sql, tuple(params), tzname)
+        return sql, tuple(params) if isinstance(params, list) else params
 
 
 class TruncTime(TruncBase):
@@ -397,11 +444,14 @@ class TruncTime(TruncBase):
     lookup_name = "time"
     output_field = TimeField()
 
-    def as_sql(self, compiler, connection):
+    def as_sql(
+        self, compiler: SQLCompiler, connection: BaseDatabaseWrapper
+    ) -> tuple[str, tuple[Any, ...]]:
         # Cast to time rather than truncate to time.
         sql, params = compiler.compile(self.lhs)
         tzname = self.get_tzname()
-        return connection.ops.datetime_cast_time_sql(sql, tuple(params), tzname)
+        sql, params = connection.ops.datetime_cast_time_sql(sql, tuple(params), tzname)
+        return sql, tuple(params) if isinstance(params, list) else params
 
 
 class TruncHour(TruncBase):

plain/models/functions/math.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from plain.models.expressions import Func, Value
-from plain.models.fields import FloatField, IntegerField
+from plain.models.fields import Field, FloatField, IntegerField
 from plain.models.functions import Cast
 from plain.models.functions.mixins import (
     FixDecimalInputMixin,
@@ -7,6 +11,10 @@ from plain.models.functions.mixins import (
 )
 from plain.models.lookups import Transform
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.sql.compiler import SQLCompiler
+
 
 class Abs(Transform):
     function = "ABS"
@@ -32,10 +40,15 @@ class ATan2(NumericOutputFieldMixin, Func):
     function = "ATAN2"
     arity = 2
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         if not getattr(
             connection.ops, "spatialite", False
-        ) or connection.ops.spatial_version >= (5, 0, 0):
+        ) or connection.ops.spatial_version >= (5, 0, 0):  # type: ignore[attr-defined]
             return self.as_sql(compiler, connection)
         # This function is usually ATan2(y, x), returning the inverse tangent
         # of y / x, but it's ATan2(x, y) on SpatiaLite < 5.0.0.
@@ -93,7 +106,12 @@ class Log(FixDecimalInputMixin, NumericOutputFieldMixin, Func):
     function = "LOG"
     arity = 2
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         if not getattr(connection.ops, "spatialite", False):
             return self.as_sql(compiler, connection)
         # This function is usually Log(b, x) returning the logarithm of x to
@@ -127,13 +145,23 @@ class Random(NumericOutputFieldMixin, Func):
     function = "RANDOM"
     arity = 0
 
-    def as_mysql(self, compiler, connection, **extra_context):
+    def as_mysql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         return super().as_sql(compiler, connection, function="RAND", **extra_context)
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         return super().as_sql(compiler, connection, function="RAND", **extra_context)
 
-    def get_group_by_cols(self):
+    def get_group_by_cols(self) -> list[Any]:
         return []
 
 
@@ -142,16 +170,21 @@ class Round(FixDecimalInputMixin, Transform):
     lookup_name = "round"
     arity = None  # Override Transform's arity=1 to enable passing precision.
 
-    def __init__(self, expression, precision=0, **extra):
+    def __init__(self, expression: Any, precision: int = 0, **extra: Any) -> None:
         super().__init__(expression, precision, **extra)
 
-    def as_sqlite(self, compiler, connection, **extra_context):
+    def as_sqlite(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         precision = self.get_source_expressions()[1]
         if isinstance(precision, Value) and precision.value < 0:
             raise ValueError("SQLite does not support negative precision.")
         return super().as_sqlite(compiler, connection, **extra_context)
 
-    def _resolve_output_field(self):
+    def _resolve_output_field(self) -> Field:
         source = self.get_source_expressions()[0]
         return source.output_field
 

plain/models/functions/mixins.py

@@ -1,11 +1,23 @@
+from __future__ import annotations
+
 import sys
+from typing import TYPE_CHECKING, Any
 
 from plain.models.fields import DecimalField, FloatField, IntegerField
 from plain.models.functions import Cast
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.sql.compiler import SQLCompiler
+
 
 class FixDecimalInputMixin:
-    def as_postgresql(self, compiler, connection, **extra_context):
+    def as_postgresql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         # Cast FloatField to DecimalField as PostgreSQL doesn't support the
         # following function signatures:
         # - LOG(double, double)
@@ -24,18 +36,23 @@ class FixDecimalInputMixin:
 
 
 class FixDurationInputMixin:
-    def as_mysql(self, compiler, connection, **extra_context):
-        sql, params = super().as_sql(compiler, connection, **extra_context)
-        if self.output_field.get_internal_type() == "DurationField":
+    def as_mysql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
+        sql, params = super().as_sql(compiler, connection, **extra_context)  # type: ignore[misc]
+        if self.output_field.get_internal_type() == "DurationField":  # type: ignore[attr-defined]
             sql = f"CAST({sql} AS SIGNED)"
         return sql, params
 
 
 class NumericOutputFieldMixin:
-    def _resolve_output_field(self):
-        source_fields = self.get_source_fields()
+    def _resolve_output_field(self) -> DecimalField | FloatField:
+        source_fields = self.get_source_fields()  # type: ignore[attr-defined]
         if any(isinstance(s, DecimalField) for s in source_fields):
             return DecimalField()
         if any(isinstance(s, IntegerField) for s in source_fields):
             return FloatField()
-        return super()._resolve_output_field() if source_fields else FloatField()
+        return super()._resolve_output_field() if source_fields else FloatField()  # type: ignore[misc]