TypeDAL 3.17.2__py3-none-any.whl → 4.0.0__py3-none-any.whl

typedal/helpers.py

@@ -7,19 +7,25 @@ from __future__ import annotations
 import datetime as dt
 import fnmatch
 import io
+import re
+import sys
 import types
-import typing
+import typing as t
 from collections import ChainMap
-from typing import Any
 
 from pydal import DAL
 
-from .types import AnyDict, Expression, Field, Table
+from .types import AnyDict, Expression, Field, Row, T, Table, Template  # type: ignore
 
-if typing.TYPE_CHECKING:
-    from . import TypeDAL, TypedField, TypedTable
+try:
+    import annotationlib
+except ImportError:  # pragma: no cover
+    annotationlib = None
+
+if t.TYPE_CHECKING:
+    from string.templatelib import Interpolation
 
-T = typing.TypeVar("T")
+    from . import TypeDAL, TypedField, TypedTable
 
 
 def is_union(some_type: type | types.UnionType) -> bool:
@@ -27,19 +33,34 @@ def is_union(some_type: type | types.UnionType) -> bool:
     Check if a type is some type of Union.
 
     Args:
-        some_type: types.UnionType = type(int | str); typing.Union = typing.Union[int, str]
+        some_type: types.UnionType = type(int | str); t.Union = t.Union[int, str]
 
     """
-    return typing.get_origin(some_type) in (types.UnionType, typing.Union)
+    return t.get_origin(some_type) in (types.UnionType, t.Union)
 
 
-def reversed_mro(cls: type) -> typing.Iterable[type]:
+def reversed_mro(cls: type) -> t.Iterable[type]:
     """
     Get the Method Resolution Order (mro) for a class, in reverse order to be used with ChainMap.
     """
     return reversed(getattr(cls, "__mro__", []))
 
 
+def _cls_annotations(c: type) -> dict[str, type]:  # pragma: no cover
+    """
+    Functions to get the annotations of a class (excl inherited, use _all_annotations for that).
+
+    Uses `annotationlib` if available (since 3.14) and if so, resolves forward references immediately.
+    """
+    if annotationlib:
+        return t.cast(
+            dict[str, type],
+            annotationlib.get_annotations(c, format=annotationlib.Format.VALUE, eval_str=True),
+        )
+    else:
+        return getattr(c, "__annotations__", {})
+
+
 def _all_annotations(cls: type) -> ChainMap[str, type]:
     """
     Returns a dictionary-like ChainMap that includes annotations for all \
@@ -47,7 +68,7 @@ def _all_annotations(cls: type) -> ChainMap[str, type]:
     """
     # chainmap reverses the iterable, so reverse again beforehand to keep order normally:
 
-    return ChainMap(*(c.__annotations__ for c in reversed_mro(cls) if "__annotations__" in c.__dict__))
+    return ChainMap(*(_cls_annotations(c) for c in reversed_mro(cls)))
 
 
 def all_dict(cls: type) -> AnyDict:
@@ -57,9 +78,9 @@ def all_dict(cls: type) -> AnyDict:
     return dict(ChainMap(*(c.__dict__ for c in reversed_mro(cls))))  # type: ignore
 
 
-def all_annotations(cls: type, _except: typing.Optional[typing.Iterable[str]] = None) -> dict[str, type]:
+def all_annotations(cls: type, _except: t.Optional[t.Iterable[str]] = None) -> dict[str, type]:
     """
-    Wrapper around `_all_annotations` that filters away any keys in _except.
+    Wrapper around `_all_annotations` that filters away t.Any keys in _except.
 
     It also flattens the ChainMap to a regular dict.
     """
@@ -70,7 +91,7 @@ def all_annotations(cls: type, _except: typing.Optional[typing.Iterable[str]] =
     return {k: v for k, v in _all.items() if k not in _except}
 
 
-def instanciate(cls: typing.Type[T] | T, with_args: bool = False) -> T:
+def instanciate(cls: t.Type[T] | T, with_args: bool = False) -> T:
     """
     Create an instance of T (if it is a class).
 
