TypeDAL 3.12.1__py3-none-any.whl → 4.2.0__py3-none-any.whl

typedal/__about__.py

@@ -5,4 +5,4 @@ This file contains the Version info for this package.
 # SPDX-FileCopyrightText: 2023-present Robin van der Noord <robinvandernoord@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "3.12.1"
+__version__ = "4.2.0"

typedal/__init__.py

@@ -2,12 +2,30 @@
 TypeDAL Library.
 """
 
-from . import fields
-from .core import Relationship, TypeDAL, TypedField, TypedRows, TypedTable, relationship
+from .core import TypeDAL
+from .fields import TypedField
+from .helpers import sql_expression
+from .query_builder import QueryBuilder
+from .relationships import Relationship, relationship
+from .rows import PaginatedRows, TypedRows
+from .tables import TypedTable
+
+from . import fields  # isort: skip
 
 try:
     from .for_py4web import DAL as P4W_DAL
 except ImportError:  # pragma: no cover
     P4W_DAL = None  # type: ignore
 
-__all__ = ["TypeDAL", "TypedTable", "TypedField", "TypedRows", "fields", "Relationship", "relationship"]
+__all__ = [
+    "PaginatedRows",
+    "QueryBuilder",
+    "Relationship",
+    "TypeDAL",
+    "TypedField",
+    "TypedRows",
+    "TypedTable",
+    "fields",
+    "relationship",
+    "sql_expression",
+]

typedal/caching.py

@@ -3,27 +3,28 @@ Helpers to facilitate db-based caching.
 """
 
 import contextlib
+import datetime as dt
 import hashlib
 import json
-import typing
-from datetime import datetime, timedelta, timezone
-from typing import Any, Iterable, Mapping, Optional, TypeVar
+import typing as t
 
 import dill  # nosec
 from pydal.objects import Field, Rows, Set
 
-from .core import TypedField, TypedRows, TypedTable
+from .fields import TypedField
+from .rows import TypedRows
+from .tables import TypedTable
 from .types import Query
 
-if typing.TYPE_CHECKING:
+if t.TYPE_CHECKING:
     from .core import TypeDAL
 
 
-def get_now(tz: timezone = timezone.utc) -> datetime:
+def get_now(tz: dt.timezone = dt.timezone.utc) -> dt.datetime:
     """
     Get the default datetime, optionally in a specific timezone.
     """
-    return datetime.now(tz)
+    return dt.datetime.now(tz)
 
 
 class _TypedalCache(TypedTable):
@@ -33,8 +34,8 @@ class _TypedalCache(TypedTable):
 
     key: TypedField[str]
     data: TypedField[bytes]
-    cached_at = TypedField(datetime, default=get_now)
-    expires_at: TypedField[datetime | None]
+    cached_at = TypedField(dt.datetime, default=get_now)
+    expires_at: TypedField[dt.datetime | None]
 
 
 class _TypedalCacheDependency(TypedTable):
@@ -47,7 +48,7 @@ class _TypedalCacheDependency(TypedTable):
     idx: TypedField[int]
 
 
-def prepare(field: Any) -> str:
+def prepare(field: t.Any) -> str:
     """
     Prepare data to be used in a cache key.
 
@@ -56,10 +57,10 @@ def prepare(field: Any) -> str:
     """
     if isinstance(field, str):
         return field
-    elif isinstance(field, (dict, Mapping)):
+    elif isinstance(field, (dict, t.Mapping)):
         data = {str(k): prepare(v) for k, v in field.items()}
         return json.dumps(data, sort_keys=True)
-    elif isinstance(field, Iterable):
+    elif isinstance(field, t.Iterable):
         return ",".join(sorted([prepare(_) for _ in field]))
     elif isinstance(field, bool):
         return str(int(field))
@@ -67,7 +68,7 @@ def prepare(field: Any) -> str:
         return str(field)
 
 
-def create_cache_key(*fields: Any) -> str:
+def create_cache_key(*fields: t.Any) -> str:
     """
     Turn any fields of data into a string.
     """
