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

plain/models/backends/sqlite3/_functions.py

@@ -2,11 +2,13 @@
 Implementations of SQL functions for SQLite.
 """
 
+from __future__ import annotations
+
 import functools
 import random
 import statistics
 import zoneinfo
-from datetime import timedelta
+from datetime import date, datetime, time, timedelta
 from hashlib import md5, sha1, sha224, sha256, sha384, sha512
 from math import (
     acos,
@@ -27,6 +29,7 @@ from math import (
     tan,
 )
 from re import search as re_search
+from typing import TYPE_CHECKING, Any
 
 from plain.models.backends.utils import (
     split_tzname_delta,
@@ -36,10 +39,13 @@ from plain.models.backends.utils import (
 from plain.utils import timezone
 from plain.utils.duration import duration_microseconds
 
+if TYPE_CHECKING:
+    from plain.models.backends.sqlite3.base import SQLiteDatabaseWrapper
+
 
-def register(connection):
+def register(connection: SQLiteDatabaseWrapper) -> None:
     create_deterministic_function = functools.partial(
-        connection.create_function,
+        connection.create_function,  # type: ignore[attr-defined]
         deterministic=True,
     )
     create_deterministic_function("plain_date_extract", 2, _sqlite_datetime_extract)
@@ -73,14 +79,14 @@ def register(connection):
     create_deterministic_function("SIGN", 1, _sqlite_sign)
     # Don't use the built-in RANDOM() function because it returns a value
     # in the range [-1 * 2^63, 2^63 - 1] instead of [0, 1).
-    connection.create_function("RAND", 0, random.random)
-    connection.create_aggregate("STDDEV_POP", 1, StdDevPop)
-    connection.create_aggregate("STDDEV_SAMP", 1, StdDevSamp)
-    connection.create_aggregate("VAR_POP", 1, VarPop)
-    connection.create_aggregate("VAR_SAMP", 1, VarSamp)
+    connection.create_function("RAND", 0, random.random)  # type: ignore[attr-defined]
+    connection.create_aggregate("STDDEV_POP", 1, StdDevPop)  # type: ignore[attr-defined]
+    connection.create_aggregate("STDDEV_SAMP", 1, StdDevSamp)  # type: ignore[attr-defined]
+    connection.create_aggregate("VAR_POP", 1, VarPop)  # type: ignore[attr-defined]
+    connection.create_aggregate("VAR_SAMP", 1, VarSamp)  # type: ignore[attr-defined]
     # Some math functions are enabled by default in SQLite 3.35+.
     sql = "select sqlite_compileoption_used('ENABLE_MATH_FUNCTIONS')"
-    if not connection.execute(sql).fetchone()[0]:
+    if not connection.execute(sql).fetchone()[0]:  # type: ignore[union-attr]
         create_deterministic_function("ACOS", 1, _sqlite_acos)
         create_deterministic_function("ASIN", 1, _sqlite_asin)
         create_deterministic_function("ATAN", 1, _sqlite_atan)
@@ -101,138 +107,162 @@ def register(connection):
         create_deterministic_function("TAN", 1, _sqlite_tan)
 
 
-def _sqlite_datetime_parse(dt, tzname=None, conn_tzname=None):
+def _sqlite_datetime_parse(
+    dt: str | None, tzname: str | None = None, conn_tzname: str | None = None
+) -> date | datetime | None:
     if dt is None:
         return None
     try:
-        dt = typecast_timestamp(dt)
+        parsed_dt: date | datetime | None = typecast_timestamp(dt)
     except (TypeError, ValueError):
         return None
     if conn_tzname:
-        dt = dt.replace(tzinfo=zoneinfo.ZoneInfo(conn_tzname))
+        parsed_dt = parsed_dt.replace(tzinfo=zoneinfo.ZoneInfo(conn_tzname))  # type: ignore[union-attr]
     if tzname is not None and tzname != conn_tzname:
         tzname, sign, offset = split_tzname_delta(tzname)
         if offset:
             hours, minutes = offset.split(":")
             offset_delta = timedelta(hours=int(hours), minutes=int(minutes))
-            dt += offset_delta if sign == "+" else -offset_delta
-        dt = timezone.localtime(dt, zoneinfo.ZoneInfo(tzname))
-    return dt
+            parsed_dt += offset_delta if sign == "+" else -offset_delta  # type: ignore[assignment,operator]
+        parsed_dt = timezone.localtime(parsed_dt, zoneinfo.ZoneInfo(tzname))  # type: ignore[arg-type]
+    return parsed_dt
 
 
-def _sqlite_date_trunc(lookup_type, dt, tzname, conn_tzname):
-    dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
-    if dt is None:
+def _sqlite_date_trunc(
+    lookup_type: str, dt: str | None, tzname: str | None, conn_tzname: str | None
+) -> str | None:
+    parsed_dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    if parsed_dt is None:
         return None
     if lookup_type == "year":
-        return f"{dt.year:04d}-01-01"
+        return f"{parsed_dt.year:04d}-01-01"
     elif lookup_type == "quarter":
-        month_in_quarter = dt.month - (dt.month - 1) % 3
-        return f"{dt.year:04d}-{month_in_quarter:02d}-01"
+        month_in_quarter = parsed_dt.month - (parsed_dt.month - 1) % 3
+        return f"{parsed_dt.year:04d}-{month_in_quarter:02d}-01"
     elif lookup_type == "month":
-        return f"{dt.year:04d}-{dt.month:02d}-01"
+        return f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-01"
     elif lookup_type == "week":
-        dt -= timedelta(days=dt.weekday())
-        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d}"
+        parsed_dt -= timedelta(days=parsed_dt.weekday())  # type: ignore[operator]
+        return f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d}"
     elif lookup_type == "day":
-        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d}"
+        return f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d}"
     raise ValueError(f"Unsupported lookup type: {lookup_type!r}")
 
 
-def _sqlite_time_trunc(lookup_type, dt, tzname, conn_tzname):
+def _sqlite_time_trunc(
+    lookup_type: str, dt: str | None, tzname: str | None, conn_tzname: str | None
+) -> str | None:
     if dt is None:
         return None
     dt_parsed = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    result: date | datetime | time | None
     if dt_parsed is None:
         try:
-            dt = typecast_time(dt)
+            result = typecast_time(dt)
         except (ValueError, TypeError):
             return None
     else:
-        dt = dt_parsed
+        result = dt_parsed
     if lookup_type == "hour":
-        return f"{dt.hour:02d}:00:00"
+        return f"{result.hour:02d}:00:00"  # type: ignore[union-attr]
     elif lookup_type == "minute":
-        return f"{dt.hour:02d}:{dt.minute:02d}:00"
+        return f"{result.hour:02d}:{result.minute:02d}:00"  # type: ignore[union-attr]
     elif lookup_type == "second":
-        return f"{dt.hour:02d}:{dt.minute:02d}:{dt.second:02d}"
+        return f"{result.hour:02d}:{result.minute:02d}:{result.second:02d}"  # type: ignore[union-attr]
     raise ValueError(f"Unsupported lookup type: {lookup_type!r}")
 
 
-def _sqlite_datetime_cast_date(dt, tzname, conn_tzname):
-    dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
-    if dt is None:
+def _sqlite_datetime_cast_date(
+    dt: str | None, tzname: str | None, conn_tzname: str | None
+) -> str | None:
+    parsed_dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    if parsed_dt is None:
         return None
-    return dt.date().isoformat()
+    return parsed_dt.date().isoformat()  # type: ignore[union-attr]
 
 
-def _sqlite_datetime_cast_time(dt, tzname, conn_tzname):
-    dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
-    if dt is None:
+def _sqlite_datetime_cast_time(
+    dt: str | None, tzname: str | None, conn_tzname: str | None
+) -> str | None:
+    parsed_dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    if parsed_dt is None:
         return None
-    return dt.time().isoformat()
+    return parsed_dt.time().isoformat()  # type: ignore[union-attr]
 
 
-def _sqlite_datetime_extract(lookup_type, dt, tzname=None, conn_tzname=None):
-    dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
-    if dt is None:
+def _sqlite_datetime_extract(
+    lookup_type: str,
+    dt: str | None,
+    tzname: str | None = None,
+    conn_tzname: str | None = None,
+) -> int | None:
+    parsed_dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    if parsed_dt is None:
         return None
     if lookup_type == "week_day":
-        return (dt.isoweekday() % 7) + 1
+        return (parsed_dt.isoweekday() % 7) + 1  # type: ignore[union-attr]
     elif lookup_type == "iso_week_day":
-        return dt.isoweekday()
+        return parsed_dt.isoweekday()  # type: ignore[union-attr]
     elif lookup_type == "week":
-        return dt.isocalendar().week
+        return parsed_dt.isocalendar().week  # type: ignore[union-attr]
     elif lookup_type == "quarter":
-        return ceil(dt.month / 3)
+        return ceil(parsed_dt.month / 3)
     elif lookup_type == "iso_year":
-        return dt.isocalendar().year
+        return parsed_dt.isocalendar().year  # type: ignore[union-attr]
     else:
-        return getattr(dt, lookup_type)
+        return getattr(parsed_dt, lookup_type)
 
 
-def _sqlite_datetime_trunc(lookup_type, dt, tzname, conn_tzname):
-    dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
-    if dt is None:
+def _sqlite_datetime_trunc(
+    lookup_type: str, dt: str | None, tzname: str | None, conn_tzname: str | None
+) -> str | None:
+    parsed_dt = _sqlite_datetime_parse(dt, tzname, conn_tzname)
+    if parsed_dt is None:
         return None
     if lookup_type == "year":
-        return f"{dt.year:04d}-01-01 00:00:00"
+        return f"{parsed_dt.year:04d}-01-01 00:00:00"
     elif lookup_type == "quarter":
-        month_in_quarter = dt.month - (dt.month - 1) % 3
-        return f"{dt.year:04d}-{month_in_quarter:02d}-01 00:00:00"
+        month_in_quarter = parsed_dt.month - (parsed_dt.month - 1) % 3
+        return f"{parsed_dt.year:04d}-{month_in_quarter:02d}-01 00:00:00"
     elif lookup_type == "month":
-        return f"{dt.year:04d}-{dt.month:02d}-01 00:00:00"
+        return f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-01 00:00:00"
     elif lookup_type == "week":
-        dt -= timedelta(days=dt.weekday())
-        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d} 00:00:00"
+        parsed_dt -= timedelta(days=parsed_dt.weekday())  # type: ignore[operator]
+        return (
+            f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d} 00:00:00"
+        )
     elif lookup_type == "day":
-        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d} 00:00:00"
+        return (
+            f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d} 00:00:00"
+        )
     elif lookup_type == "hour":
-        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d} {dt.hour:02d}:00:00"
+        return f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d} {parsed_dt.hour:02d}:00:00"  # type: ignore[union-attr]
     elif lookup_type == "minute":
         return (
-            f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d} "
-            f"{dt.hour:02d}:{dt.minute:02d}:00"
+            f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d} "
+            f"{parsed_dt.hour:02d}:{parsed_dt.minute:02d}:00"  # type: ignore[union-attr]
         )
     elif lookup_type == "second":
         return (
-            f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d} "
-            f"{dt.hour:02d}:{dt.minute:02d}:{dt.second:02d}"
+            f"{parsed_dt.year:04d}-{parsed_dt.month:02d}-{parsed_dt.day:02d} "
+            f"{parsed_dt.hour:02d}:{parsed_dt.minute:02d}:{parsed_dt.second:02d}"  # type: ignore[union-attr]
         )
     raise ValueError(f"Unsupported lookup type: {lookup_type!r}")
 
 
-def _sqlite_time_extract(lookup_type, dt):
+def _sqlite_time_extract(lookup_type: str, dt: str | None) -> int | None:
     if dt is None:
         return None
     try:
-        dt = typecast_time(dt)
+        parsed_time = typecast_time(dt)
     except (ValueError, TypeError):
         return None
-    return getattr(dt, lookup_type)
+    return getattr(parsed_time, lookup_type)  # type: ignore[union-attr]
 
 
-def _sqlite_prepare_dtdelta_param(conn, param):
+def _sqlite_prepare_dtdelta_param(
+    conn: str, param: Any
+) -> timedelta | date | datetime | Any:
     if conn in ["+", "-"]:
         if isinstance(param, int):
             return timedelta(0, 0, param)
@@ -241,7 +271,9 @@ def _sqlite_prepare_dtdelta_param(conn, param):
     return param
 
 
-def _sqlite_format_dtdelta(connector, lhs, rhs):
+def _sqlite_format_dtdelta(
+    connector: str | None, lhs: Any, rhs: Any
+) -> str | int | float | None:
     """
     LHS and RHS can be either:
     - An integer number of microseconds