@@ -80,20 +101,20 @@ def instanciate(cls: typing.Type[T] | T, with_args: bool = False) -> T:
     If with_args: spread the generic args into the class creation
     (needed for e.g. TypedField(str), but not for list[str])
     """
-    if inner_cls := typing.get_origin(cls):
+    if inner_cls := t.get_origin(cls):
         if not with_args:
-            return typing.cast(T, inner_cls())
+            return t.cast(T, inner_cls())
 
-        args = typing.get_args(cls)
-        return typing.cast(T, inner_cls(*args))
+        args = t.get_args(cls)
+        return t.cast(T, inner_cls(*args))
 
     if isinstance(cls, type):
-        return typing.cast(T, cls())
+        return t.cast(T, cls())
 
     return cls
 
 
-def origin_is_subclass(obj: Any, _type: type) -> bool:
+def origin_is_subclass(obj: t.Any, _type: type) -> bool:
     """
     Check if the origin of a generic is a subclass of _type.
 
@@ -101,15 +122,13 @@ def origin_is_subclass(obj: Any, _type: type) -> bool:
         origin_is_subclass(list[str], list) -> True
     """
     return bool(
-        typing.get_origin(obj)
-        and isinstance(typing.get_origin(obj), type)
-        and issubclass(typing.get_origin(obj), _type),
+        t.get_origin(obj) and isinstance(t.get_origin(obj), type) and issubclass(t.get_origin(obj), _type),
     )
 
 
 def mktable(
-    data: dict[Any, Any],
-    header: typing.Optional[typing.Iterable[str] | range] = None,
+    data: dict[t.Any, t.Any],
+    header: t.Optional[t.Iterable[str] | range] = None,
     skip_first: bool = True,
 ) -> str:
     """
