TypeDAL 3.17.3__py3-none-any.whl → 4.0.1__py3-none-any.whl

typedal/define.py

@@ -0,0 +1,188 @@
+"""
+Seperates the table definition code from core DAL code.
+
+Since otherwise helper methods would clutter up the TypeDAl class.
+"""
+
+from __future__ import annotations
+
+import copy
+import types
+import typing as t
+import warnings
+
+import pydal
+
+from .constants import BASIC_MAPPINGS
+from .core import TypeDAL, evaluate_forward_reference, resolve_annotation
+from .fields import TypedField, is_typed_field
+from .helpers import (
+    all_annotations,
+    all_dict,
+    filter_out,
+    instanciate,
+    is_union,
+    origin_is_subclass,
+    to_snake,
+)
+from .relationships import Relationship, to_relationship
+from .tables import TypedTable
+from .types import (
+    Field,
+    T,
+    T_annotation,
+    Table,
+    _Types,
+)
+
+try:
+    # python 3.14+
+    from annotationlib import ForwardRef
+except ImportError:  # pragma: no cover
+    # python 3.13-
+    from typing import ForwardRef
+
+
+class TableDefinitionBuilder:
+    """Handles the conversion of TypedTable classes to pydal tables."""
+
+    def __init__(self, db: "TypeDAL"):
+        """
+        Before, the `class_map` was a singleton on the pydal class; now it's per database.
+        """
+        self.db = db
+        self.class_map: dict[str, t.Type["TypedTable"]] = {}
+
+    def define(self, cls: t.Type[T], **kwargs: t.Any) -> t.Type[T]:
+        """Build and register a table from a TypedTable class."""
+        full_dict = all_dict(cls)
+        tablename = to_snake(cls.__name__)
+        annotations = all_annotations(cls)
+        annotations |= {k: t.cast(type, v) for k, v in full_dict.items() if is_typed_field(v)}
+        annotations = {k: v for k, v in annotations.items() if not k.startswith("_")}
+
+        typedfields: dict[str, TypedField[t.Any]] = {
+            k: instanciate(v, True) for k, v in annotations.items() if is_typed_field(v)
+        }
+
+        relationships: dict[str, type[Relationship[t.Any]]] = filter_out(annotations, Relationship)
+        fields = {fname: self.to_field(fname, ftype) for fname, ftype in annotations.items()}
+
+        other_kwargs = kwargs | {
+            k: v for k, v in cls.__dict__.items() if k not in annotations and not k.startswith("_")
+        }
+
+        for key, field in typedfields.items():
+            clone = copy.copy(field)
+            setattr(cls, key, clone)
+            typedfields[key] = clone
+
+        relationships = filter_out(full_dict, Relationship) | relationships | filter_out(other_kwargs, Relationship)
+
+        reference_field_keys = [
+            k for k, v in fields.items() if str(v.type).split(" ")[0] in ("list:reference", "reference")
+        ]
+
+        relationships |= {
+            k: new_relationship
+            for k in reference_field_keys
+            if k not in relationships and (new_relationship := to_relationship(cls, k, annotations[k]))
+        }
+
+        cache_dependency = self.db._config.caching and kwargs.pop("cache_dependency", True)
+        table: Table = self.db.define_table(tablename, *fields.values(), **kwargs)
+
+        for name, typed_field in typedfields.items():
+            field = fields[name]
+            typed_field.bind(field, table)
+
+        if issubclass(cls, TypedTable):
+            cls.__set_internals__(
+                db=self.db,
+                table=table,
+                relationships=t.cast(dict[str, Relationship[t.Any]], relationships),
+            )
+            self.class_map[str(table)] = cls
+            self.class_map[table._rname] = cls
+            cls.__on_define__(self.db)
+        else:
+            warnings.warn("db.define used without inheriting TypedTable. This could lead to strange problems!")
+
+        if not tablename.startswith("typedal_") and cache_dependency:
+            from .caching import _remove_cache
+
+            table._before_update.append(lambda s, _: _remove_cache(s, tablename))
+            table._before_delete.append(lambda s: _remove_cache(s, tablename))
+
+        return cls
+
+    def to_field(self, fname: str, ftype: type, **kw: t.Any) -> Field:
+        """Convert annotation to pydal Field."""
+        fname = to_snake(fname)
+        if converted_type := self.annotation_to_pydal_fieldtype(ftype, kw):
+            return self.build_field(fname, converted_type, **kw)
+        else:
+            raise NotImplementedError(f"Unsupported type {ftype}/{type(ftype)}")
+
+    def annotation_to_pydal_fieldtype(
+        self,
+        ftype_annotation: T_annotation,
+        mut_kw: t.MutableMapping[str, t.Any],
+    ) -> t.Optional[str]:
+        """Convert Python type annotation to pydal field type string."""
+        ftype = t.cast(type, ftype_annotation)  # cast from Type to type to make mypy happy)
+
+        if isinstance(ftype, str):
+            # extract type from string
+            ftype = resolve_annotation(ftype)
+
+        if isinstance(ftype, ForwardRef):
+            known_classes = {table.__name__: table for table in self.class_map.values()}
+
+            ftype = evaluate_forward_reference(ftype, namespace=known_classes)
+
+        if mapping := BASIC_MAPPINGS.get(ftype):
+            # basi types
+            return mapping
+        elif isinstance(ftype, pydal.objects.Table):
+            # db.table
+            return f"reference {ftype._tablename}"
+        elif issubclass(type(ftype), type) and issubclass(ftype, TypedTable):
+            # SomeTable
+            snakename = to_snake(ftype.__name__)
+            return f"reference {snakename}"
+        elif isinstance(ftype, TypedField):
+            # FieldType(type, ...)
+            return ftype._to_field(mut_kw, self)
+        elif origin_is_subclass(ftype, TypedField):
+            # TypedField[int]
+            return self.annotation_to_pydal_fieldtype(t.get_args(ftype)[0], mut_kw)
+        elif isinstance(ftype, types.GenericAlias) and t.get_origin(ftype) in (list, TypedField):  # type: ignore
+            # list[str] -> str -> string -> list:string
+            _child_type = t.get_args(ftype)[0]
+            _child_type = self.annotation_to_pydal_fieldtype(_child_type, mut_kw)
+            return f"list:{_child_type}"
+        elif is_union(ftype):
+            # str | int -> UnionType
+            # typing.Union[str | int] -> typing._UnionGenericAlias
+
+            # Optional[type] == type | None
+
+            match t.get_args(ftype):
+                case (_child_type, _Types.NONETYPE) | (_Types.NONETYPE, _child_type):
+                    # good union of Nullable
+
+                    # if a field is optional, it is nullable:
+                    mut_kw["notnull"] = False
+                    return self.annotation_to_pydal_fieldtype(_child_type, mut_kw)
+                case _:
+                    # two types is not supported by the db!
+                    return None
+        else:
+            return None
+
+    @classmethod
+    def build_field(cls, name: str, field_type: str, **kw: t.Any) -> Field:
+        """Create a pydal Field with default kwargs."""
+        kw_combined = TypeDAL.default_kwargs | kw
+        return Field(name, field_type, **kw_combined)