@@ -259,42 +291,42 @@ def _sqlite_format_dtdelta(connector, lhs, rhs):
     if connector == "+":
         # typecast_timestamp() returns a date or a datetime without timezone.
         # It will be formatted as "%Y-%m-%d" or "%Y-%m-%d %H:%M:%S[.%f]"
-        out = str(real_lhs + real_rhs)
+        out = str(real_lhs + real_rhs)  # type: ignore[operator]
     elif connector == "-":
-        out = str(real_lhs - real_rhs)
+        out = str(real_lhs - real_rhs)  # type: ignore[operator]
     elif connector == "*":
-        out = real_lhs * real_rhs
+        out = real_lhs * real_rhs  # type: ignore[operator]
     else:
-        out = real_lhs / real_rhs
+        out = real_lhs / real_rhs  # type: ignore[operator]
     return out
 
 
-def _sqlite_time_diff(lhs, rhs):
+def _sqlite_time_diff(lhs: str | None, rhs: str | None) -> int | None:
     if lhs is None or rhs is None:
         return None
     left = typecast_time(lhs)
     right = typecast_time(rhs)
     return (
-        (left.hour * 60 * 60 * 1000000)
-        + (left.minute * 60 * 1000000)
-        + (left.second * 1000000)
-        + (left.microsecond)
-        - (right.hour * 60 * 60 * 1000000)
-        - (right.minute * 60 * 1000000)
-        - (right.second * 1000000)
-        - (right.microsecond)
+        (left.hour * 60 * 60 * 1000000)  # type: ignore[union-attr]
+        + (left.minute * 60 * 1000000)  # type: ignore[union-attr]
+        + (left.second * 1000000)  # type: ignore[union-attr]
+        + (left.microsecond)  # type: ignore[union-attr]
+        - (right.hour * 60 * 60 * 1000000)  # type: ignore[union-attr]
+        - (right.minute * 60 * 1000000)  # type: ignore[union-attr]
+        - (right.second * 1000000)  # type: ignore[union-attr]
+        - (right.microsecond)  # type: ignore[union-attr]
     )
 
 
