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

plain/models/backends/utils.py

@@ -1,52 +1,59 @@
+from __future__ import annotations
+
 import datetime
 import decimal
 import functools
 import logging
 import time
+from collections.abc import Generator, Iterator
 from contextlib import contextmanager
 from hashlib import md5
+from typing import TYPE_CHECKING, Any
 
 from plain.models.db import NotSupportedError
 from plain.models.otel import db_span
 from plain.utils.dateparse import parse_time
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+
 logger = logging.getLogger("plain.models.backends")
 
 
 class CursorWrapper:
-    def __init__(self, cursor, db):
+    def __init__(self, cursor: Any, db: Any) -> None:
         self.cursor = cursor
         self.db = db
 
     WRAP_ERROR_ATTRS = frozenset(["fetchone", "fetchmany", "fetchall", "nextset"])
 
-    def __getattr__(self, attr):
+    def __getattr__(self, attr: str) -> Any:
         cursor_attr = getattr(self.cursor, attr)
         if attr in CursorWrapper.WRAP_ERROR_ATTRS:
             return self.db.wrap_database_errors(cursor_attr)
         else:
             return cursor_attr
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Any]:
         with self.db.wrap_database_errors:
             yield from self.cursor
 
-    def __enter__(self):
+    def __enter__(self) -> CursorWrapper:
         return self
 
-    def __exit__(self, type, value, traceback):
+    def __exit__(self, type: Any, value: Any, traceback: Any) -> None:
         # Close instead of passing through to avoid backend-specific behavior
         # (#17671). Catch errors liberally because errors in cleanup code
         # aren't useful.
         try:
-            self.close()
+            self.close()  # type: ignore[attr-defined]
         except self.db.Database.Error:
             pass
 
     # The following methods cannot be implemented in __getattr__, because the
     # code must run when the method is invoked, not just when it is accessed.
 
-    def callproc(self, procname, params=None, kparams=None):
+    def callproc(self, procname: str, params: Any = None, kparams: Any = None) -> Any:
         # Keyword parameters for callproc aren't supported in PEP 249, but the
         # database driver may support them (e.g. cx_Oracle).
         if kparams is not None and not self.db.features.supports_callproc_kwargs:
@@ -64,23 +71,25 @@ class CursorWrapper:
                 params = params or ()
                 return self.cursor.callproc(procname, params, kparams)
 
-    def execute(self, sql, params=None):
+    def execute(self, sql: str, params: Any = None) -> Any:
         return self._execute_with_wrappers(
             sql, params, many=False, executor=self._execute
         )
 
-    def executemany(self, sql, param_list):
+    def executemany(self, sql: str, param_list: Any) -> Any:
         return self._execute_with_wrappers(
             sql, param_list, many=True, executor=self._executemany
         )
 
-    def _execute_with_wrappers(self, sql, params, many, executor):
-        context = {"connection": self.db, "cursor": self}
+    def _execute_with_wrappers(
+        self, sql: str, params: Any, many: bool, executor: Any
+    ) -> Any:
+        context: dict[str, Any] = {"connection": self.db, "cursor": self}
         for wrapper in reversed(self.db.execute_wrappers):
             executor = functools.partial(wrapper, executor)
         return executor(sql, params, many, context)
 
-    def _execute(self, sql, params, *ignored_wrapper_args):
+    def _execute(self, sql: str, params: Any, *ignored_wrapper_args: Any) -> Any:
         # Wrap in an OpenTelemetry span with standard attributes.
         with db_span(self.db, sql, params=params):
             self.db.validate_no_broken_transaction()
@@ -90,7 +99,9 @@ class CursorWrapper:
                 else:
                     return self.cursor.execute(sql, params)
 
-    def _executemany(self, sql, param_list, *ignored_wrapper_args):
+    def _executemany(
+        self, sql: str, param_list: Any, *ignored_wrapper_args: Any
+    ) -> Any:
         with db_span(self.db, sql, many=True, params=param_list):
             self.db.validate_no_broken_transaction()
             with self.db.wrap_database_errors:
@@ -100,18 +111,22 @@ class CursorWrapper:
 class CursorDebugWrapper(CursorWrapper):
     # XXX callproc isn't instrumented at this time.
 