typedal/fields.py

@@ -2,27 +2,248 @@
 This file contains available Field types.
 """
 
+from __future__ import annotations
+
 import ast
+import contextlib
 import datetime as dt
 import decimal
-import typing
+import types
+import typing as t
 import uuid
 
+import pydal
 from pydal.helpers.classes import SQLCustomType
 from pydal.objects import Table
-from typing_extensions import Unpack
 
-from .core import TypeDAL, TypedField, TypedTable
-from .types import FieldSettings
+from .core import TypeDAL
+from .types import (
+    Expression,
+    Field,
+    FieldSettings,
+    Query,
+    T_annotation,
+    T_MetaInstance,
+    T_subclass,
+    T_Value,
+    Validator,
+)
 
-T = typing.TypeVar("T", bound=typing.Any)
+if t.TYPE_CHECKING:
+    # will be imported for real later:
+    from .tables import TypedTable
 
 
 ## general
 
 
+class TypedField(Expression, t.Generic[T_Value]):  # pragma: no cover
+    """
+    Typed version of pydal.Field, which will be converted to a normal Field in the background.
+    """
+
+    # will be set by .bind on db.define
+    name = ""
+    _db: t.Optional[pydal.DAL] = None
+    _rname: t.Optional[str] = None
+    _table: t.Optional[Table] = None
+    _field: t.Optional[Field] = None
+
+    _type: T_annotation
+    kwargs: t.Any
+
+    requires: Validator | t.Iterable[Validator]
+
+    # NOTE: for the logic of converting a TypedField into a pydal Field, see TypeDAL._to_field
+
+    def __init__(
+        self,
+        _type: t.Type[T_Value] | types.UnionType = str,  # type: ignore
+        /,
+        **settings: t.Unpack[FieldSettings],
+    ) -> None:
+        """
+        Typed version of pydal.Field, which will be converted to a normal Field in the background.
+
+        Provide the Python type for this field as the first positional argument
+        and any other settings to Field() as keyword parameters.
+        """
+        self._type = _type
+        self.kwargs = settings
+        # super().__init__()
+
+    @t.overload
+    def __get__(self, instance: T_MetaInstance, owner: t.Type[T_MetaInstance]) -> T_Value:  # pragma: no cover
+        """
+        row.field -> (actual data).
+        """
+
+    @t.overload
+    def __get__(self, instance: None, owner: "t.Type[TypedTable]") -> "TypedField[T_Value]":  # pragma: no cover
+        """
+        Table.field -> Field.
+        """
+
+    def __get__(
+        self,
+        instance: T_MetaInstance | None,
+        owner: t.Type[T_MetaInstance],
+    ) -> t.Union[T_Value, "TypedField[T_Value]"]:
+        """
+        Since this class is a Descriptor field, \
+            it returns something else depending on if it's called on a class or instance.
+
+        (this is mostly for mypy/typing)
+        """
+        if instance:
+            # this is only reached in a very specific case:
+            # an instance of the object was created with a specific set of fields selected (excluding the current one)
+            # in that case, no value was stored in the owner -> return None (since the field was not selected)
+            return t.cast(T_Value, None)  # cast as T_Value so mypy understands it for selected fields
+        else:
+            # getting as class -> return actual field so pydal understands it when using in query etc.
+            return t.cast(TypedField[T_Value], self._field)  # pretend it's still typed for IDE support
+
+    def __str__(self) -> str:
+        """
+        String representation of a Typed Field.
+
+        If `type` is set explicitly (e.g. TypedField(str, type="text")), that type is used: `TypedField.text`,
+        otherwise the type annotation is used (e.g. TypedField(str) -> TypedField.str)
+        """
+        return str(self._field) if self._field else ""
+
+    def __repr__(self) -> str:
+        """
+        More detailed string representation of a Typed Field.
+
+        Uses __str__ and adds the provided extra options (kwargs) in the representation.
+        """
+        string_value = self.__str__()
+
+        if "type" in self.kwargs:
+            # manual type in kwargs supplied
+            typename = self.kwargs["type"]
+        elif issubclass(type, type(self._type)):
+            # normal type, str.__name__ = 'str'
+            typename = getattr(self._type, "__name__", str(self._type))
+        elif t_args := t.get_args(self._type):
+            # list[str] -> 'str'
+            typename = t_args[0].__name__
+        else:  # pragma: no cover
+            # fallback - something else, may not even happen, I'm not sure
+            typename = self._type
+
+        string_value = f"TypedField[{typename}].{string_value}" if string_value else f"TypedField[{typename}]"
+
+        kw = self.kwargs.copy()
+        kw.pop("type", None)
+        return f"<{string_value} with options {kw}>"
+
+    def _to_field(self, extra_kwargs: t.MutableMapping[str, t.Any], builder: TableDefinitionBuilder) -> t.Optional[str]:
+        """
+        Convert a Typed Field instance to a pydal.Field.
+
+        Actual logic in TypeDAL._to_field but this function creates the pydal type name and updates the kwarg settings.
+        """
+        other_kwargs = self.kwargs.copy()
+        extra_kwargs.update(other_kwargs)  # <- modifies and overwrites the default kwargs with user-specified ones
+        return extra_kwargs.pop("type", False) or builder.annotation_to_pydal_fieldtype(
+            self._type,
+            extra_kwargs,
+        )
+
+    def bind(self, field: pydal.objects.Field, table: pydal.objects.Table) -> None:
+        """
+        Bind the right db/table/field info to this class, so queries can be made using `Class.field == ...`.
+        """
+        self._table = table
+        self._field = field
+
+    def __getattr__(self, key: str) -> t.Any:
+        """
+        If the regular getattribute does not work, try to get info from the related Field.
+        """
+        with contextlib.suppress(AttributeError):
+            return super().__getattribute__(key)
+
+        # try on actual field:
+        return getattr(self._field, key)
+
+    def __eq__(self, other: t.Any) -> Query:
+        """
+        Performing == on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field == other)
+
+    def __ne__(self, other: t.Any) -> Query:
+        """
+        Performing != on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field != other)
+
+    def __gt__(self, other: t.Any) -> Query:
+        """
+        Performing > on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field > other)
+
+    def __lt__(self, other: t.Any) -> Query:
+        """
+        Performing < on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field < other)
+
+    def __ge__(self, other: t.Any) -> Query:
+        """
+        Performing >= on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field >= other)
+
+    def __le__(self, other: t.Any) -> Query:
+        """
+        Performing <= on a Field will result in a Query.
+        """
+        return t.cast(Query, self._field <= other)
+
+    def __hash__(self) -> int:
+        """
+        Shadow Field.__hash__.
+        """
+        return hash(self._field)
+
+    def __invert__(self) -> Expression:
+        """
+        Performing ~ on a Field will result in an Expression.
+        """
+        if not self._field:  # pragma: no cover
+            raise ValueError("Unbound Field can not be inverted!")
+
+        return t.cast(Expression, ~self._field)
+
+    def lower(self) -> Expression:
+        """
+        For string-fields: compare lowercased values.
+        """
+        if not self._field:  # pragma: no cover
+            raise ValueError("Unbound Field can not be lowered!")
+
+        return t.cast(Expression, self._field.lower())
+
+
+def is_typed_field(cls: t.Any) -> t.TypeGuard["TypedField[t.Any]"]:
+    """
+    Is `cls` an instance or subclass of TypedField?
+
+    Deprecated
+    """
+    return isinstance(cls, TypedField) or (
+        isinstance(t.get_origin(cls), type) and issubclass(t.get_origin(cls), TypedField)
+    )
+
+
 ## specific