-def _sqlite_timestamp_diff(lhs, rhs):
+def _sqlite_timestamp_diff(lhs: str | None, rhs: str | None) -> int | None:
     if lhs is None or rhs is None:
         return None
     left = typecast_timestamp(lhs)
     right = typecast_timestamp(rhs)
-    return duration_microseconds(left - right)
+    return duration_microseconds(left - right)  # type: ignore[arg-type,operator]
 
 
-def _sqlite_regexp(pattern, string):
+def _sqlite_regexp(pattern: str | None, string: Any) -> bool | None:
     if pattern is None or string is None:
         return None
     if not isinstance(string, str):
@@ -302,86 +334,88 @@ def _sqlite_regexp(pattern, string):
     return bool(re_search(pattern, string))
 
 
-def _sqlite_acos(x):
+def _sqlite_acos(x: float | None) -> float | None:
     if x is None:
         return None
     return acos(x)
 
 
-def _sqlite_asin(x):
+def _sqlite_asin(x: float | None) -> float | None:
     if x is None:
         return None
     return asin(x)
 
 
-def _sqlite_atan(x):
+def _sqlite_atan(x: float | None) -> float | None:
     if x is None:
         return None
     return atan(x)
 
 
-def _sqlite_atan2(y, x):
+def _sqlite_atan2(y: float | None, x: float | None) -> float | None:
     if y is None or x is None:
         return None
     return atan2(y, x)
 
 
