asyncpg-typed 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

asyncpg_typed/__init__.py

@@ -4,7 +4,7 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2025, Levente Hunyadi"
 __license__ = "MIT"
@@ -13,14 +13,15 @@ __status__ = "Production"
 
 import enum
 import sys
+import typing
 from abc import abstractmethod
-from collections.abc import Iterable, Sequence
-from datetime import date, datetime, time
+from collections.abc import Callable, Iterable, Sequence
+from datetime import date, datetime, time, timedelta
 from decimal import Decimal
 from functools import reduce
 from io import StringIO
 from types import UnionType
-from typing import Any, Generic, TypeAlias, TypeVar, Union, get_args, get_origin, overload
+from typing import Any, Protocol, TypeAlias, TypeVar, Union, get_args, get_origin, overload
 from uuid import UUID
 
 import asyncpg
@@ -31,12 +32,11 @@ if sys.version_info < (3, 11):
 else:
     from typing import LiteralString, TypeVarTuple, Unpack
 
-# list of supported data types
-DATA_TYPES: list[type[Any]] = [bool, int, float, Decimal, date, time, datetime, str, bytes, UUID]
+JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
 
-# maximum number of inbound query parameters
-NUM_ARGS = 8
+RequiredJsonType = bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
 
+TargetType: TypeAlias = type[Any] | UnionType
 
 if sys.version_info >= (3, 11):
 
@@ -83,6 +83,14 @@ def is_standard_type(tp: Any) -> bool:
     return tp.__module__ == "builtins" or tp.__module__ == UnionType.__module__
 
 
+def is_json_type(tp: Any) -> bool:
+    """
+    `True` if the type represents an object de-serialized from a JSON string.
+    """
+
+    return tp in [JsonType, RequiredJsonType]
+
+
 def make_union_type(tpl: list[Any]) -> UnionType:
     """
     Creates a `UnionType` (a.k.a. `A | B | C`) dynamically at run time.
@@ -111,38 +119,77 @@ def get_required_type(tp: Any) -> Any:
         return type(None)
 
 
-# maps PostgreSQL internal type names to Python types
-_name_to_type: dict[str, Any] = {
-    "bool": bool,
-    "int2": int,
-    "int4": int,
-    "int8": int,
-    "float4": float,
-    "float8": float,
-    "numeric": Decimal,
-    "date": date,
-    "time": time,
-    "timetz": time,
-    "timestamp": datetime,
-    "timestamptz": datetime,
-    "bpchar": str,
-    "varchar": str,
-    "text": str,
-    "bytea": bytes,
-    "json": str,
-    "jsonb": str,
-    "uuid": UUID,
+_json_converter: Callable[[str], JsonType]
+if typing.TYPE_CHECKING:
+    import json
+
+    _json_decoder = json.JSONDecoder()
+    _json_converter = _json_decoder.decode
+else:
+    try:
+        import orjson
+
+        _json_converter = orjson.loads
+    except ModuleNotFoundError:
+        import json
+
+        _json_decoder = json.JSONDecoder()
+        _json_converter = _json_decoder.decode
+
+
+def get_converter_for(tp: Any) -> Callable[[Any], Any]:
+    """
+    Returns a callable that takes a wire type and returns a target type.
+
+    A wire type is one of the types returned by asyncpg.
+    A target type is one of the types supported by the library.
+    """
+
+    if is_json_type(tp):
+        # asyncpg returns fields of type `json` and `jsonb` as `str`, which must be de-serialized
+        return _json_converter
+    else:
+        # target data types that require conversion must have a single-argument `__init__` that takes an object of the source type
+        return tp
+
+
+# maps PostgreSQL internal type names to compatible Python types
+_name_to_type: dict[str, tuple[Any, ...]] = {
+    "bool": (bool,),
+    "int2": (int,),
+    "int4": (int,),
+    "int8": (int,),
+    "float4": (float,),
+    "float8": (float,),
+    "numeric": (Decimal,),
+    "date": (date,),
+    "time": (time,),
+    "timetz": (time,),
+    "timestamp": (datetime,),
+    "timestamptz": (datetime,),
+    "interval": (timedelta,),
+    "bpchar": (str,),
+    "varchar": (str,),
+    "text": (str,),
+    "bytea": (bytes,),
+    "json": (str, RequiredJsonType),
+    "jsonb": (str, RequiredJsonType),
+    "uuid": (UUID,),
+    "xml": (str,),
 }
 
 
-def check_data_type(schema: str, name: str, data_type: type[Any]) -> bool:
+def check_data_type(schema: str, name: str, data_type: TargetType) -> bool:
     """
     Verifies if the Python target type can represent the PostgreSQL source type.
     """
 
     if schema == "pg_catalog":
-        expected_type = _name_to_type.get(name)
-        return expected_type == data_type
+        if is_enum_type(data_type):
+            return name in ["bpchar", "varchar", "text"]
+
+        expected_types = _name_to_type.get(name)
+        return expected_types is not None and data_type in expected_types
     else:
         if is_standard_type(data_type):
             return False
@@ -153,9 +200,9 @@ def check_data_type(schema: str, name: str, data_type: type[Any]) -> bool:
 
 class _SQLPlaceholder:
     ordinal: int
-    data_type: type[Any]
+    data_type: TargetType
 
-    def __init__(self, ordinal: int, data_type: type[Any]) -> None:
+    def __init__(self, ordinal: int, data_type: TargetType) -> None:
         self.ordinal = ordinal
         self.data_type = data_type
 
@@ -169,14 +216,15 @@ class _SQLObject:
     """
 
     parameter_data_types: tuple[_SQLPlaceholder, ...]