-def StringField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
+def StringField(**kw: t.Unpack[FieldSettings]) -> TypedField[str]:
     """
     Pydal type is string, Python type is str.
     """
@@ -33,7 +254,7 @@ def StringField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
 String = StringField
 
 
-def TextField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
+def TextField(**kw: t.Unpack[FieldSettings]) -> TypedField[str]:
     """
     Pydal type is text, Python type is str.
     """
@@ -44,7 +265,7 @@ def TextField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
 Text = TextField
 
 
-def BlobField(**kw: Unpack[FieldSettings]) -> TypedField[bytes]:
+def BlobField(**kw: t.Unpack[FieldSettings]) -> TypedField[bytes]:
     """
     Pydal type is blob, Python type is bytes.
     """
@@ -55,7 +276,7 @@ def BlobField(**kw: Unpack[FieldSettings]) -> TypedField[bytes]:
 Blob = BlobField
 
 
-def BooleanField(**kw: Unpack[FieldSettings]) -> TypedField[bool]:
+def BooleanField(**kw: t.Unpack[FieldSettings]) -> TypedField[bool]:
     """
     Pydal type is boolean, Python type is bool.
     """
@@ -66,7 +287,7 @@ def BooleanField(**kw: Unpack[FieldSettings]) -> TypedField[bool]:
 Boolean = BooleanField
 
 