@@ -154,11 +173,11 @@ def mktable(
     return output.getvalue()
 
 
-K = typing.TypeVar("K")
-V = typing.TypeVar("V")
+K = t.TypeVar("K")
+V = t.TypeVar("V")
 
 
-def looks_like(v: Any, _type: type[Any]) -> bool:
+def looks_like(v: t.Any, _type: type[t.Any]) -> bool:
     """
     Returns true if v or v's class is of type _type, including if it is a generic.
 
@@ -186,19 +205,19 @@ def unwrap_type(_type: type) -> type:
     Example:
         list[list[str]] -> str
     """
-    while args := typing.get_args(_type):
+    while args := t.get_args(_type):
         _type = args[0]
     return _type
 
 
-@typing.overload
+@t.overload
 def extract_type_optional(annotation: T) -> tuple[T, bool]:
     """
     T -> T is not exactly right because you'll get the inner type, but mypy seems happy with this.
     """
 
 
-@typing.overload
+@t.overload
 def extract_type_optional(annotation: None) -> tuple[None, bool]:
     """
     None leads to None, False.
@@ -212,10 +231,10 @@ def extract_type_optional(annotation: T | None) -> tuple[T | None, bool]:
     if annotation is None:
         return None, False
 
-    if origin := typing.get_origin(annotation):
-        args = typing.get_args(annotation)
+    if origin := t.get_origin(annotation):
+        args = t.get_args(annotation)
 
-        if origin in (typing.Union, types.UnionType, typing.Optional) and args:
+        if origin in (t.Union, types.UnionType, t.Optional) and args:
             # remove None:
             return next(_ for _ in args if _ and _ != types.NoneType and not isinstance(_, types.NoneType)), True
 
@@ -256,7 +275,7 @@ class DummyQuery:
         return False
 
 
-def as_lambda(value: T) -> typing.Callable[..., T]:
+def as_lambda(value: T) -> t.Callable[..., T]:
     """
     Wrap value in a callable.
     """
@@ -289,21 +308,21 @@ def get_db(table: "TypedTable | Table") -> "DAL":
     """
     Get the underlying DAL instance for a pydal or typedal table.
     """
-    return typing.cast("DAL", table._db)
+    return t.cast("DAL", table._db)
 
 
 def get_table(table: "TypedTable | Table") -> "Table":
     """
     Get the underlying pydal table for a typedal table.
     """
-    return typing.cast("Table", table._table)
+    return t.cast("Table", table._table)
 
 
-def get_field(field: "TypedField[typing.Any] | Field") -> "Field":
+def get_field(field: "TypedField[t.Any] | Field") -> "Field":
     """
     Get the underlying pydal field from a typedal field.
     """
-    return typing.cast(
+    return t.cast(
         "Field",
         field,  # Table.field already is a Field, but cast to make sure the editor knows this too.
     )
@@ -314,7 +333,7 @@ class classproperty:
     Combination of @classmethod and @property.
     """
 
-    def __init__(self, fget: typing.Callable[..., typing.Any]) -> None:
+    def __init__(self, fget: t.Callable[..., t.Any]) -> None:
         """
         Initialize the classproperty.
 
@@ -323,7 +342,7 @@ class classproperty:
         """
         self.fget = fget
 
-    def __get__(self, obj: typing.Any, owner: typing.Type[T]) -> typing.Any:
+    def __get__(self, obj: t.Any, owner: t.Type[T]) -> t.Any:
         """
         Retrieve the property value.
 
@@ -337,7 +356,7 @@ class classproperty:
         return self.fget(owner)
 
 
-def smarter_adapt(db: TypeDAL, placeholder: Any) -> str:
+def smarter_adapt(db: TypeDAL, placeholder: t.Any) -> str:
     """
     Smarter adaptation of placeholder to quote if needed.
 
@@ -349,7 +368,7 @@ def smarter_adapt(db: TypeDAL, placeholder: Any) -> str:
         Quoted placeholder if needed, except for numbers (smart_adapt logic)
             or fields/tables (use already quoted rname).
     """
-    return typing.cast(
+    return t.cast(
         str,
         getattr(placeholder, "sql_shortref", None)  # for tables
         or getattr(placeholder, "sqlsafe", None)  # for fields
@@ -357,26 +376,123 @@ def smarter_adapt(db: TypeDAL, placeholder: Any) -> str:
     )
 
 
-def sql_escape(db: TypeDAL, sql_fragment: str, *raw_args: Any, **raw_kwargs: Any) -> str:
+# https://docs.python.org/3.14/library/string.templatelib.html
+SYSTEM_SUPPORTS_TEMPLATES = sys.version_info > (3, 14)
+
+
+def process_tstring(template: Template, operation: t.Callable[["Interpolation"], str]) -> str:  # pragma: no cover
     """
-    Generates escaped SQL fragments with placeholders.
+    Process a Template string by applying an operation to each interpolation.
+
+    This function iterates through a Template object, which contains both string literals
+    and Interpolation objects. String literals are preserved as-is, while Interpolation
+    objects are transformed using the provided operation function.
 
     Args:
-        db: Database object.
-        sql_fragment: SQL fragment with placeholders.
-        *raw_args: Positional arguments to be escaped.
-        **raw_kwargs: Keyword arguments to be escaped.
+        template: A Template object containing mixed string literals and Interpolation objects.
+        operation: A callable that takes an Interpolation object and returns a string.
+                  This function will be applied to each interpolated value in the template.
+
+    Returns:
+        str: The processed string with all interpolations replaced by the results of
+             applying the operation function.
+
+    Example:
+        Basic f-string functionality can be implemented as:
+
+        >>> def fstring_operation(interpolation):
+        ...     return str(interpolation.value)
+        >>> value = "test"
+        >>> template = t"{value = }"  # Template string literal
+        >>> result = process_tstring(template, fstring_operation)
+        >>> print(result)  # "value = test"
+
+    Note:
+        This is a generic template processor. The specific behavior depends entirely
+        on the operation function provided.
+    """
+    return "".join(part if isinstance(part, str) else operation(part) for part in template)
+
+
+def sql_escape_template(db: TypeDAL, sql_fragment: Template) -> str:  # pragma: no cover
+    r"""
+    Safely escape a Template string for SQL execution using database-specific escaping.
+
+    This function processes a Template string (t-string) by escaping all interpolated
+    values using the database adapter's escape mechanism, preventing SQL injection
+    attacks while maintaining the structure of the SQL query.
+
+    Args:
+        db: TypeDAL database connection object that provides the adapter for escaping.
+        sql_fragment: A Template object (t-string) containing SQL with interpolated values.
+                     The interpolated values will be automatically escaped.
+
+    Returns:
+        str: SQL string with all interpolated values properly escaped for safe execution.
+
+    Example:
+        >>> user_input = "'; DROP TABLE users; --"
+        >>> query = t"SELECT * FROM users WHERE name = {user_input}"
+        >>> safe_query = sql_escape_template(db, query)
+        >>> print(safe_query)  # "SELECT * FROM users WHERE name = '\'; DROP TABLE users; --'"
+
+    Security:
+        This function is essential for preventing SQL injection attacks when using
+        user-provided data in SQL queries. All interpolated values are escaped
+        according to the database adapter's rules.
+
+    Note:
+        Only available in Python 3.14+ when SYSTEM_SUPPORTS_TEMPLATES is True.
+        For earlier Python versions, use sql_escape() with string formatting.
+    """
+    return process_tstring(sql_fragment, lambda part: smarter_adapt(db, part.value))
+
+
+def sql_escape(db: TypeDAL, sql_fragment: str | Template, *raw_args: t.Any, **raw_kwargs: t.Any) -> str:
+    """
+    Generate escaped SQL fragments with safely substituted placeholders.
+
+    This function provides secure SQL string construction by escaping all provided
+    arguments using the database adapter's escaping mechanism. It supports both
+    traditional string formatting (Python < 3.14) and Template strings (Python 3.14+).
+
+    Args:
+        db: TypeDAL database connection object that provides the adapter for escaping.
+        sql_fragment: SQL fragment with placeholders (%s for positional, %(name)s for named).
+                     In Python 3.14+, this can also be a Template (t-string) with
+                     interpolated values that will be automatically escaped.
+        *raw_args: Positional arguments to be escaped and substituted for %s placeholders.
+                  Only use with string fragments, not Template objects.
+        **raw_kwargs: Keyword arguments to be escaped and substituted for %(name)s placeholders.
+                     Only use with string fragments, not Template objects.
 
     Returns:
-        Escaped SQL fragment with placeholders replaced with escaped values.
+        str: SQL fragment with all placeholders replaced by properly escaped values.
 
     Raises:
-        ValueError: If both args and kwargs are provided.
+        ValueError: If both positional and keyword arguments are provided simultaneously.
+
+    Examples:
+        Positional arguments:
+        >>> safe_sql = sql_escape(db, "SELECT * FROM users WHERE id = %s", user_id)
+
+        Keyword arguments:
+        >>> safe_sql = sql_escape(db, "SELECT * FROM users WHERE name = %(name)s", name=username)
+
+        Template strings (Python 3.14+):
+        >>> safe_sql = sql_escape(db, t"SELECT * FROM users WHERE id = {user_id}")
+
+    Security:
+        All arguments are escaped using the database adapter's escaping rules to prevent
+        SQL injection attacks. Never concatenate user input directly into SQL strings.
     """
     if raw_args and raw_kwargs:  # pragma: no cover
         raise ValueError("Please provide either args or kwargs, not both.")
 
-    elif raw_args:
+    if SYSTEM_SUPPORTS_TEMPLATES and isinstance(sql_fragment, Template):  # pragma: no cover
+        return sql_escape_template(db, sql_fragment)
+
+    if raw_args:
         # list
         return sql_fragment % tuple(smarter_adapt(db, placeholder) for placeholder in raw_args)
     else:
@@ -386,23 +502,58 @@ def sql_escape(db: TypeDAL, sql_fragment: str, *raw_args: Any, **raw_kwargs: Any
 
 def sql_expression(
     db: TypeDAL,
-    sql_fragment: str,
-    *raw_args: Any,
+    sql_fragment: str | Template,
+    *raw_args: t.Any,
     output_type: str | None = None,
-    **raw_kwargs: Any,
+    **raw_kwargs: t.Any,
 ) -> Expression:
     """
-    Creates a pydal Expression object representing a raw SQL fragment.
+    Create a PyDAL Expression object from a raw SQL fragment with safe parameter substitution.
+
+    This function combines SQL escaping with PyDAL's Expression system, allowing you to
+    create database expressions from raw SQL while maintaining security through proper
+    parameter escaping.
 
     Args:
-        db: The TypeDAL object.
-        sql_fragment: The raw SQL fragment.
-        *raw_args: Arguments to be interpolated into the SQL fragment.
-        output_type: The expected output type of the expression.
-        **raw_kwargs: Keyword arguments to be interpolated into the SQL fragment.
+        db: The TypeDAL database connection object.
+        sql_fragment: Raw SQL fragment with placeholders (%s for positional, %(name)s for named).
+                     In Python 3.14+, this can also be a Template (t-string) with
+                     interpolated values that will be automatically escaped.
+        *raw_args: Positional arguments to be escaped and interpolated into the SQL fragment.
+                  Only use with string fragments, not Template objects.
+        output_type: Optional type hint for the expected output type of the expression.
+                    This can help with query analysis and optimization.
+        **raw_kwargs: Keyword arguments to be escaped and interpolated into the SQL fragment.
+                     Only use with string fragments, not Template objects.
 
     Returns:
-        A pydal Expression object.
+        Expression: A PyDAL Expression object wrapping the safely escaped SQL fragment.
+
+    Examples:
+        Creating a complex WHERE clause:
+        >>> expr = sql_expression(db,
+        ...     "age > %s AND status = %s",
+        ...     18, "active",
+        ...     output_type="boolean")
+        >>> query = db(expr).select()
+
+        Using keyword arguments:
+        >>> expr = sql_expression(db,
+        ...     "EXTRACT(year FROM %(date_col)s) = %(year)s",
+        ...     date_col="created_at", year=2023,
+        ...     output_type="boolean")
+
+        Template strings (Python 3.14+):
+        >>> min_age = 21
+        >>> expr = sql_expression(db, t"age >= {min_age}", output_type="boolean")
+
+    Security:
+        All parameters are escaped using sql_escape() before being wrapped in the Expression,
+        ensuring protection against SQL injection attacks.
+
+    Note:
+        The returned Expression can be used anywhere PyDAL expects an expression,
+        such as in db().select(), .update(), or .delete() operations.
     """
     safe_sql = sql_escape(db, sql_fragment, *raw_args, **raw_kwargs)
 
@@ -413,3 +564,59 @@ def sql_expression(
         safe_sql,
         type=output_type,  # optional type hint
     )
+
+
+def normalize_table_keys(row: Row, pattern: re.Pattern[str] = re.compile(r"^([a-zA-Z_]+)_(\d{5,})$")) -> Row:
+    """
+    Normalize table keys in a PyDAL Row object by stripping numeric hash suffixes from table names, \
+    only if the suffix is 5 or more digits.
+
+    For example:
+        Row({'articles_12345': {...}}) -> Row({'articles': {...}})
+        Row({'articles_123': {...}})   -> unchanged
+
+    Returns:
+        Row: A new Row object with normalized keys.
+    """
+    new_data: dict[str, t.Any] = {}
+    for key, value in row.items():
+        if match := pattern.match(key):
+            base, _suffix = match.groups()
+            normalized_key = base
+            new_data[normalized_key] = value
+        else:
+            new_data[key] = value
+    return Row(new_data)
+
+
+def default_representer(field: TypedField[T], value: T, table: t.Type[TypedTable]) -> str:
+    """
+    Simply call field.represent on the value.
+    """
+    if represent := getattr(field, "represent", None):
+        return str(represent(value, table))
+    else:
+        return repr(value)
+
+
+def throw(exc: BaseException) -> t.Never:
+    """
+    Raise the given exception.
+
+    This function provides a functional way to raise exceptions, allowing
+    exception raising to be used in expressions where a statement wouldn't work.
+
+    Args:
+        exc: The exception to be raised.
+
+    Returns:
+        Never returns normally as an exception is always raised.
+
+    Raises:
+        BaseException: Always raises the provided exception.
+
+    Examples:
+        >>> value = get_value() or throw(ValueError("No value available"))
+        >>> result = data.get('key') if data else throw(KeyError("Missing data"))
+    """
+    raise exc

typedal/mixins.py

@@ -5,26 +5,22 @@ Mixins can add reusable fields and behavior (optimally both, otherwise it doesn'
 """
 
 import base64
+import datetime as dt
 import os
-import typing
+import typing as t
 import warnings
-from datetime import datetime
-from typing import Any, Optional
 
 from pydal import DAL
 from pydal.validators import IS_NOT_IN_DB, ValidationError
 from slugify import slugify
 
-from .core import (  # noqa F401 - used by example in docstring
-    QueryBuilder,
-    T_MetaInstance,
-    TableMeta,
-    TypeDAL,
-    TypedTable,
-    _TypedTable,
-)
+from .core import TypeDAL
 from .fields import DatetimeField, StringField
-from .types import OpRow, Set
+from .tables import _TypedTable
+from .types import OpRow, Set, T_MetaInstance
+
+if t.TYPE_CHECKING:
+    from .tables import TypedTable  # noqa: F401
 
 
 class Mixin(_TypedTable):
@@ -38,9 +34,9 @@ class Mixin(_TypedTable):
         ('inconsistent method resolution' or 'metaclass conflicts')
     """
 
-    __settings__: typing.ClassVar[dict[str, Any]]
+    __settings__: t.ClassVar[dict[str, t.Any]]
 
-    def __init_subclass__(cls, **kwargs: Any):
+    def __init_subclass__(cls, **kwargs: t.Any):
         """
         Ensures __settings__ exists for other mixins.
         """
@@ -52,8 +48,8 @@ class TimestampsMixin(Mixin):
     A Mixin class for adding timestamp fields to a model.
     """
 
-    created_at = DatetimeField(default=datetime.now, writable=False)
-    updated_at = DatetimeField(default=datetime.now, writable=False)
+    created_at = DatetimeField(default=dt.datetime.now, writable=False)
+    updated_at = DatetimeField(default=dt.datetime.now, writable=False)
 
     @classmethod
     def __on_define__(cls, db: TypeDAL) -> None:
@@ -73,7 +69,7 @@ class TimestampsMixin(Mixin):
                 _: Set: Unused parameter.
                 row (OpRow): The row to update.
             """
-            row["updated_at"] = datetime.now()
+            row["updated_at"] = dt.datetime.now()
 
         cls._before_update.append(set_updated_at)
 
@@ -89,7 +85,7 @@ def slug_random_suffix(length: int = 8) -> str:
     return base64.urlsafe_b64encode(os.urandom(length)).rstrip(b"=").decode().strip("=")
 
 
-T = typing.TypeVar("T")
+T = t.TypeVar("T")
 
 
 # noinspection PyPep8Naming
@@ -112,7 +108,7 @@ class HAS_UNIQUE_SLUG(IS_NOT_IN_DB):
         """
         super().__init__(db, field, error_message)
 
-    def validate(self, original: T, record_id: Optional[int] = None) -> T:
+    def validate(self, original: T, record_id: t.Optional[int] = None) -> T:
         """
         Performs checks to see if the slug already exists for a different row.
         """
@@ -154,7 +150,7 @@ class SlugMixin(Mixin):
     # pub:
     slug = StringField(unique=True, writable=False)
     # priv:
-    __settings__: typing.TypedDict(  # type: ignore
+    __settings__: t.TypedDict(  # type: ignore
         "SlugFieldSettings",
         {
             "slug_field": str,
@@ -164,10 +160,10 @@ class SlugMixin(Mixin):
 
     def __init_subclass__(
         cls,
-        slug_field: typing.Optional[str] = None,
+        slug_field: t.Optional[str] = None,
         slug_suffix_length: int = 0,
-        slug_suffix: Optional[int] = None,
-        **kw: Any,
+        slug_suffix: t.Optional[int] = None,
+        **kw: t.Any,
     ) -> None:
         """
         Bind 'slug field' option to be used later (on_define).
@@ -235,7 +231,7 @@ class SlugMixin(Mixin):
             slug_field.requires = current_requires
 
     @classmethod
-    def from_slug(cls: typing.Type[T_MetaInstance], slug: str, join: bool = True) -> Optional[T_MetaInstance]:
+    def from_slug(cls: t.Type[T_MetaInstance], slug: str, join: bool = True) -> t.Optional[T_MetaInstance]:
         """
         Find a row by its slug.
         """
@@ -246,7 +242,7 @@ class SlugMixin(Mixin):
         return builder.first()
 
     @classmethod
-    def from_slug_or_fail(cls: typing.Type[T_MetaInstance], slug: str, join: bool = True) -> T_MetaInstance:
+    def from_slug_or_fail(cls: t.Type[T_MetaInstance], slug: str, join: bool = True) -> T_MetaInstance:
         """
         Find a row by its slug, or raise an error if it doesn't exist.
         """