asyncpg-typed 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

asyncpg_typed/__init__.py

@@ -4,9 +4,9 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2025, Levente Hunyadi"
+__copyright__ = "Copyright 2025-2026, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"
@@ -43,10 +43,18 @@ TargetType: TypeAlias = type[Any] | UnionType
 Connection: TypeAlias = asyncpg.Connection | asyncpg.pool.PoolConnectionProxy
 
 
+class CountMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a different number of parameters or columns than declared in Python."
+
+
 class TypeMismatchError(TypeError):
     "Raised when a prepared statement takes or returns a PostgreSQL type incompatible with the declared Python type."
 
 
+class NameMismatchError(TypeError):
+    "Raised when the name of a result-set column differs from what is declared in Python."
+
+
 class EnumMismatchError(TypeError):
     "Raised when a prepared statement takes or returns a PostgreSQL enum type whose permitted set of values differs from what is declared in Python."
 
@@ -333,15 +341,29 @@ class _TypeVerifier:
             if is_enum_type(data_type):
                 if pg_type.name not in ["bpchar", "varchar", "text"]:
                     raise TypeMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` instead of `char`, `varchar` or `text`")
+            elif pg_type.kind == "array" and get_origin(data_type) is list:
+                if not pg_type.name.endswith("[]"):
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` instead of array")
+
+                expected_types = _NAME_TO_TYPE.get(pg_type.name[:-2])
+                if expected_types is None:
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: unrecognized PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+                elif get_args(data_type)[0] not in expected_types:
+                    if len(expected_types) == 1:
+                        target = f"the Python type `{type_to_str(expected_types[0])}`"
+                    else:
+                        target = f"one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` whose elements convert to {target}")
             else:
                 expected_types = _NAME_TO_TYPE.get(pg_type.name)
                 if expected_types is None:
                     raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: unrecognized PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
                 elif data_type not in expected_types:
-                    raise TypeMismatchError(
-                        f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; "
-                        f"got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`, which converts to one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
-                    )
+                    if len(expected_types) == 1:
+                        target = f"the Python type `{type_to_str(expected_types[0])}`"
+                    else:
+                        target = f"one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
+                    raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` which converts to {target}")
         elif pg_type.kind == "composite":  # PostgreSQL composite types
             # user-defined composite types registered with `conn.set_type_codec()` typically using `format="tuple"`
             pass
@@ -356,7 +378,7 @@ class _TypeVerifier:
 
 
 @dataclass(frozen=True)
-class _SQLPlaceholder:
+class _Placeholder:
     ordinal: int
     data_type: TargetType
 
@@ -364,13 +386,33 @@ class _SQLPlaceholder:
         return f"{self.__class__.__name__}({self.ordinal}, {self.data_type!r})"
 
 
+class _ResultsetWrapper:
+    "Wraps result-set rows into a tuple or named tuple."
+
+    init: Callable[..., tuple[Any, ...]] | None
+    iterable: Callable[[Iterable[Any]], tuple[Any, ...]]
+
+    def __init__(self, init: Callable[..., tuple[Any, ...]] | None, iterable: Callable[[Iterable[Any]], tuple[Any, ...]]) -> None:
+        """
+        Initializes a result-set wrapper.
+
+        :param init: Initializer function that takes as many arguments as columns in the result-set.
+        :param iterable: Initializer function that takes an iterable over columns of a result-set row.
+        """
+
+        self.init = init
+        self.iterable = iterable
+
+
 class _SQLObject:
     """
     Associates input and output type information with a SQL statement.
     """
 
-    _parameter_data_types: tuple[_SQLPlaceholder, ...]
+    _parameter_data_types: tuple[_Placeholder, ...]
     _resultset_data_types: tuple[TargetType, ...]
+    _resultset_column_names: tuple[str, ...] | None
+    _resultset_wrapper: _ResultsetWrapper
     _parameter_cast: int
     _parameter_converters: tuple[Callable[[Any], Any], ...]
     _required: int
@@ -378,20 +420,35 @@ class _SQLObject:
     _resultset_converters: tuple[Callable[[Any], Any], ...]
 
     @property
-    def parameter_data_types(self) -> tuple[_SQLPlaceholder, ...]:
+    def parameter_data_types(self) -> tuple[_Placeholder, ...]:
+        "Expected inbound parameter data types."
+
         return self._parameter_data_types
 
     @property
     def resultset_data_types(self) -> tuple[TargetType, ...]:
+        "Expected column data types in the result-set."
+
         return self._resultset_data_types
 
+    @property
+    def resultset_column_names(self) -> tuple[str, ...] | None:
+        "Expected column names in the result-set."
+
+        return self._resultset_column_names
+
     def __init__(
         self,
-        input_data_types: tuple[TargetType, ...],
-        output_data_types: tuple[TargetType, ...],
+        *,
+        args: tuple[TargetType, ...],
+        resultset: tuple[TargetType, ...],
+        names: tuple[str, ...] | None,
+        wrapper: _ResultsetWrapper,
     ) -> 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)
+        self._parameter_data_types = tuple(_Placeholder(ordinal, get_required_type(arg)) for ordinal, arg in enumerate(args, start=1))
+        self._resultset_data_types = tuple(get_required_type(data_type) for data_type in resultset)
+        self._resultset_column_names = names
+        self._resultset_wrapper = wrapper
 
         # create a bit-field of types that require cast or serialization (1: apply conversion; 0: forward value as-is)
         parameter_cast = 0
@@ -403,7 +460,7 @@ class _SQLObject:
 
         # create a bit-field of required types (1: required; 0: optional)
         required = 0
-        for index, data_type in enumerate(output_data_types):
+        for index, data_type in enumerate(resultset):
             required |= (not is_optional_type(data_type)) << index
         self._required = required
 
@@ -528,6 +585,16 @@ class _SQLObject:
             case _:
                 self._raise_required_is_none(row)
 
+    def check_column(self, column: list[Any]) -> None:
+        """
+        Verifies if the declared type matches the actual value type of a single-column resultset.
+        """
+
+        if self._required:
+            for i, value in enumerate(column):
+                if value is None:
+                    raise NoneTypeError(f"expected: {self._resultset_data_types[0]} in row #{i}; got: NULL")
+
     def check_value(self, value: Any) -> None:
         """
         Verifies if the declared type matches the actual value type.
@@ -568,12 +635,95 @@ class _SQLObject:
         :returns: List of tuples with each tuple element having the configured Python target type.
         """
 
+        if not rows:
+            return []
+
+        init_wrapper = self._resultset_wrapper.init
+        iterable_wrapper = self._resultset_wrapper.iterable
         cast = self._resultset_cast
-        if cast:
-            converters = self._resultset_converters
-            return [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:
-            return [tuple(value for value in row) for row in rows]
+        if not cast:
+            return [iterable_wrapper(row.values()) for row in rows]
+
+        columns = len(rows[0])
+        match columns:
+            case 1:
+                converter = self._resultset_converters[0]
+                if init_wrapper is not None:
+                    return [init_wrapper(converter(value) if (value := row[0]) is not None else value) for row in rows]
+                else:
+                    return [(converter(value) if (value := row[0]) is not None else value,) for row in rows]
+            case 2:
+                conv_a, conv_b = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                        )
+                        for row in rows
+                    ]
+            case 3:
+                conv_a, conv_b, conv_c = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                cast_c = cast >> 2 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                        )
+                        for row in rows
+                    ]
+            case 4:
+                conv_a, conv_b, conv_c, conv_d = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                cast_c = cast >> 2 & 1
+                cast_d = cast >> 3 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                            conv_d(value) if (value := row[3]) is not None and cast_d else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                            conv_d(value) if (value := row[3]) is not None and cast_d else value,
+                        )
+                        for row in rows
+                    ]
+            case _:
+                converters = self._resultset_converters
+                return [iterable_wrapper((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(columns)) for row in rows]
 
     def convert_row(self, row: asyncpg.Record) -> tuple[Any, ...]:
         """
@@ -583,12 +733,29 @@ class _SQLObject:
         :returns: A tuple with each tuple element having the configured Python target type.
         """
 
+        wrapper = self._resultset_wrapper.iterable
         cast = self._resultset_cast
         if cast:
             converters = self._resultset_converters
-            return tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
+            columns = len(row)
+            return wrapper((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(columns))
         else:
-            return tuple(value for value in row)
+            return wrapper(row.values())
+
+    def convert_column(self, rows: list[asyncpg.Record]) -> list[Any]:
+        """
+        Converts a single column in the PostgreSQL result-set to its corresponding Python target type.
+
+        :param rows: List of rows returned by PostgreSQL.
+        :returns: List of values having the configured Python target type.
+        """
+
+        cast = self._resultset_cast
+        if cast:
+            converter = self._resultset_converters[0]
+            return [(converter(value) if (value := row[0]) is not None else value) for row in rows]
+        else:
+            return [row[0] for row in rows]
 
     def convert_value(self, value: Any) -> Any:
         """
@@ -625,7 +792,7 @@ if sys.version_info >= (3, 14):
         """
 
         _strings: tuple[str, ...]
-        _placeholders: tuple[_SQLPlaceholder, ...]
+        _placeholders: tuple[_Placeholder, ...]
 
         def __init__(
             self,
@@ -633,8 +800,10 @@ if sys.version_info >= (3, 14):
             *,
             args: tuple[TargetType, ...],
             resultset: tuple[TargetType, ...],
+            names: tuple[str, ...] | None,
+            wrapper: _ResultsetWrapper,
         ) -> None:
-            super().__init__(args, resultset)
+            super().__init__(args=args, resultset=resultset, names=names, wrapper=wrapper)
 
             for ip in template.interpolations:
                 if ip.conversion is not None:
@@ -648,7 +817,7 @@ if sys.version_info >= (3, 14):
 
             if len(self.parameter_data_types) > 0:
 
-                def _to_placeholder(ip: Interpolation) -> _SQLPlaceholder:
+                def _to_placeholder(ip: Interpolation) -> _Placeholder:
                     ordinal = int(ip.value)
                     if not (0 < ordinal <= len(self.parameter_data_types)):
                         raise IndexError(f"interpolation `{ip.expression}` is an ordinal out of range; expected: 0 < value <= {len(self.parameter_data_types)}")
@@ -683,8 +852,10 @@ class _SQLString(_SQLObject):
         *,
         args: tuple[TargetType, ...],
         resultset: tuple[TargetType, ...],
+        names: tuple[str, ...] | None,
+        wrapper: _ResultsetWrapper,
     ) -> None:
-        super().__init__(args, resultset)
+        super().__init__(args=args, resultset=resultset, names=names, wrapper=wrapper)
         self._sql = sql
 
     def query(self) -> str:
@@ -717,8 +888,22 @@ class _SQLImpl(_SQL):
         stmt = await connection.prepare(self._sql.query())
 
         verifier = _TypeVerifier(connection)
+
+        input_count = len(self._sql.parameter_data_types)
+        parameter_count = len(stmt.get_parameters())
+        if parameter_count != input_count:
+            raise CountMismatchError(f"expected: PostgreSQL query to take {input_count} parameter(s); got: {parameter_count}")
         for param, placeholder in zip(stmt.get_parameters(), self._sql.parameter_data_types, strict=True):
             await verifier.check_data_type(f"parameter ${placeholder.ordinal}", param, placeholder.data_type)
+
+        output_count = len(self._sql.resultset_data_types)
+        column_count = len(stmt.get_attributes())
+        if column_count != output_count:
+            raise CountMismatchError(f"expected: PostgreSQL query to return {output_count} column(s) in result-set; got: {column_count}")
+        if self._sql.resultset_column_names is not None:
+            for index, attr, name in zip(range(output_count), stmt.get_attributes(), self._sql.resultset_column_names, strict=True):
+                if attr.name != name:
+                    raise NameMismatchError(f"expected: Python field name `{name}` to match PostgreSQL result-set column name `{attr.name}` for index #{index}")
         for attr, data_type in zip(stmt.get_attributes(), self._sql.resultset_data_types, strict=True):
             await verifier.check_data_type(f"column `{attr.name}`", attr.type, data_type)
 
@@ -755,6 +940,13 @@ class _SQLImpl(_SQL):
         self._sql.check_row(resultset)
         return resultset
 
+    async def fetchcol(self, connection: asyncpg.Connection, *args: Any) -> list[Any]:
+        stmt = await self._prepare(connection)
+        rows = await stmt.fetch(*self._sql.convert_arg_list(args))
+        column = self._sql.convert_column(rows)
+        self._sql.check_column(column)
+        return column
+
     async def fetchval(self, connection: asyncpg.Connection, *args: Any) -> Any:
         stmt = await self._prepare(connection)
         value = await stmt.fetchval(*self._sql.convert_arg_list(args))
@@ -784,6 +976,8 @@ class SQL_R1_P0(SQL_P0, Protocol[R1]):
     @abstractmethod
     async def fetchrow(self, connection: Connection) -> tuple[R1] | None: ...
     @abstractmethod
+    async def fetchcol(self, connection: Connection) -> list[R1]: ...
+    @abstractmethod
     async def fetchval(self, connection: Connection) -> R1: ...
 
 
@@ -809,6 +1003,8 @@ class SQL_R1_PX(SQL_PX[Unpack[PX]], Protocol[R1, Unpack[PX]]):
     @abstractmethod
     async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> tuple[R1] | None: ...
     @abstractmethod
+    async def fetchcol(self, connection: Connection, *args: Unpack[PX]) -> list[R1]: ...
+    @abstractmethod
     async def fetchval(self, connection: Connection, *args: Unpack[PX]) -> R1: ...
 
 
@@ -823,6 +1019,8 @@ class SQL_RX_PX(SQL_PX[Unpack[PX]], Protocol[RT, Unpack[PX]]):
 
 ### END OF AUTO-GENERATED BLOCK FOR Protocol ###
 
+RS = TypeVar("RS", bound=tuple[Any, ...])
+
 
 class SQLFactory:
     """
@@ -835,25 +1033,19 @@ class SQLFactory:
     @overload
     def sql(self, stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
     @overload
-    def sql(self, stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
-    @overload
-    def sql(self, stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
+    def sql(self, stmt: SQLExpression, *, resultset: type[RS]) -> SQL_RX_P0[RS]: ...
     @overload
     def sql(self, stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
     @overload
     def sql(self, stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
     @overload
-    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
-    @overload
-    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[RS]) -> SQL_RX_PX[RS, P1]: ...
     @overload
     def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
     @overload
     def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
     @overload
-    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-    @overload
-    def sql(self, 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]]: ...
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[RS]) -> SQL_RX_PX[RS, P1, Unpack[PX]]: ...
 
     ### END OF AUTO-GENERATED BLOCK FOR sql ###
 
@@ -868,17 +1060,17 @@ class SQLFactory:
         :param result: Type signature for a single result column (e.g. `UUID`).
         """
 
-        input_data_types, output_data_types = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+        input_data_types, output_data_types, names, wrapper = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
 
         obj: _SQLObject
         if sys.version_info >= (3, 14):
             match stmt:
                 case Template():
-                    obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types)
+                    obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
                 case str():
-                    obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+                    obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
         else:
-            obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+            obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
 
         return _SQLImpl(obj)
 
@@ -888,25 +1080,19 @@ class SQLFactory:
     @overload
     def unsafe_sql(self, stmt: str, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
     @overload
-    def unsafe_sql(self, stmt: str, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
-    @overload
-    def unsafe_sql(self, stmt: str, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
+    def unsafe_sql(self, stmt: str, *, resultset: type[RS]) -> SQL_RX_P0[RS]: ...
     @overload
     def unsafe_sql(self, stmt: str, *, arg: type[P1]) -> SQL_PX[P1]: ...
     @overload
     def unsafe_sql(self, stmt: str, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
     @overload
-    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
-    @overload
-    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[RS]) -> SQL_RX_PX[RS, P1]: ...
     @overload
     def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
     @overload
     def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
     @overload
-    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-    @overload
-    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[RS]) -> SQL_RX_PX[RS, P1, Unpack[PX]]: ...
 
     ### END OF AUTO-GENERATED BLOCK FOR unsafe_sql ###
 
@@ -924,12 +1110,14 @@ class SQLFactory:
         :param result: Type signature for a single result column (e.g. `UUID`).
         """
 
-        input_data_types, output_data_types = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
-        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+        input_data_types, output_data_types, names, wrapper = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
         return _SQLImpl(obj)
 
 
-def _sql_args_resultset(*, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None) -> tuple[tuple[Any, ...], tuple[Any, ...]]:
+def _sql_args_resultset(
+    *, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None
+) -> tuple[tuple[Any, ...], tuple[Any, ...], tuple[str, ...] | None, _ResultsetWrapper]:
     "Parses an argument/resultset signature into input/output types."
 
     if args is not None and arg is not None:
@@ -938,24 +1126,41 @@ def _sql_args_resultset(*, args: type[Any] | None = None, resultset: type[Any] |
         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)
+        if hasattr(args, "_asdict") and hasattr(args, "_fields"):
+            # named tuple
+            input_data_types = tuple(tp for tp in args.__annotations__.values())
+        else:
+            # regular tuple
+            if get_origin(args) is not tuple:
+                raise TypeError(f"expected: `type[tuple[T, ...]]` for `args`; got: {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,)
+        if hasattr(resultset, "_asdict") and hasattr(resultset, "_fields") and hasattr(resultset, "_make"):
+            # named tuple
+            output_data_types = tuple(tp for tp in resultset.__annotations__.values())
+            names = tuple(f for f in resultset._fields)
+            wrapper = _ResultsetWrapper(resultset, resultset._make)
+        else:
+            # regular tuple
+            if get_origin(resultset) is not tuple:
+                raise TypeError(f"expected: `type[tuple[T, ...]]` for `resultset`; got: {resultset}")
+            output_data_types = get_args(resultset)
+            names = None
+            wrapper = _ResultsetWrapper(None, tuple)
     else:
-        output_data_types = ()
+        if result is not None:
+            output_data_types = (result,)
+        else:
+            output_data_types = ()
+        names = None
+        wrapper = _ResultsetWrapper(None, tuple)
 
-    return input_data_types, output_data_types
+    return input_data_types, output_data_types, names, wrapper
 
 
 FACTORY: SQLFactory = SQLFactory()

{asyncpg_typed-0.1.3.dist-info → asyncpg_typed-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.3
+Version: 0.1.4
 Summary: Type-safe queries for asyncpg
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -45,6 +45,8 @@ This Python library provides "compile-time" validation for SQL queries that lint
 
 ## Motivating example
 
+### Using a plain tuple
+
 ```python
 # create a typed object, setting expected and returned types
 select_where_sql = sql(
@@ -66,7 +68,7 @@ try:
     # ✅ Type of "rows" is "list[tuple[bool, int, str | None]]"
     reveal_type(rows)
 
-    # ⚠️ Argument missing for parameter "arg2"
+    # ⚠️ Expected 1 more positional argument
     rows = await select_where_sql.fetch(conn, False)
 
     # ⚠️ Argument of type "float" cannot be assigned to parameter "arg2" of type "int" in function "fetch"; "float" is not assignable to "int"
@@ -74,27 +76,52 @@ try:
 
 finally:
     await conn.close()
+```
 
-# create a list of data-class instances from a list of typed tuples
-@dataclass
-class DataObject:
+### Using a named tuple
+
+```python
+# capture resultset column names and data types as fields of a named tuple
+class Resultset(NamedTuple):
     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
+# create a typed object, declaring return types with the named tuple
+select_sql = sql(
+    """--sql
+    SELECT boolean_value, integer_value, string_value
+    FROM sample_data
+    ORDER BY integer_value;
+    """,
+    resultset=Resultset,
+)
 
-# ⚠️ 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]
-```
+conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
+try:
+    rows = await select_sql.fetch(conn)
+
+    # ✅ Type of "rows" is "list[Resultset]"
+    reveal_type(rows)
+
+    for row in rows:
+        # use dot notation to access properties
+        if row.string_value is not None:
+            print(f"#{row.integer_value}: {row.string_value}")
+
+        # ✅ Type of "row.boolean_value" is "bool"
+        reveal_type(row.boolean_value)
 
+        # unpack named tuple
+        b, i, s = row
+
+        # ✅ Type of "s" is "str | None"
+        reveal_type(s)
+
+finally:
+    await conn.close()
+```
 
 ## Syntax
 
@@ -284,10 +311,12 @@ Only those functions are prompted on code completion that make sense in the cont
 
 #### Run-time behavior
 
-When a call such as `sql.executemany(conn, records)` or `sql.fetch(conn, param1, param2)` is made on a `SQL` object at run time, the library invokes `connection.prepare(sql)` to create a `PreparedStatement` and compares the actual statement signature against the expected Python types. If the expected and actual signatures don't match, an exception `TypeMismatchError` (subclass of `TypeError`) is raised.
+When a call such as `sql.executemany(conn, records)` or `sql.fetch(conn, param1, param2)` is made on a `SQL` object at run time, the library invokes `connection.prepare(sql)` to create a `PreparedStatement` and compares the actual statement signature against the expected Python types. If the expected and actual signatures don't match, a `TypeMismatchError` exception is raised.
+
+If the resultset type has been declared with a subclass of `NamedTuple`, the field names of the tuple are compared against the column names of the PostgreSQL resultset. Should there be a mismatch, a `NameMismatchError` is raised. Field and column order is relevant.
 
-The set of values for an enumeration type is validated when a prepared statement is created. The string values declared in a Python `StrEnum` are compared against the values listed in PostgreSQL `CREATE TYPE ... AS ENUM` by querying the system table `pg_enum`. If there are missing or extra values on either side, an exception `EnumMismatchError` (subclass of `TypeError`) is raised.
+The set of values for an enumeration type is validated when a prepared statement is created. The string values declared in a Python `StrEnum` are compared against the values listed in PostgreSQL `CREATE TYPE ... AS ENUM` by querying the system table `pg_enum`. If there are missing or extra values on either side, an `EnumMismatchError` exception is raised.
 
-Unfortunately, PostgreSQL doesn't propagate nullability via prepared statements: resultset types that are declared as required (e.g. `T` as opposed to `T | None`) are validated at run time. When a `None` value is encountered for a required type, an exception `NoneTypeError` (subclass of `TypeError`) is raised.
+Unfortunately, PostgreSQL doesn't propagate nullability via prepared statements: resultset types that are declared as required (e.g. `T` as opposed to `T | None`) have to be validated at run time. When a `None` value is encountered for a required type, a `NoneTypeError` exception is raised.
 
 PostgreSQL doesn't differentiate between IPv4 and IPv6 network definitions, or IPv4 and IPv6 addresses in the types `cidr` and `inet`. This means that semantically a union type is returned. If you specify a more restrictive type, the resultset data is validated dynamically at run time.

asyncpg_typed-0.1.4.dist-info/RECORD

@@ -0,0 +1,8 @@
+asyncpg_typed/__init__.py,sha256=gGyWS0ChY1PcCDpSiyycqjE5xDrPcOCH8BjeMzBPlLc,48610
+asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asyncpg_typed-0.1.4.dist-info/licenses/LICENSE,sha256=fsxatgMrv7G5R_IJYOb7FqBNbXIvLidWG9blKAir8k8,1098
+asyncpg_typed-0.1.4.dist-info/METADATA,sha256=cTwlTJjzBFHz9FYH8Ozk3S_z4uVWA0ivnszY-8tZD6A,16126
+asyncpg_typed-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+asyncpg_typed-0.1.4.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
+asyncpg_typed-0.1.4.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+asyncpg_typed-0.1.4.dist-info/RECORD,,

{asyncpg_typed-0.1.3.dist-info → asyncpg_typed-0.1.4.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Levente Hunyadi
+Copyright (c) 2025-2026 Levente Hunyadi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

asyncpg_typed-0.1.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-asyncpg_typed/__init__.py,sha256=pDwWTWeNqXtw0Z0YrHRu_kneHu20X2SggFWK6aczbY8,38766
-asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-asyncpg_typed-0.1.3.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
-asyncpg_typed-0.1.3.dist-info/METADATA,sha256=LTGsagnYy0YHn33DUpIEfkRh63mNyH1rdRxCnpyTNZk,15353
-asyncpg_typed-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-asyncpg_typed-0.1.3.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
-asyncpg_typed-0.1.3.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-asyncpg_typed-0.1.3.dist-info/RECORD,,