-def _sqlite_bitxor(x, y):
+def _sqlite_bitxor(x: int | None, y: int | None) -> int | None:
     if x is None or y is None:
         return None
     return x ^ y
 
 
-def _sqlite_ceiling(x):
+def _sqlite_ceiling(x: float | None) -> float | None:
     if x is None:
         return None
     return ceil(x)
 
 
-def _sqlite_cos(x):
+def _sqlite_cos(x: float | None) -> float | None:
     if x is None:
         return None
     return cos(x)
 
 
-def _sqlite_cot(x):
+def _sqlite_cot(x: float | None) -> float | None:
     if x is None:
         return None
     return 1 / tan(x)
 
 
-def _sqlite_degrees(x):
+def _sqlite_degrees(x: float | None) -> float | None:
     if x is None:
         return None
     return degrees(x)
 
 
-def _sqlite_exp(x):
+def _sqlite_exp(x: float | None) -> float | None:
     if x is None:
         return None
     return exp(x)
 
 
-def _sqlite_floor(x):
+def _sqlite_floor(x: float | None) -> float | None:
     if x is None:
         return None
     return floor(x)
 
 
-def _sqlite_ln(x):
+def _sqlite_ln(x: float | None) -> float | None:
     if x is None:
         return None
     return log(x)
 
 