@@ -83,7 +84,7 @@ def hash_cache_key(cache_key: str | bytes) -> str:
     return h.hexdigest()
 
 
-def create_and_hash_cache_key(*fields: Any) -> tuple[str, str]:
+def create_and_hash_cache_key(*fields: t.Any) -> tuple[str, str]:
     """
     Combine the input fields into one key and hash it with SHA 256.
     """
@@ -112,7 +113,7 @@ def _get_dependency_ids(rows: Rows, dependency_keys: list[tuple[Field, str]]) ->
     return dependencies
 
 
-def _determine_dependencies_auto(_: TypedRows[Any], rows: Rows) -> DependencyTupleSet:
+def _determine_dependencies_auto(_: TypedRows[t.Any], rows: Rows) -> DependencyTupleSet:
     dependency_keys = []
     for field in rows.fields:
         if str(field).endswith(".id"):
@@ -123,7 +124,7 @@ def _determine_dependencies_auto(_: TypedRows[Any], rows: Rows) -> DependencyTup
     return _get_dependency_ids(rows, dependency_keys)
 
 
-def _determine_dependencies(instance: TypedRows[Any], rows: Rows, depends_on: list[Any]) -> DependencyTupleSet:
+def _determine_dependencies(instance: TypedRows[t.Any], rows: Rows, depends_on: list[t.Any]) -> DependencyTupleSet:
     if not depends_on:
         return _determine_dependencies_auto(instance, rows)
 