-    resultset_data_types: tuple[type[Any], ...]
+    resultset_data_types: tuple[TargetType, ...]
     required: int
     cast: int
+    converters: tuple[Callable[[Any], Any], ...]
 
     def __init__(
         self,
-        input_data_types: tuple[type[Any], ...],
-        output_data_types: tuple[type[Any], ...],
+        input_data_types: tuple[TargetType, ...],
+        output_data_types: tuple[TargetType, ...],
     ) -> None:
         self.parameter_data_types = tuple(_SQLPlaceholder(ordinal, get_required_type(arg)) for ordinal, arg in enumerate(input_data_types, start=1))
         self.resultset_data_types = tuple(get_required_type(data_type) for data_type in output_data_types)
@@ -187,12 +235,14 @@ class _SQLObject:
             required |= (not is_optional_type(data_type)) << index
         self.required = required
 
-        # create a bit-field of types that require cast/conversion (1: pass to __init__; 0: skip)
+        # create a bit-field of types that require cast or serialization (1: apply conversion; 0: forward value as-is)
         cast = 0
         for index, data_type in enumerate(self.resultset_data_types):
-            cast |= is_enum_type(data_type) << index
+            cast |= (is_enum_type(data_type) or is_json_type(data_type)) << index
         self.cast = cast
 
