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

asyncpg_typed/__init__.py

@@ -4,43 +4,63 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2025, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __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
 from asyncpg.prepared_stmt import PreparedStatement
 
 if sys.version_info < (3, 11):
-    from typing_extensions import TypeVarTuple, Unpack
+    from typing_extensions import LiteralString, TypeVarTuple, Unpack
 else:
-    from typing import TypeVarTuple, Unpack
+    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):
+
+    def is_enum_type(typ: object) -> bool:
+        """
+        `True` if the specified type is an enumeration type.
+        """
+
+        return isinstance(typ, enum.EnumType)
+
+else:
+
+    def is_enum_type(typ: object) -> bool:
+        """
+        `True` if the specified type is an enumeration type.
+        """
+
+        # use an explicit isinstance(..., type) check to filter out special forms like generics
+        return isinstance(typ, type) and issubclass(typ, enum.Enum)
 
 
 def is_union_type(tp: Any) -> bool:
     """
-    Returns `True` if `tp` is a union type such as `A | B` or `Union[A, B]`.
+    `True` if `tp` is a union type such as `A | B` or `Union[A, B]`.
     """
 
     origin = get_origin(tp)
@@ -49,7 +69,7 @@ def is_union_type(tp: Any) -> bool:
 
 def is_optional_type(tp: Any) -> bool:
     """
-    Returns `True` if `tp` is an optional type such as `T | None`, `Optional[T]` or `Union[T, None]`.
+    `True` if `tp` is an optional type such as `T | None`, `Optional[T]` or `Union[T, None]`.
     """
 
     return is_union_type(tp) and any(a is type(None) for a in get_args(tp))
@@ -57,12 +77,20 @@ def is_optional_type(tp: Any) -> bool:
 
 def is_standard_type(tp: Any) -> bool:
     """
-    Returns `True` if the type represents a built-in or a well-known standard type.
+    `True` if the type represents a built-in or a well-known standard type.
     """
 
     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.
@@ -91,52 +119,90 @@ 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(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.
     """
 
-    expected_type = _name_to_type.get(name)
-    required_type = get_required_type(data_type)
+    if schema == "pg_catalog":
+        if is_enum_type(data_type):
+            return name in ["bpchar", "varchar", "text"]
 
-    if expected_type is not None:
-        return expected_type == required_type
-    if is_standard_type(required_type):
-        return False
+        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
 
-    # user-defined type registered with `conn.set_type_codec()`
-    return True
+        # user-defined type registered with `conn.set_type_codec()`
+        return True
 
 
 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
 
@@ -150,37 +216,33 @@ 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,
-        *,
-        args: type[Any] | None = None,
-        resultset: type[Any] | None = None,
+        input_data_types: tuple[TargetType, ...],
+        output_data_types: tuple[TargetType, ...],
     ) -> None:
-        if args is not None:
-            if get_origin(args) is tuple:
-                self.parameter_data_types = tuple(_SQLPlaceholder(ordinal, arg) for ordinal, arg in enumerate(get_args(args), start=1))
-            else:
-                self.parameter_data_types = (_SQLPlaceholder(1, args),)
-        else:
-            self.parameter_data_types = ()
-
-        if resultset is not None:
-            if get_origin(resultset) is tuple:
-                self.resultset_data_types = get_args(resultset)
-            else:
-                self.resultset_data_types = (resultset,)
-        else:
-            self.resultset_data_types = ()
+        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)
 
         # create a bit-field of required types (1: required; 0: optional)
         required = 0
-        for index, data_type in enumerate(self.resultset_data_types):
+        for index, data_type in enumerate(output_data_types):
             required |= (not is_optional_type(data_type)) << index
         self.required = required
 
+        # 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) 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`.
@@ -319,7 +381,7 @@ class _SQLObject:
 if sys.version_info >= (3, 14):
     from string.templatelib import Interpolation, Template  # type: ignore[import-not-found]
 
-    SQLExpression: TypeAlias = Template | str
+    SQLExpression: TypeAlias = Template | LiteralString
 
     class _SQLTemplate(_SQLObject):
         """
@@ -333,10 +395,10 @@ if sys.version_info >= (3, 14):
             self,
             template: Template,
             *,
-            args: type[Any] | None = None,
-            resultset: type[Any] | None = None,
+            args: tuple[TargetType, ...],
+            resultset: tuple[TargetType, ...],
         ) -> None:
-            super().__init__(args=args, resultset=resultset)
+            super().__init__(args, resultset)
 
             for ip in template.interpolations:
                 if ip.conversion is not None:
@@ -348,7 +410,7 @@ if sys.version_info >= (3, 14):
 
             self.strings = template.strings
 
-            if args is not None:
+            if len(self.parameter_data_types) > 0:
 
                 def _to_placeholder(ip: Interpolation) -> _SQLPlaceholder:
                     ordinal = int(ip.value)
@@ -369,7 +431,7 @@ if sys.version_info >= (3, 14):
             return buf.getvalue()
 
 else:
-    SQLExpression = str
+    SQLExpression = LiteralString
 
 
 class _SQLString(_SQLObject):
@@ -383,17 +445,17 @@ class _SQLString(_SQLObject):
         self,
         sql: str,
         *,
-        args: type[Any] | None = None,
-        resultset: type[Any] | None = None,
+        args: tuple[TargetType, ...],
+        resultset: tuple[TargetType, ...],
     ) -> None:
-        super().__init__(args=args, resultset=resultset)
+        super().__init__(args, resultset)
         self.sql = sql
 
     def query(self) -> str:
         return self.sql
 
 
-class _SQL:
+class _SQL(Protocol):
     """
     Represents a SQL statement with associated type information.
     """
@@ -422,7 +484,7 @@ class _SQLImpl(_SQL):
         stmt = await connection.prepare(self.sql.query())
 
         for attr, data_type in zip(stmt.get_attributes(), self.sql.resultset_data_types, strict=True):
-            if not check_data_type(attr.type.name, data_type):
+            if not check_data_type(attr.type.schema, attr.type.name, data_type):
                 raise TypeError(f"expected: {data_type} in column `{attr.name}`; got: `{attr.type.kind}` of `{attr.type.name}`")
 
         return stmt
@@ -434,60 +496,66 @@ class _SQLImpl(_SQL):
         stmt = await self._prepare(connection)
         await stmt.executemany(args)
 
+    def _cast_fetch(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
+        cast = self.sql.cast
+        if cast:
+            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)
+        return resultset
+
     async def fetch(self, connection: asyncpg.Connection, *args: Any) -> list[tuple[Any, ...]]:
         stmt = await self._prepare(connection)
         rows = await stmt.fetch(*args)
-        resultset = [tuple(value for value in row) for row in rows]
-        self.sql.check_rows(resultset)
-        return resultset
+        return self._cast_fetch(rows)
 
     async def fetchmany(self, connection: asyncpg.Connection, args: Iterable[Sequence[Any]]) -> list[tuple[Any, ...]]:
         stmt = await self._prepare(connection)
-        rows = await stmt.fetchmany(args)  # type: ignore[arg-type, call-arg]  # pyright: ignore[reportCallIssue]
-        rows = typing.cast(list[asyncpg.Record], rows)
-        resultset = [tuple(value for value in row) for row in rows]
-        self.sql.check_rows(resultset)
-        return resultset
+        rows = await stmt.fetchmany(args)
+        return self._cast_fetch(rows)
 
     async def fetchrow(self, connection: asyncpg.Connection, *args: Any) -> tuple[Any, ...] | None:
         stmt = await self._prepare(connection)
         row = await stmt.fetchrow(*args)
         if row is None:
             return None
-        resultset = tuple(value for value in row)
+        cast = self.sql.cast
+        if cast:
+            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)
         return resultset
 
     async def fetchval(self, connection: asyncpg.Connection, *args: Any) -> Any:
         stmt = await self._prepare(connection)
         value = await stmt.fetchval(*args)
-        self.sql.check_value(value)
-        return 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", bool, bool | None, int, int | None, float, float | None, Decimal, Decimal | None, date, date | None, time, time | None, datetime, datetime | None, str, str | None, bytes, bytes | None, UUID, UUID | None)
 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", bool, bool | None, int, int | None, float, float | None, Decimal, Decimal | None, date, date | None, time, time | None, datetime, datetime | None, str, str | None, bytes, bytes | None, UUID, UUID | None)
+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
@@ -496,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]]]: ...
+class SQL_RX_P0(SQL_P0, Protocol[RT]):
     @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2]]) -> 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) -> tuple[R1, R2, Unpack[RX]] | None: ...