-def _sqlite_log(base, x):
+def _sqlite_log(base: float | None, x: float | None) -> float | None:
     if base is None or x is None:
         return None
     # Arguments reversed to match SQL standard.
     return log(x, base)
 
 
-def _sqlite_lpad(text, length, fill_text):
+def _sqlite_lpad(
+    text: str | None, length: int | None, fill_text: str | None
+) -> str | None:
     if text is None or length is None or fill_text is None:
         return None
     delta = length - len(text)
@@ -390,101 +424,103 @@ def _sqlite_lpad(text, length, fill_text):
     return (fill_text * length)[:delta] + text
 
 
-def _sqlite_md5(text):
+def _sqlite_md5(text: str | None) -> str | None:
     if text is None:
         return None
     return md5(text.encode()).hexdigest()
 
 
-def _sqlite_mod(x, y):
+def _sqlite_mod(x: float | None, y: float | None) -> float | None:
     if x is None or y is None:
         return None
     return fmod(x, y)
 
 
-def _sqlite_pi():
+def _sqlite_pi() -> float:
     return pi
 
 
-def _sqlite_power(x, y):
+def _sqlite_power(x: float | None, y: float | None) -> float | None:
     if x is None or y is None:
         return None
     return x**y
 
 
-def _sqlite_radians(x):
+def _sqlite_radians(x: float | None) -> float | None:
     if x is None:
         return None
     return radians(x)
 
 
-def _sqlite_repeat(text, count):
+def _sqlite_repeat(text: str | None, count: int | None) -> str | None:
     if text is None or count is None:
         return None
     return text * count
 
 
-def _sqlite_reverse(text):
+def _sqlite_reverse(text: str | None) -> str | None:
     if text is None:
         return None
     return text[::-1]
 
 
-def _sqlite_rpad(text, length, fill_text):
+def _sqlite_rpad(
+    text: str | None, length: int | None, fill_text: str | None
+) -> str | None:
     if text is None or length is None or fill_text is None:
         return None
     return (text + fill_text * length)[:length]
 
 
-def _sqlite_sha1(text):
+def _sqlite_sha1(text: str | None) -> str | None:
     if text is None:
         return None
     return sha1(text.encode()).hexdigest()
 
 
-def _sqlite_sha224(text):
+def _sqlite_sha224(text: str | None) -> str | None:
     if text is None:
         return None
     return sha224(text.encode()).hexdigest()
 
 
-def _sqlite_sha256(text):
+def _sqlite_sha256(text: str | None) -> str | None:
     if text is None:
         return None
     return sha256(text.encode()).hexdigest()
 
 
-def _sqlite_sha384(text):
+def _sqlite_sha384(text: str | None) -> str | None:
     if text is None:
         return None
     return sha384(text.encode()).hexdigest()
 
 
-def _sqlite_sha512(text):
+def _sqlite_sha512(text: str | None) -> str | None:
     if text is None:
         return None
     return sha512(text.encode()).hexdigest()
 
 
-def _sqlite_sign(x):
+def _sqlite_sign(x: float | None) -> int | None:
     if x is None:
         return None
     return (x > 0) - (x < 0)
 
 
-def _sqlite_sin(x):
+def _sqlite_sin(x: float | None) -> float | None:
     if x is None:
         return None
     return sin(x)
 
 
-def _sqlite_sqrt(x):
+def _sqlite_sqrt(x: float | None) -> float | None:
     if x is None:
         return None
     return sqrt(x)
 
 
-def _sqlite_tan(x):
+def _sqlite_tan(x: float | None) -> float | None:
     if x is None:
         return None
     return tan(x)