-    def execute(self, sql, params=None):
+    def execute(self, sql: str, params: Any = None) -> Any:
         with self.debug_sql(sql, params, use_last_executed_query=True):
             return super().execute(sql, params)
 
-    def executemany(self, sql, param_list):
+    def executemany(self, sql: str, param_list: Any) -> Any:
         with self.debug_sql(sql, param_list, many=True):
             return super().executemany(sql, param_list)
 
     @contextmanager
     def debug_sql(
-        self, sql=None, params=None, use_last_executed_query=False, many=False
-    ):
+        self,
+        sql: str | None = None,
+        params: Any = None,
+        use_last_executed_query: bool = False,
+        many: bool = False,
+    ) -> Generator[None, None, None]:
         start = time.monotonic()
         try:
             yield
@@ -121,7 +136,7 @@ class CursorDebugWrapper(CursorWrapper):
             if use_last_executed_query:
                 sql = self.db.ops.last_executed_query(self.cursor, sql, params)
             try:
-                times = len(params) if many else ""
+                times = len(params) if many else ""  # type: ignore[arg-type]
             except TypeError:
                 # params could be an iterator.
                 times = "?"
@@ -145,7 +160,9 @@ class CursorDebugWrapper(CursorWrapper):
 
 
 @contextmanager
-def debug_transaction(connection, sql):
+def debug_transaction(
+    connection: BaseDatabaseWrapper, sql: str
+) -> Generator[None, None, None]:
     start = time.monotonic()
     try:
         yield
@@ -171,7 +188,7 @@ def debug_transaction(connection, sql):
             )
 
 
-def split_tzname_delta(tzname):
+def split_tzname_delta(tzname: str) -> tuple[str, str | None, str | None]:
     """
     Split a time zone name into a 3-tuple of (name, sign, offset).
     """
@@ -188,13 +205,15 @@ def split_tzname_delta(tzname):
 ###############################################
 
 
-def typecast_date(s):
+def typecast_date(s: str | None) -> datetime.date | None:
     return (
         datetime.date(*map(int, s.split("-"))) if s else None
     )  # return None if s is null
 
 
-def typecast_time(s):  # does NOT store time zone information
+def typecast_time(
+    s: str | None,
+) -> datetime.time | None:  # does NOT store time zone information
     if not s:
         return None
     hour, minutes, seconds = s.split(":")
@@ -207,7 +226,9 @@ def typecast_time(s):  # does NOT store time zone information
     )
 
 
-def typecast_timestamp(s):  # does NOT store time zone information
+def typecast_timestamp(
+    s: str | None,
+) -> datetime.date | datetime.datetime | None:  # does NOT store time zone information
     # "2005-07-29 15:48:00.590358-05"
     # "2005-07-29 09:56:00-05"
     if not s:
@@ -243,7 +264,7 @@ def typecast_timestamp(s):  # does NOT store time zone information
 ###############################################
 
 
-def split_identifier(identifier):
+def split_identifier(identifier: str) -> tuple[str, str]:
     """
     Split an SQL identifier into a two element tuple of (namespace, name).
 
@@ -257,7 +278,7 @@ def split_identifier(identifier):
     return namespace.strip('"'), name.strip('"')
 
 
-def truncate_name(identifier, length=None, hash_len=4):
+def truncate_name(identifier: str, length: int | None = None, hash_len: int = 4) -> str:
     """
     Shorten an SQL identifier to a repeatable mangled version with the given
     length.
@@ -278,7 +299,7 @@ def truncate_name(identifier, length=None, hash_len=4):
     )
 
 
-def names_digest(*args, length):
+def names_digest(*args: str, length: int) -> str:
     """
     Generate a 32-bit digest of a set of arguments that can be used to shorten
     identifying names.
@@ -289,7 +310,9 @@ def names_digest(*args, length):
     return h.hexdigest()[:length]
 
 
-def format_number(value, max_digits, decimal_places):
+def format_number(
+    value: decimal.Decimal | None, max_digits: int | None, decimal_places: int | None
+) -> str | None:
     """
     Format a number into a string with the requisite number of digits and
     decimal places.