@@ -144,11 +145,11 @@ def _determine_dependencies(instance: TypedRows[Any], rows: Rows, depends_on: li
     return _get_dependency_ids(rows, dependency_keys)
 
 
-def remove_cache(idx: int | Iterable[int], table: str) -> None:
+def remove_cache(idx: int | t.Iterable[int], table: str) -> None:
     """
     Remove any cache entries that are dependant on one or multiple indices of a table.
     """
-    if not isinstance(idx, Iterable):
+    if not isinstance(idx, t.Iterable):
         idx = [idx]
 
     related = (
@@ -184,12 +185,14 @@ def _remove_cache(s: Set, tablename: str) -> None:
     remove_cache(indeces, tablename)
 
 
-T_TypedTable = TypeVar("T_TypedTable", bound=TypedTable)
+T_TypedTable = t.TypeVar("T_TypedTable", bound=TypedTable)
 
 
 def get_expire(
-    expires_at: Optional[datetime] = None, ttl: Optional[int | timedelta] = None, now: Optional[datetime] = None
-) -> datetime | None:
+    expires_at: t.Optional[dt.datetime] = None,
+    ttl: t.Optional[int | dt.timedelta] = None,
+    now: t.Optional[dt.datetime] = None,
+) -> dt.datetime | None:
     """
     Based on an expires_at date or a ttl (in seconds or a time delta), determine the expire date.
     """
@@ -197,10 +200,10 @@ def get_expire(
 
     if expires_at and ttl:
         raise ValueError("Please only supply an `expired at` date or a `ttl` in seconds!")
-    elif isinstance(ttl, timedelta):
+    elif isinstance(ttl, dt.timedelta):
         return now + ttl
     elif ttl:
-        return now + timedelta(seconds=ttl)
+        return now + dt.timedelta(seconds=ttl)
     elif expires_at:
         return expires_at
 
@@ -210,8 +213,8 @@ def get_expire(
 def save_to_cache(
     instance: TypedRows[T_TypedTable],
     rows: Rows,
-    expires_at: Optional[datetime] = None,
-    ttl: Optional[int | timedelta] = None,
+    expires_at: t.Optional[dt.datetime] = None,
+    ttl: t.Optional[int | dt.timedelta] = None,
 ) -> TypedRows[T_TypedTable]:
     """
     Save a typedrows result to the database, and save dependencies from rows.
@@ -237,13 +240,13 @@ def save_to_cache(
     return instance
 
 
-def _load_from_cache(key: str, db: "TypeDAL") -> Any | None:
+def _load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
     if not (row := _TypedalCache.where(key=key).first()):
         return None
 
     now = get_now()
 
-    expires = row.expires_at.replace(tzinfo=timezone.utc) if row.expires_at else None
+    expires = row.expires_at.replace(tzinfo=dt.timezone.utc) if row.expires_at else None
 
     if expires and now >= expires:
         row.delete_record()
@@ -257,11 +260,11 @@ def _load_from_cache(key: str, db: "TypeDAL") -> Any | None:
 
     inst.db = db
     inst.model = db._class_map[inst.model]
-    inst.model._setup_instance_methods(inst.model)  # type: ignore
+    inst.model._setup_instance_methods(inst.model)
     return inst
 
 
-def load_from_cache(key: str, db: "TypeDAL") -> Any | None:
+def load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
     """
     If 'key' matches a non-expired row in the database, try to load the dill.
 
@@ -302,10 +305,10 @@ def _expired_and_valid_query() -> tuple[str, str]:
     return expired_items, valid_items
 
 
-T = typing.TypeVar("T")
-Stats = typing.TypedDict("Stats", {"total": T, "valid": T, "expired": T})
+T = t.TypeVar("T")
+Stats = t.TypedDict("Stats", {"total": T, "valid": T, "expired": T})
 
-RowStats = typing.TypedDict(
+RowStats = t.TypedDict(
     "RowStats",
     {
         "Dependent Cache Entries": int,
@@ -338,7 +341,7 @@ def row_stats(db: "TypeDAL", table: str, row_id: str) -> Stats[RowStats]:
     }
 
 
-TableStats = typing.TypedDict(
+TableStats = t.TypedDict(
     "TableStats",
     {
         "Dependent Cache Entries": int,
@@ -371,7 +374,7 @@ def table_stats(db: "TypeDAL", table: str) -> Stats[TableStats]:
     }
 
 
-GenericStats = typing.TypedDict(
+GenericStats = t.TypedDict(
     "GenericStats",
     {
         "entries": int,

typedal/cli.py

@@ -185,7 +185,7 @@ def setup(
             data.pop(prop, None)
             continue
 
-        if minimal and getattr(config, prop, None) not in (None, "") or is_optional(annotation):
+        if (minimal and getattr(config, prop, None) not in (None, "")) or is_optional(annotation):
             # property already present or not required, SKIP!
             data[prop] = getattr(config, prop, None)
             continue

typedal/config.py

@@ -4,11 +4,10 @@ TypeDAL can be configured by a combination of pyproject.toml (static), env (dyna
 
 import os
 import re
-import typing
+import typing as t
 import warnings
 from collections import defaultdict
 from pathlib import Path
-from typing import Any, Optional
 
 import tomli
 from configuraptor import TypedConfig, alias
@@ -17,10 +16,12 @@ from dotenv import dotenv_values, find_dotenv
 
 from .types import AnyDict
 
-if typing.TYPE_CHECKING:
+if t.TYPE_CHECKING:
     from edwh_migrate import Config as MigrateConfig
     from pydal2sql.typer_support import Config as P2SConfig
 
+LazyPolicy = t.Literal["forbid", "warn", "ignore", "tolerate", "allow"]
+
 
 class TypeDALConfig(TypedConfig):
     """
@@ -35,21 +36,22 @@ class TypeDALConfig(TypedConfig):
     pool_size: int = 0
     pyproject: str
     connection: str = "default"
+    lazy_policy: LazyPolicy = "tolerate"
 
     # pydal2sql:
     input: str = ""
     output: str = ""
     noop: bool = False
     magic: bool = True
-    tables: Optional[list[str]] = None
+    tables: t.Optional[list[str]] = None
     function: str = "define_tables"
 
     # edwh-migrate:
     # migrate uri = database
-    database_to_restore: Optional[str]
-    migrate_cat_command: Optional[str]
-    schema_version: Optional[str]
-    redis_host: Optional[str]
+    database_to_restore: t.Optional[str]
+    migrate_cat_command: t.Optional[str]
+    schema_version: t.Optional[str]
+    redis_host: t.Optional[str]
     migrate_table: str = "typedal_implemented_features"
     flag_location: str
     create_flag_location: bool = True
@@ -148,7 +150,7 @@ def _load_toml(path: str | bool | Path | None = True) -> tuple[str, AnyDict]:
         with open(toml_path, "rb") as f:
             data = tomli.load(f)
 
-        return str(toml_path) or "", typing.cast(AnyDict, data["tool"]["typedal"])
+        return str(toml_path) or "", t.cast(AnyDict, data["tool"]["typedal"])
     except Exception as e:
         warnings.warn(f"Could not load typedal config toml: {e}", source=e)
         return str(toml_path) or "", {}
@@ -194,7 +196,7 @@ def get_db_for_alias(db_name: str) -> str:
     return DB_ALIASES.get(db_name, db_name)
 
 
-DEFAULTS: dict[str, Any | typing.Callable[[AnyDict], Any]] = {
+DEFAULTS: dict[str, t.Any | t.Callable[[AnyDict], t.Any]] = {
     "database": lambda data: data.get("db_uri") or "sqlite:memory",
     "dialect": lambda data: (
         get_db_for_alias(data["database"].split(":")[0]) if ":" in data["database"] else data.get("db_type")
@@ -208,7 +210,7 @@ DEFAULTS: dict[str, Any | typing.Callable[[AnyDict], Any]] = {
 }
 
 
-def _fill_defaults(data: AnyDict, prop: str, fallback: Any = None) -> None:
+def _fill_defaults(data: AnyDict, prop: str, fallback: t.Any = None) -> None:
     default = DEFAULTS.get(prop, fallback)
     if callable(default):
         default = default(data)
@@ -223,7 +225,7 @@ def fill_defaults(data: AnyDict, prop: str) -> None:
         _fill_defaults(data, prop)
 
 
-TRANSFORMS: dict[str, typing.Callable[[AnyDict], Any]] = {
+TRANSFORMS: dict[str, t.Callable[[AnyDict], t.Any]] = {
     "database": lambda data: (
         data["database"]
         if (":" in data["database"] or not data.get("dialect"))
@@ -264,7 +266,7 @@ def expand_posix_vars(posix_expr: str, context: dict[str, str]) -> str:
     # Regular expression to match "${VAR:default}" pattern
     pattern = r"\$\{([^}]+)\}"
 
-    def replace_var(match: re.Match[Any]) -> str:
+    def replace_var(match: re.Match[t.Any]) -> str:
         var_with_default = match.group(1)
         var_name, default_value = var_with_default.split(":") if ":" in var_with_default else (var_with_default, "")
         return env.get(var_name.lower(), default_value)
@@ -325,10 +327,10 @@ def expand_env_vars_into_toml_values(toml: AnyDict, env: AnyDict) -> None:
 
 
 def load_config(
-    connection_name: Optional[str] = None,
+    connection_name: t.Optional[str] = None,
     _use_pyproject: bool | str | None = True,
     _use_env: bool | str | None = True,
-    **fallback: Any,
+    **fallback: t.Any,
 ) -> TypeDALConfig:
     """
     Combines multiple sources of config into one config instance.
@@ -338,7 +340,7 @@ def load_config(
     # combine and fill with fallback values
     # load typedal config or fail
     toml_path, toml = _load_toml(_use_pyproject)
-    dotenv_path, dotenv = _load_dotenv(_use_env)
+    _dotenv_path, dotenv = _load_dotenv(_use_env)
 
     expand_env_vars_into_toml_values(toml, dotenv)
 

typedal/constants.py

@@ -0,0 +1,25 @@
+"""
+Constants values.
+"""
+
+import datetime as dt
+import typing as t
+from decimal import Decimal
+
+from .types import T_annotation
+
+JOIN_OPTIONS = t.Literal["left", "inner", None]
+DEFAULT_JOIN_OPTION: JOIN_OPTIONS = "left"
+
+BASIC_MAPPINGS: dict[T_annotation, str] = {
+    str: "string",
+    int: "integer",
+    bool: "boolean",
+    bytes: "blob",
+    float: "double",
+    object: "json",
+    Decimal: "decimal(10,2)",
+    dt.date: "date",
+    dt.time: "time",
+    dt.datetime: "datetime",
+}