+        self.converters = tuple(get_converter_for(data_type) for data_type in self.resultset_data_types)
+
     def _raise_required_is_none(self, row: tuple[Any, ...], row_index: int | None = None) -> None:
         """
         Raises an error with the index of the first column value that is of a required type but has been assigned a value of `None`.
@@ -345,8 +395,8 @@ if sys.version_info >= (3, 14):
             self,
             template: Template,
             *,
-            args: tuple[type[Any], ...],
-            resultset: tuple[type[Any], ...],
+            args: tuple[TargetType, ...],
+            resultset: tuple[TargetType, ...],
         ) -> None:
             super().__init__(args, resultset)
 
@@ -395,8 +445,8 @@ class _SQLString(_SQLObject):
         self,
         sql: str,
         *,
-        args: tuple[type[Any], ...],
-        resultset: tuple[type[Any], ...],
+        args: tuple[TargetType, ...],
+        resultset: tuple[TargetType, ...],
     ) -> None:
         super().__init__(args, resultset)
         self.sql = sql
@@ -405,7 +455,7 @@ class _SQLString(_SQLObject):
         return self.sql
 
 
-class _SQL:
+class _SQL(Protocol):
     """
     Represents a SQL statement with associated type information.
     """
@@ -449,8 +499,8 @@ class _SQLImpl(_SQL):
     def _cast_fetch(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
         cast = self.sql.cast
         if cast:
-            data_types = self.sql.resultset_data_types
-            resultset = [tuple((data_types[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
+            converters = self.sql.converters
+            resultset = [tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
         else:
             resultset = [tuple(value for value in row) for row in rows]
         self.sql.check_rows(resultset)
@@ -473,8 +523,8 @@ class _SQLImpl(_SQL):
             return None
         cast = self.sql.cast
         if cast:
-            data_types = self.sql.resultset_data_types
-            resultset = tuple((data_types[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
+            converters = self.sql.converters
+            resultset = tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
         else:
             resultset = tuple(value for value in row)
         self.sql.check_row(resultset)
@@ -483,34 +533,29 @@ class _SQLImpl(_SQL):
     async def fetchval(self, connection: asyncpg.Connection, *args: Any) -> Any:
         stmt = await self._prepare(connection)
         value = await stmt.fetchval(*args)
-        result = self.sql.resultset_data_types[0](value) if value is not None and self.sql.cast else value
+        result = self.sql.converters[0](value) if value is not None and self.sql.cast else value
         self.sql.check_value(result)
         return result
 
 
-### START OF AUTO-GENERATED BLOCK ###
-
-PS = TypeVar("PS")
 P1 = TypeVar("P1")
-P2 = TypeVar("P2")
-P3 = TypeVar("P3")
-P4 = TypeVar("P4")
-P5 = TypeVar("P5")
-P6 = TypeVar("P6")
-P7 = TypeVar("P7")
-P8 = TypeVar("P8")
-RS = TypeVar("RS")
+PX = TypeVarTuple("PX")
+
+RT = TypeVar("RT")
 R1 = TypeVar("R1")
 R2 = TypeVar("R2")
 RX = TypeVarTuple("RX")
 
 
-class SQL_P0(_SQL):
+### START OF AUTO-GENERATED BLOCK ###
+
+
+class SQL_P0(Protocol):
     @abstractmethod
     async def execute(self, connection: Connection) -> None: ...
 
 
-class SQL_P0_RS(Generic[R1], SQL_P0):
+class SQL_R1_P0(SQL_P0, Protocol[R1]):
     @abstractmethod
     async def fetch(self, connection: Connection) -> list[tuple[R1]]: ...
     @abstractmethod
@@ -519,305 +564,64 @@ class SQL_P0_RS(Generic[R1], SQL_P0):
     async def fetchval(self, connection: Connection) -> R1: ...
 
 
-class SQL_P0_RX(Generic[R1, R2, Unpack[RX]], SQL_P0):
-    @abstractmethod
-    async def fetch(self, connection: Connection) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P1(Generic[P1], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1]]) -> None: ...
-
-
-class SQL_P1_RS(Generic[P1, R1], SQL_P1[P1]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1) -> R1: ...
-
-
-class SQL_P1_RX(Generic[P1, R1, R2, Unpack[RX]], SQL_P1[P1]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P2(Generic[P1, P2], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2]]) -> None: ...
-
-
-class SQL_P2_RS(Generic[P1, P2, R1], SQL_P2[P1, P2]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2) -> R1: ...
-
-
-class SQL_P2_RX(Generic[P1, P2, R1, R2, Unpack[RX]], SQL_P2[P1, P2]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P3(Generic[P1, P2, P3], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3]]) -> None: ...
-
-
-class SQL_P3_RS(Generic[P1, P2, P3, R1], SQL_P3[P1, P2, P3]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> R1: ...
-
-
-class SQL_P3_RX(Generic[P1, P2, P3, R1, R2, Unpack[RX]], SQL_P3[P1, P2, P3]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P4(Generic[P1, P2, P3, P4], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4]]) -> None: ...
-
-
-class SQL_P4_RS(Generic[P1, P2, P3, P4, R1], SQL_P4[P1, P2, P3, P4]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> R1: ...
-
-
-class SQL_P4_RX(Generic[P1, P2, P3, P4, R1, R2, Unpack[RX]], SQL_P4[P1, P2, P3, P4]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P5(Generic[P1, P2, P3, P4, P5], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5]]) -> None: ...
-
-
-class SQL_P5_RS(Generic[P1, P2, P3, P4, P5, R1], SQL_P5[P1, P2, P3, P4, P5]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> R1: ...
-
-
-class SQL_P5_RX(Generic[P1, P2, P3, P4, P5, R1, R2, Unpack[RX]], SQL_P5[P1, P2, P3, P4, P5]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P6(Generic[P1, P2, P3, P4, P5, P6], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6]]) -> None: ...
-
-
-class SQL_P6_RS(Generic[P1, P2, P3, P4, P5, P6, R1], SQL_P6[P1, P2, P3, P4, P5, P6]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> R1: ...
-
-
-class SQL_P6_RX(Generic[P1, P2, P3, P4, P5, P6, R1, R2, Unpack[RX]], SQL_P6[P1, P2, P3, P4, P5, P6]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> list[tuple[R1, R2, Unpack[RX]]]: ...
+class SQL_RX_P0(SQL_P0, Protocol[RT]):
     @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
+    async def fetch(self, connection: Connection) -> list[RT]: ...
     @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6) -> tuple[R1, R2, Unpack[RX]] | None: ...
+    async def fetchrow(self, connection: Connection) -> RT | None: ...
 
 
-class SQL_P7(Generic[P1, P2, P3, P4, P5, P6, P7], _SQL):
+class SQL_PX(Protocol[Unpack[PX]]):
     @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> None: ...
+    async def execute(self, connection: Connection, *args: Unpack[PX]) -> None: ...
     @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> None: ...
+    async def executemany(self, connection: Connection, args: Iterable[tuple[Unpack[PX]]]) -> None: ...
 
 
-class SQL_P7_RS(Generic[P1, P2, P3, P4, P5, P6, P7, R1], SQL_P7[P1, P2, P3, P4, P5, P6, P7]):
+class SQL_R1_PX(SQL_PX[Unpack[PX]], Protocol[R1, Unpack[PX]]):
     @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> list[tuple[R1]]: ...
+    async def fetch(self, connection: Connection, *args: Unpack[PX]) -> list[tuple[R1]]: ...
     @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> list[tuple[R1]]: ...
+    async def fetchmany(self, connection: Connection, args: Iterable[tuple[Unpack[PX]]]) -> list[tuple[R1]]: ...
     @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> tuple[R1] | None: ...
+    async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> tuple[R1] | None: ...
     @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> R1: ...
+    async def fetchval(self, connection: Connection, *args: Unpack[PX]) -> R1: ...
 
 
-class SQL_P7_RX(Generic[P1, P2, P3, P4, P5, P6, P7, R1, R2, Unpack[RX]], SQL_P7[P1, P2, P3, P4, P5, P6, P7]):
+class SQL_RX_PX(SQL_PX[Unpack[PX]], Protocol[RT, Unpack[PX]]):
     @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> list[tuple[R1, R2, Unpack[RX]]]: ...
+    async def fetch(self, connection: Connection, *args: Unpack[PX]) -> list[RT]: ...
     @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
+    async def fetchmany(self, connection: Connection, args: Iterable[tuple[Unpack[PX]]]) -> list[RT]: ...
     @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P8(Generic[P1, P2, P3, P4, P5, P6, P7, P8], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7, P8]]) -> None: ...
-
-
-class SQL_P8_RS(Generic[P1, P2, P3, P4, P5, P6, P7, P8, R1], SQL_P8[P1, P2, P3, P4, P5, P6, P7, P8]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7, P8]]) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> tuple[R1] | None: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> R1: ...
-
-
-class SQL_P8_RX(Generic[P1, P2, P3, P4, P5, P6, P7, P8, R1, R2, Unpack[RX]], SQL_P8[P1, P2, P3, P4, P5, P6, P7, P8]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7, P8]]) -> list[tuple[R1, R2, Unpack[RX]]]: ...
-    @abstractmethod
-    async def fetchrow(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8) -> tuple[R1, R2, Unpack[RX]] | None: ...
+    async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> RT | None: ...
 
 
 @overload
 def sql(stmt: SQLExpression) -> SQL_P0: ...
 @overload
-def sql(stmt: SQLExpression, *, result: type[RS]) -> SQL_P0_RS[RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_P0_RS[R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P0_RX[R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[PS]) -> SQL_P1[PS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1]]) -> SQL_P1[P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[PS], result: type[RS]) -> SQL_P1_RS[PS, RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1]], resultset: type[tuple[R1]]) -> SQL_P1_RS[P1, R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[PS], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[PS, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[P1, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]]) -> SQL_P2[P1, P2]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], result: type[RS]) -> SQL_P2_RS[P1, P2, RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[tuple[R1]]) -> SQL_P2_RS[P1, P2, R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P2_RX[P1, P2, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]]) -> SQL_P3[P1, P2, P3]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], result: type[RS]) -> SQL_P3_RS[P1, P2, P3, RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], resultset: type[tuple[R1]]) -> SQL_P3_RS[P1, P2, P3, R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P3_RX[P1, P2, P3, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]]) -> SQL_P4[P1, P2, P3, P4]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], result: type[RS]) -> SQL_P4_RS[P1, P2, P3, P4, RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], resultset: type[tuple[R1]]) -> SQL_P4_RS[P1, P2, P3, P4, R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P4_RX[P1, P2, P3, P4, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]]) -> SQL_P5[P1, P2, P3, P4, P5]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], result: type[RS]) -> SQL_P5_RS[P1, P2, P3, P4, P5, RS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], resultset: type[tuple[R1]]) -> SQL_P5_RS[P1, P2, P3, P4, P5, R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P5_RX[P1, P2, P3, P4, P5, R1, R2, Unpack[RX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]]) -> SQL_P6[P1, P2, P3, P4, P5, P6]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]], result: type[RS]) -> SQL_P6_RS[P1, P2, P3, P4, P5, P6, RS]: ...
+def sql(stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]], resultset: type[tuple[R1]]) -> SQL_P6_RS[P1, P2, P3, P4, P5, P6, R1]: ...
+def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P6_RX[P1, P2, P3, P4, P5, P6, R1, R2, Unpack[RX]]: ...
+def sql(stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> SQL_P7[P1, P2, P3, P4, P5, P6, P7]: ...
+def sql(stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], result: type[RS]) -> SQL_P7_RS[P1, P2, P3, P4, P5, P6, P7, RS]: ...
+def sql(stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], resultset: type[tuple[R1]]) -> SQL_P7_RS[P1, P2, P3, P4, P5, P6, P7, R1]: ...
+def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P7_RX[P1, P2, P3, P4, P5, P6, P7, R1, R2, Unpack[RX]]: ...
+def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]]) -> SQL_P8[P1, P2, P3, P4, P5, P6, P7, P8]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]], result: type[RS]) -> SQL_P8_RS[P1, P2, P3, P4, P5, P6, P7, P8, RS]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]], resultset: type[tuple[R1]]) -> SQL_P8_RS[P1, P2, P3, P4, P5, P6, P7, P8, R1]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P8_RX[P1, P2, P3, P4, P5, P6, P7, P8, R1, R2, Unpack[RX]]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
 
 
 ### END OF AUTO-GENERATED BLOCK ###

{asyncpg_typed-0.1.1.dist-info → asyncpg_typed-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.1
+Version: 0.1.2
 Summary: Type-safe queries for asyncpg
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -74,6 +74,25 @@ try:
 
 finally:
     await conn.close()
+
+# create a list of data-class instances from a list of typed tuples
+@dataclass
+class DataObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str | None
+
+# ✅ Valid initializer call
+items = [DataObject(*row) for row in rows]
+
+@dataclass
+class MismatchedObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str
+
+# ⚠️ Argument of type "int | None" cannot be assigned to parameter "integer_value" of type "int" in function "__init__"; "None" is not assignable to "int"
+items = [MismatchedObject(*row) for row in rows]
 ```
 
 
@@ -137,7 +156,7 @@ The parameters `arg` and `result` take a single type `P` or `R`. Passing a simpl
 
 The number of types in `args` must correspond to the number of query parameters. (This is validated on calling `sql(...)` for the *t-string* syntax.) The number of types in `resultset` must correspond to the number of columns returned by the query.
 
-Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types.
+Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types. When there are multiple options separated by a slash, either of the types can be specified as a source or target type.
 
 | PostgreSQL type   | Python type        |
 | ----------------- | ------------------ |
@@ -154,15 +173,19 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `timetz`          | `time` (tz)        |
 | `timestamp`       | `datetime` (naive) |
 | `timestamptz`     | `datetime` (tz)    |
+| `interval`        | `timedelta`        |
 | `char(N)`         | `str`              |
 | `varchar(N)`      | `str`              |
 | `text`            | `str`              |
 | `bytea`           | `bytes`            |
-| `json`            | `str`              |
-| `jsonb`           | `str`              |
+| `json`            | `str`/`JsonType`   |
+| `jsonb`           | `str`/`JsonType`   |
+| `xml`             | `str`              |
 | `uuid`            | `UUID`             |
 | enumeration       | `E: StrEnum`       |
 
+PostgreSQL types `json` and `jsonb` are [returned by asyncpg](https://magicstack.github.io/asyncpg/current/usage.html#type-conversion) as Python type `str`. However, if we specify the union type `JsonType` in `args` or `resultset`, the JSON string is parsed as if by calling `json.loads()`. (`JsonType` is defined in the module `asyncpg_typed`.) If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
+
 ### Using a SQL object
 
 The function `sql` returns an object that derives from the base class `_SQL` and is specific to the number and types of parameters passed in `args` and `resultset`.

asyncpg_typed-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+asyncpg_typed/__init__.py,sha256=Z9UqmIr2QcSpGe7qC-ddMDDkwnJSGg5mm1dqiWPKYQM,24915
+asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asyncpg_typed-0.1.2.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
+asyncpg_typed-0.1.2.dist-info/METADATA,sha256=9wNzfDUQWAOhedM3g3cx_TYYlaaDjlqTrNq1qEqcK0k,9932
+asyncpg_typed-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+asyncpg_typed-0.1.2.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
+asyncpg_typed-0.1.2.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+asyncpg_typed-0.1.2.dist-info/RECORD,,

asyncpg_typed-0.1.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-asyncpg_typed/__init__.py,sha256=2c4xyDjjR-yVrIlcgL-rqLJlWB7_JJR76eRxPDTqAPY,38154
-asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-asyncpg_typed-0.1.1.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
-asyncpg_typed-0.1.1.dist-info/METADATA,sha256=6RqDzYtI9FnIbKAjHHQdhnOQhBfM3pK1IHUOYXNf9yU,8652
-asyncpg_typed-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-asyncpg_typed-0.1.1.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
-asyncpg_typed-0.1.1.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-asyncpg_typed-0.1.1.dist-info/RECORD,,