@@ -304,12 +327,12 @@ def format_number(value, max_digits, decimal_places):
             decimal.Decimal(1).scaleb(-decimal_places), context=context
         )
     else:
-        context.traps[decimal.Rounded] = 1
+        context.traps[decimal.Rounded] = 1  # type: ignore[assignment]
         value = context.create_decimal(value)
     return f"{value:f}"
 
 
-def strip_quotes(table_name):
+def strip_quotes(table_name: str) -> str:
     """
     Strip quotes off of quoted table names to make them safe for use in index
     names, sequence names, etc. For example '"USER"."TABLE"' (an Oracle naming

plain/models/backups/cli.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import time
 from pathlib import Path
@@ -11,13 +13,13 @@ from .core import DatabaseBackups
 
 @register_cli("backups")
 @click.group("backups")
-def cli():
+def cli() -> None:
     """Local database backups"""
     pass
 
 
 @cli.command("list")
-def list_backups():
+def list_backups() -> None:
     backups_handler = DatabaseBackups()
     backups = backups_handler.find_backups()
     if not backups:
@@ -40,7 +42,7 @@ def list_backups():
 @cli.command("create")
 @click.option("--pg-dump", default="pg_dump", envvar="PG_DUMP")
 @click.argument("backup_name", default="")
-def create_backup(backup_name, pg_dump):
+def create_backup(backup_name: str, pg_dump: str) -> None:
     backups_handler = DatabaseBackups()
 
     if not backup_name:
@@ -62,7 +64,7 @@ def create_backup(backup_name, pg_dump):
 @click.option("--latest", is_flag=True)
 @click.option("--pg-restore", default="pg_restore", envvar="PG_RESTORE")
 @click.argument("backup_name", default="")
-def restore_backup(backup_name, latest, pg_restore):
+def restore_backup(backup_name: str, latest: bool, pg_restore: str) -> None:
     backups_handler = DatabaseBackups()
 
     if backup_name and latest:
@@ -89,7 +91,7 @@ def restore_backup(backup_name, latest, pg_restore):
 
 @cli.command("delete")
 @click.argument("backup_name")
-def delete_backup(backup_name):
+def delete_backup(backup_name: str) -> None:
     backups_handler = DatabaseBackups()
     try:
         backups_handler.delete(backup_name)
@@ -101,7 +103,7 @@ def delete_backup(backup_name):
 
 @cli.command("clear")
 @click.confirmation_option(prompt="Are you sure you want to delete all backups?")
-def clear_backups():
+def clear_backups() -> None:
     backups_handler = DatabaseBackups()
     backups = backups_handler.find_backups()
     for backup in backups:

plain/models/backups/clients.py

@@ -1,13 +1,20 @@
+from __future__ import annotations
+
 import gzip
 import os
 import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
 
 
 class PostgresBackupClient:
-    def __init__(self, connection):
+    def __init__(self, connection: BaseDatabaseWrapper) -> None:
         self.connection = connection
 
-    def get_env(self):
+    def get_env(self) -> dict[str, str]:
         settings_dict = self.connection.settings_dict
         options = settings_dict.get("OPTIONS", {})
         env = {}
@@ -27,7 +34,7 @@ class PostgresBackupClient:
             env["PGSSLKEY"] = str(options.get("sslkey"))
         return env
 
-    def create_backup(self, backup_path, *, pg_dump="pg_dump"):
+    def create_backup(self, backup_path: Path, *, pg_dump: str = "pg_dump") -> None:
         settings_dict = self.connection.settings_dict
 
         args = pg_dump.split()
@@ -64,7 +71,9 @@ class PostgresBackupClient:
             cmd, env={**os.environ, **self.get_env()}, check=True, shell=True
         )
 
-    def restore_backup(self, backup_path, *, pg_restore="pg_restore", psql="psql"):
+    def restore_backup(
+        self, backup_path: Path, *, pg_restore: str = "pg_restore", psql: str = "psql"
+    ) -> None:
         settings_dict = self.connection.settings_dict
 
         host = settings_dict.get("HOST")
@@ -118,17 +127,17 @@ class PostgresBackupClient:
 
 
 class SQLiteBackupClient:
-    def __init__(self, connection):
+    def __init__(self, connection: BaseDatabaseWrapper) -> None:
         self.connection = connection
 
-    def create_backup(self, backup_path):
+    def create_backup(self, backup_path: Path) -> None:
         self.connection.ensure_connection()
         src_conn = self.connection.connection
         dump = "\n".join(src_conn.iterdump())
         with gzip.open(backup_path, "wt") as f:
             f.write(dump)
 
-    def restore_backup(self, backup_path):
+    def restore_backup(self, backup_path: Path) -> None:
         with gzip.open(backup_path, "rt") as f:
             sql = f.read()
 

plain/models/backups/core.py

@@ -1,18 +1,29 @@
+from __future__ import annotations
+
 import datetime
 import os
+from collections.abc import Generator
 from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
 
 from plain.runtime import PLAIN_TEMP_PATH
 
-from .. import db_connection
+from .. import db_connection as _db_connection
 from .clients import PostgresBackupClient, SQLiteBackupClient
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+
+    db_connection = cast("BaseDatabaseWrapper", _db_connection)
+else:
+    db_connection = _db_connection
+
 
 class DatabaseBackups:
-    def __init__(self):
+    def __init__(self) -> None:
         self.path = PLAIN_TEMP_PATH / "backups"
 
-    def find_backups(self):
+    def find_backups(self) -> list[DatabaseBackup]:
         if not self.path.exists():
             return []
 
@@ -27,20 +38,20 @@ class DatabaseBackups:
 
         return backups
 
-    def create(self, name, **create_kwargs):
+    def create(self, name: str, **create_kwargs: Any) -> Path:
         backup = DatabaseBackup(name, backups_path=self.path)
         if backup.exists():
             raise Exception(f"Backup {name} already exists")
         backup_dir = backup.create(**create_kwargs)
         return backup_dir
 
-    def restore(self, name, **restore_kwargs):
+    def restore(self, name: str, **restore_kwargs: Any) -> None:
         backup = DatabaseBackup(name, backups_path=self.path)
         if not backup.exists():
             raise Exception(f"Backup {name} not found")
         backup.restore(**restore_kwargs)
 
-    def delete(self, name):
+    def delete(self, name: str) -> None:
         backup = DatabaseBackup(name, backups_path=self.path)
         if not backup.exists():
             raise Exception(f"Backup {name} not found")
@@ -48,17 +59,17 @@ class DatabaseBackups:
 
 
 class DatabaseBackup:
-    def __init__(self, name: str, *, backups_path: Path):
+    def __init__(self, name: str, *, backups_path: Path) -> None:
         self.name = name
         self.path = backups_path / name
 
         if not self.name:
             raise ValueError("Backup name is required")
 
-    def exists(self):
+    def exists(self) -> bool:
         return self.path.exists()
 
-    def create(self, **create_kwargs):
+    def create(self, **create_kwargs: Any) -> Path:
         self.path.mkdir(parents=True, exist_ok=True)
 
         backup_path = self.path / "default.backup"
@@ -75,7 +86,7 @@ class DatabaseBackup:
 
         return self.path
 
-    def iter_files(self):
+    def iter_files(self) -> Generator[Path, None, None]:
         for backup_file in self.path.iterdir():
             if not backup_file.is_file():
                 continue
@@ -83,7 +94,7 @@ class DatabaseBackup:
                 continue
             yield backup_file
 
-    def restore(self, **restore_kwargs):
+    def restore(self, **restore_kwargs: Any) -> None:
         for backup_file in self.iter_files():
             if db_connection.vendor == "postgresql":
                 PostgresBackupClient(db_connection).restore_backup(
@@ -95,12 +106,12 @@ class DatabaseBackup:
             else:
                 raise Exception("Unsupported database vendor")
 
-    def delete(self):
+    def delete(self) -> None:
         for backup_file in self.iter_files():
             backup_file.unlink()
 
         self.path.rmdir()
 
-    def updated_at(self):
+    def updated_at(self) -> datetime.datetime:
         mtime = os.path.getmtime(self.path)
         return datetime.datetime.fromtimestamp(mtime)