-def IntegerField(**kw: Unpack[FieldSettings]) -> TypedField[int]:
+def IntegerField(**kw: t.Unpack[FieldSettings]) -> TypedField[int]:
     """
     Pydal type is integer, Python type is int.
     """
@@ -77,7 +298,7 @@ def IntegerField(**kw: Unpack[FieldSettings]) -> TypedField[int]:
 Integer = IntegerField
 
 
-def DoubleField(**kw: Unpack[FieldSettings]) -> TypedField[float]:
+def DoubleField(**kw: t.Unpack[FieldSettings]) -> TypedField[float]:
     """
     Pydal type is double, Python type is float.
     """
@@ -88,7 +309,7 @@ def DoubleField(**kw: Unpack[FieldSettings]) -> TypedField[float]:
 Double = DoubleField
 
 
-def DecimalField(n: int, m: int, **kw: Unpack[FieldSettings]) -> TypedField[decimal.Decimal]:
+def DecimalField(n: int, m: int, **kw: t.Unpack[FieldSettings]) -> TypedField[decimal.Decimal]:
     """
     Pydal type is decimal, Python type is Decimal.
     """
@@ -99,7 +320,7 @@ def DecimalField(n: int, m: int, **kw: Unpack[FieldSettings]) -> TypedField[deci
 Decimal = DecimalField
 
 
-def DateField(**kw: Unpack[FieldSettings]) -> TypedField[dt.date]:
+def DateField(**kw: t.Unpack[FieldSettings]) -> TypedField[dt.date]:
     """
     Pydal type is date, Python type is datetime.date.
     """
@@ -110,7 +331,7 @@ def DateField(**kw: Unpack[FieldSettings]) -> TypedField[dt.date]:
 Date = DateField
 
 
-def TimeField(**kw: Unpack[FieldSettings]) -> TypedField[dt.time]:
+def TimeField(**kw: t.Unpack[FieldSettings]) -> TypedField[dt.time]:
     """
     Pydal type is time, Python type is datetime.time.
     """
@@ -121,7 +342,7 @@ def TimeField(**kw: Unpack[FieldSettings]) -> TypedField[dt.time]:
 Time = TimeField
 
 
-def DatetimeField(**kw: Unpack[FieldSettings]) -> TypedField[dt.datetime]:
+def DatetimeField(**kw: t.Unpack[FieldSettings]) -> TypedField[dt.datetime]:
     """
     Pydal type is datetime, Python type is datetime.datetime.
     """
@@ -132,7 +353,7 @@ def DatetimeField(**kw: Unpack[FieldSettings]) -> TypedField[dt.datetime]:
 Datetime = DatetimeField
 
 
-def PasswordField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
+def PasswordField(**kw: t.Unpack[FieldSettings]) -> TypedField[str]:
     """
     Pydal type is password, Python type is str.
     """
@@ -143,7 +364,7 @@ def PasswordField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
 Password = PasswordField
 
 
-def UploadField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
+def UploadField(**kw: t.Unpack[FieldSettings]) -> TypedField[str]:
     """
     Pydal type is upload, Python type is str.
     """
@@ -153,11 +374,10 @@ def UploadField(**kw: Unpack[FieldSettings]) -> TypedField[str]:
 
 Upload = UploadField
 
-T_subclass = typing.TypeVar("T_subclass", TypedTable, Table)
-
 
 def ReferenceField(
-    other_table: str | typing.Type[TypedTable] | TypedTable | Table | T_subclass, **kw: Unpack[FieldSettings]
+    other_table: str | t.Type[TypedTable] | TypedTable | Table | T_subclass,
+    **kw: t.Unpack[FieldSettings],
 ) -> TypedField[int]:
     """
     Pydal type is reference, Python type is int (id).
@@ -180,7 +400,7 @@ def ReferenceField(
 Reference = ReferenceField
 
 
-def ListStringField(**kw: Unpack[FieldSettings]) -> TypedField[list[str]]:
+def ListStringField(**kw: t.Unpack[FieldSettings]) -> TypedField[list[str]]:
     """
     Pydal type is list:string, Python type is list of str.
     """
@@ -191,7 +411,7 @@ def ListStringField(**kw: Unpack[FieldSettings]) -> TypedField[list[str]]:
 ListString = ListStringField
 
 
-def ListIntegerField(**kw: Unpack[FieldSettings]) -> TypedField[list[int]]:
+def ListIntegerField(**kw: t.Unpack[FieldSettings]) -> TypedField[list[int]]:
     """
     Pydal type is list:integer, Python type is list of int.
     """
@@ -202,7 +422,7 @@ def ListIntegerField(**kw: Unpack[FieldSettings]) -> TypedField[list[int]]:
 ListInteger = ListIntegerField
 
 
-def ListReferenceField(other_table: str, **kw: Unpack[FieldSettings]) -> TypedField[list[int]]:
+def ListReferenceField(other_table: str, **kw: t.Unpack[FieldSettings]) -> TypedField[list[int]]:
     """
     Pydal type is list:reference, Python type is list of int (id).
     """
@@ -213,7 +433,7 @@ def ListReferenceField(other_table: str, **kw: Unpack[FieldSettings]) -> TypedFi
 ListReference = ListReferenceField
 
 
-def JSONField(**kw: Unpack[FieldSettings]) -> TypedField[object]:
+def JSONField(**kw: t.Unpack[FieldSettings]) -> TypedField[object]:
     """
     Pydal type is json, Python type is object (can be anything JSON-encodable).
     """
@@ -221,7 +441,7 @@ def JSONField(**kw: Unpack[FieldSettings]) -> TypedField[object]:
     return TypedField(object, **kw)
 
 
-def BigintField(**kw: Unpack[FieldSettings]) -> TypedField[int]:
+def BigintField(**kw: t.Unpack[FieldSettings]) -> TypedField[int]:
     """
     Pydal type is bigint, Python type is int.
     """
@@ -241,7 +461,7 @@ NativeTimestampField = SQLCustomType(
 )
 
 
-def TimestampField(**kw: Unpack[FieldSettings]) -> TypedField[dt.datetime]:
+def TimestampField(**kw: t.Unpack[FieldSettings]) -> TypedField[dt.datetime]:
     """
     Database type is timestamp, Python type is datetime.
 
@@ -275,7 +495,7 @@ def safe_decode_native_point(value: str | None) -> tuple[float, ...]:
 
     try:
         parsed = ast.literal_eval(value)
-        return typing.cast(tuple[float, ...], parsed)
+        return t.cast(tuple[float, ...], parsed)
     except ValueError:  # pragma: no cover
         # should not happen when inserted with `safe_encode_native_point` but you never know
         return ()
@@ -328,7 +548,7 @@ NativePointField = SQLCustomType(
 )
 
 
-def PointField(**kw: Unpack[FieldSettings]) -> TypedField[tuple[float, float]]:
+def PointField(**kw: t.Unpack[FieldSettings]) -> TypedField[tuple[float, float]]:
     """
     Database type is point, Python type is tuple[float, float].
     """
@@ -344,9 +564,14 @@ NativeUUIDField = SQLCustomType(
 )
 
 
-def UUIDField(**kw: Unpack[FieldSettings]) -> TypedField[uuid.UUID]:
+def UUIDField(**kw: t.Unpack[FieldSettings]) -> TypedField[uuid.UUID]:
     """
     Database type is uuid, Python type is UUID.
     """
     kw["type"] = NativeUUIDField
     return TypedField(uuid.UUID, **kw)
+
+
+# note: import at the end to prevent circular imports:
+from .define import TableDefinitionBuilder  # noqa: E402
+from .tables import TypedTable  # noqa: E402

typedal/for_web2py.py

@@ -6,7 +6,7 @@ import datetime as dt
 
 from pydal.validators import IS_NOT_IN_DB
 
-from .core import TypeDAL, TypedField, TypedTable
+from . import TypeDAL, TypedField, TypedTable
 from .fields import TextField
 from .web2py_py4web_shared import AuthUser