+    async def fetchrow(self, connection: Connection) -> RT | None: ...
 
 
-class SQL_P3(Generic[P1, P2, P3], _SQL):
+class SQL_PX(Protocol[Unpack[PX]]):
     @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3) -> None: ...
+    async def execute(self, connection: Connection, *args: Unpack[PX]) -> None: ...
     @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3]]) -> None: ...
+    async def executemany(self, connection: Connection, args: Iterable[tuple[Unpack[PX]]]) -> None: ...
 
 
-class SQL_P3_RS(Generic[P1, P2, P3, R1], SQL_P3[P1, P2, P3]):
+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) -> 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]]) -> 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) -> 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) -> R1: ...
+    async def fetchval(self, connection: Connection, *args: Unpack[PX]) -> R1: ...
 
 
-class SQL_P3_RX(Generic[P1, P2, P3, R1, R2, Unpack[RX]], SQL_P3[P1, P2, P3]):
+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) -> 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):
+    async def fetch(self, connection: Connection, *args: Unpack[PX]) -> list[RT]: ...
     @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4) -> None: ...
+    async def fetchmany(self, connection: Connection, args: Iterable[tuple[Unpack[PX]]]) -> list[RT]: ...
     @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]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6]]) -> 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) -> tuple[R1, R2, Unpack[RX]] | None: ...
-
-
-class SQL_P7(Generic[P1, P2, P3, P4, P5, P6, P7], _SQL):
-    @abstractmethod
-    async def execute(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> None: ...
-    @abstractmethod
-    async def executemany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> None: ...
-
-
-class SQL_P7_RS(Generic[P1, P2, P3, P4, P5, P6, P7, R1], SQL_P7[P1, P2, P3, P4, P5, P6, P7]):
-    @abstractmethod
-    async def fetch(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> list[tuple[R1]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> 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: ...
-    @abstractmethod
-    async def fetchval(self, connection: Connection, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7) -> 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]):
-    @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]]]: ...
-    @abstractmethod
-    async def fetchmany(self, connection: Connection, args: Iterable[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> 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) -> 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, *, resultset: 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, *, args: type[PS]) -> SQL_P1[PS]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1]]) -> SQL_P1[P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[PS], resultset: 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]: ...
+def sql(stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[PS], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[PS, R1, R2, Unpack[RX]]: ...
+def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[P1, 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]]) -> SQL_P2[P1, P2]: ...
+def sql(stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[RS]) -> SQL_P2_RS[P1, P2, 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]], resultset: type[tuple[R1]]) -> SQL_P2_RS[P1, P2, 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]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P2_RX[P1, P2, 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]]) -> SQL_P3[P1, P2, P3]: ...
+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]], resultset: type[RS]) -> SQL_P3_RS[P1, P2, P3, 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]], resultset: type[tuple[R1]]) -> SQL_P3_RS[P1, P2, P3, 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]], 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]], resultset: 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]], resultset: 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]], resultset: type[RS]) -> SQL_P6_RS[P1, P2, P3, P4, P5, P6, RS]: ...
-@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]: ...
-@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]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]]) -> SQL_P7[P1, P2, P3, P4, P5, P6, P7]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], resultset: type[RS]) -> SQL_P7_RS[P1, P2, P3, P4, P5, P6, P7, RS]: ...
-@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]: ...
-@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]]: ...
-@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]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]], resultset: type[RS]) -> SQL_P8_RS[P1, P2, P3, P4, P5, P6, P7, P8, RS]: ...
-@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]: ...
-@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 ###
@@ -805,23 +632,50 @@ def sql(
     *,
     args: type[Any] | None = None,
     resultset: type[Any] | None = None,
+    arg: type[Any] | None = None,
+    result: type[Any] | None = None,
 ) -> _SQL:
     """
     Creates a SQL statement with associated type information.
 
-    :param stmt: SQL statement as a string or template.
-    :param args: Type signature for input parameters. Use the type for a single parameter (e.g. `int`) or `tuple[...]` for multiple parameters.
-    :param resultset: Type signature for output data. Use the type for a single parameter (e.g. `int`) or `tuple[...]` for multiple parameters.
+    :param stmt: SQL statement as a literal string or template.
+    :param args: Type signature for multiple input parameters (e.g. `tuple[bool, int, str]`).
+    :param resultset: Type signature for multiple resultset columns (e.g. `tuple[datetime, Decimal, str]`).
+    :param arg: Type signature for a single input parameter (e.g. `int`).
+    :param result: Type signature for a single result column (e.g. `UUID`).
     """
 
+    if args is not None and arg is not None:
+        raise TypeError("expected: either `args` or `arg`; got: both")
+    if resultset is not None and result is not None:
+        raise TypeError("expected: either `resultset` or `result`; got: both")
+
+    if args is not None:
+        if get_origin(args) is not tuple:
+            raise TypeError(f"expected: `type[tuple[T, ...]]` for `args`; got: {type(args)}")
+        input_data_types = get_args(args)
+    elif arg is not None:
+        input_data_types = (arg,)
+    else:
+        input_data_types = ()
+
+    if resultset is not None:
+        if get_origin(resultset) is not tuple:
+            raise TypeError(f"expected: `type[tuple[T, ...]]` for `resultset`; got: {type(resultset)}")
+        output_data_types = get_args(resultset)
+    elif result is not None:
+        output_data_types = (result,)
+    else:
+        output_data_types = ()
+
     if sys.version_info >= (3, 14):
         obj: _SQLObject
         match stmt:
             case Template():
-                obj = _SQLTemplate(stmt, args=args, resultset=resultset)
+                obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types)
             case str():
-                obj = _SQLString(stmt, args=args, resultset=resultset)
+                obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
     else:
-        obj = _SQLString(stmt, args=args, resultset=resultset)
+        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
 
     return _SQLImpl(obj)

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.0
+Version: 0.1.2
 Summary: Type-safe queries for asyncpg
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hunyadi/asyncpg_typed
 Project-URL: Source, https://github.com/hunyadi/asyncpg_typed
-Keywords: asyncpg,typed,database-client
+Keywords: asyncpg,typed,database-client,postgres
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -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]
 ```
 
 
@@ -85,19 +104,21 @@ Instantiate a SQL object with the `sql` function:
 
 ```python
 def sql(
-    stmt: str | string.templatelib.Template,
+    stmt: LiteralString | string.templatelib.Template,
     *,
-    args: None | type[P1] | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
-    resultset: None | type[R1] | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None
+    args: None | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
+    resultset: None | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None,
+    arg: None | type[P] = None,
+    result: None | type[R] = None,
 ) -> _SQL: ...
 ```
 
-The parameter `stmt` represents a SQL expression, either as a string (including an *f-string*) or a template (i.e. a *t-string*).
+The parameter `stmt` represents a SQL expression, either as a literal string or a template (i.e. a *t-string*).
 
 If the expression is a string, it can have PostgreSQL parameter placeholders such as `$1`, `$2` or `$3`:
 
 ```python
-f"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
+"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
 ```
 
 If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
@@ -106,11 +127,10 @@ If the expression is a *t-string*, it can have replacement fields that evaluate
 t"INSERT INTO table_name (col_1, col_2, col_3) VALUES ({1}, {2}, {3});"
 ```
 
-The parameters `args` and `resultset` take a series type `P` or `R`, which may be any of the following:
+The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`, each of which may be any of the following:
 
 * (required) simple type
 * optional simple type (`T | None`)
-* `tuple` of several (required or optional) simple types.
 
 Simple types include:
 
@@ -124,6 +144,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -131,11 +152,11 @@ Types are grouped together with `tuple`:
 tuple[bool, int, str | None]
 ```
 
-Passing a simple type directly (e.g. `type[T]`) is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`).
+The parameters `arg` and `result` take a single type `P` or `R`. Passing a simple type (e.g. `type[T]`) directly via `arg` and `result` is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`) via `args` and `resultset`.
 
 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        |
 | ----------------- | ------------------ |
@@ -152,13 +173,18 @@ 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
 

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.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-asyncpg_typed/__init__.py,sha256=6F8tV2H1ayXFptYmsXLEi3puqKT-U904qamONeCJXUA,36489
-asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-asyncpg_typed-0.1.0.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
-asyncpg_typed-0.1.0.dist-info/METADATA,sha256=ti6ld6HyUOodNUCmbNru0xiUu5mNHM_Z2TiDvQm4CNA,8429
-asyncpg_typed-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-asyncpg_typed-0.1.0.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
-asyncpg_typed-0.1.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-asyncpg_typed-0.1.0.dist-info/RECORD,,