asyncpg-typed 0.1.0__py3-none-any.whl

asyncpg_typed/__init__.py

@@ -0,0 +1,827 @@
+"""
+Type-safe queries for asyncpg.
+
+:see: https://github.com/hunyadi/asyncpg_typed
+"""
+
+__version__ = "0.1.0"
+__author__ = "Levente Hunyadi"
+__copyright__ = "Copyright 2025, Levente Hunyadi"
+__license__ = "MIT"
+__maintainer__ = "Levente Hunyadi"
+__status__ = "Production"
+
+import sys
+import typing
+from abc import abstractmethod
+from collections.abc import Iterable, Sequence
+from datetime import date, datetime, time
+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 uuid import UUID
+
+import asyncpg
+from asyncpg.prepared_stmt import PreparedStatement
+
+if sys.version_info < (3, 11):
+    from typing_extensions import TypeVarTuple, Unpack
+else:
+    from typing import TypeVarTuple, Unpack
+
+# list of supported data types
+DATA_TYPES: list[type[Any]] = [bool, int, float, Decimal, date, time, datetime, str, bytes, UUID]
+
+# maximum number of inbound query parameters
+NUM_ARGS = 8
+
+
+def is_union_type(tp: Any) -> bool:
+    """
+    Returns `True` if `tp` is a union type such as `A | B` or `Union[A, B]`.
+    """
+
+    origin = get_origin(tp)
+    return origin is Union or origin is UnionType
+
+
+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]`.
+    """
+
+    return is_union_type(tp) and any(a is type(None) for a in get_args(tp))
+
+
+def is_standard_type(tp: Any) -> bool:
+    """
+    Returns `True` if the type represents a built-in or a well-known standard type.
+    """
+
+    return tp.__module__ == "builtins" or tp.__module__ == UnionType.__module__
+
+
+def make_union_type(tpl: list[Any]) -> UnionType:
+    """
+    Creates a `UnionType` (a.k.a. `A | B | C`) dynamically at run time.
+    """
+
+    if len(tpl) < 2:
+        raise ValueError("expected: at least two types to make a `UnionType`")
+
+    return reduce(lambda a, b: a | b, tpl)
+
+
+def get_required_type(tp: Any) -> Any:
+    """
+    Removes `None` from an optional type (i.e. a union type that has `None` as a member).
+    """
+
+    if not is_optional_type(tp):
+        return tp
+
+    tpl = [a for a in get_args(tp) if a is not type(None)]
+    if len(tpl) > 1:
+        return make_union_type(tpl)
+    elif len(tpl) > 0:
+        return tpl[0]
+    else:
+        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,
+}
+
+
+def check_data_type(name: str, data_type: type[Any]) -> 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 expected_type is not None:
+        return expected_type == required_type
+    if is_standard_type(required_type):
+        return False
+
+    # user-defined type registered with `conn.set_type_codec()`
+    return True
+
+
+class _SQLPlaceholder:
+    ordinal: int
+    data_type: type[Any]
+
+    def __init__(self, ordinal: int, data_type: type[Any]) -> None:
+        self.ordinal = ordinal
+        self.data_type = data_type
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.ordinal}, {self.data_type!r})"
+
+
+class _SQLObject:
+    """
+    Associates input and output type information with a SQL statement.
+    """
+
+    parameter_data_types: tuple[_SQLPlaceholder, ...]
+    resultset_data_types: tuple[type[Any], ...]
+    required: int
+
+    def __init__(
+        self,
+        *,
+        args: type[Any] | None = None,
+        resultset: type[Any] | None = None,
+    ) -> 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 = ()
+
+        # create a bit-field of required types (1: required; 0: optional)
+        required = 0
+        for index, data_type in enumerate(self.resultset_data_types):
+            required |= (not is_optional_type(data_type)) << index
+        self.required = required
+
+    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`.
+        """
+
+        for col_index in range(len(row)):
+            if (self.required >> col_index & 1) and row[col_index] is None:
+                if row_index is not None:
+                    row_col_spec = f"row #{row_index} and column #{col_index}"
+                else:
+                    row_col_spec = f"column #{col_index}"
+                raise TypeError(f"expected: {self.resultset_data_types[col_index]} in {row_col_spec}; got: NULL")
+
+    def check_rows(self, rows: list[tuple[Any, ...]]) -> None:
+        """
+        Verifies if declared types match actual value types in a resultset.
+        """
+
+        if not rows:
+            return
+
+        required = self.required
+        if not required:
+            return
+
+        match len(rows[0]):
+            case 1:
+                for r, row in enumerate(rows):
+                    if required & (row[0] is None):
+                        self._raise_required_is_none(row, r)
+            case 2:
+                for r, row in enumerate(rows):
+                    a, b = row
+                    if required & ((a is None) | (b is None) << 1):
+                        self._raise_required_is_none(row, r)
+            case 3:
+                for r, row in enumerate(rows):
+                    a, b, c = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2):
+                        self._raise_required_is_none(row, r)
+            case 4:
+                for r, row in enumerate(rows):
+                    a, b, c, d = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3):
+                        self._raise_required_is_none(row, r)
+            case 5:
+                for r, row in enumerate(rows):
+                    a, b, c, d, e = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4):
+                        self._raise_required_is_none(row, r)
+            case 6:
+                for r, row in enumerate(rows):
+                    a, b, c, d, e, f = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5):
+                        self._raise_required_is_none(row, r)
+            case 7:
+                for r, row in enumerate(rows):
+                    a, b, c, d, e, f, g = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5 | (g is None) << 6):
+                        self._raise_required_is_none(row, r)
+            case 8:
+                for r, row in enumerate(rows):
+                    a, b, c, d, e, f, g, h = row
+                    if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5 | (g is None) << 6 | (h is None) << 7):
+                        self._raise_required_is_none(row, r)
+            case _:
+                for r, row in enumerate(rows):
+                    self._raise_required_is_none(row, r)
+
+    def check_row(self, row: tuple[Any, ...]) -> None:
+        """
+        Verifies if declared types match actual value types in a single row.
+        """
+
+        required = self.required
+        if not required:
+            return
+
+        match len(row):
+            case 1:
+                if required & (row[0] is None):
+                    self._raise_required_is_none(row)
+            case 2:
+                a, b = row
+                if required & ((a is None) | (b is None) << 1):
+                    self._raise_required_is_none(row)
+            case 3:
+                a, b, c = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2):
+                    self._raise_required_is_none(row)
+            case 4:
+                a, b, c, d = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3):
+                    self._raise_required_is_none(row)
+            case 5:
+                a, b, c, d, e = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4):
+                    self._raise_required_is_none(row)
+            case 6:
+                a, b, c, d, e, f = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5):
+                    self._raise_required_is_none(row)
+            case 7:
+                a, b, c, d, e, f, g = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5 | (g is None) << 6):
+                    self._raise_required_is_none(row)
+            case 8:
+                a, b, c, d, e, f, g, h = row
+                if required & ((a is None) | (b is None) << 1 | (c is None) << 2 | (d is None) << 3 | (e is None) << 4 | (f is None) << 5 | (g is None) << 6 | (h is None) << 7):
+                    self._raise_required_is_none(row)
+            case _:
+                self._raise_required_is_none(row)
+
+    def check_value(self, value: Any) -> None:
+        """
+        Verifies if the declared type matches the actual value type.
+        """
+
+        if self.required and value is None:
+            raise TypeError(f"expected: {self.resultset_data_types[0]}; got: NULL")
+
+    @abstractmethod
+    def query(self) -> str:
+        """
+        Returns a SQL query string with PostgreSQL ordinal placeholders.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.query()!r})"
+
+    def __str__(self) -> str:
+        return self.query()
+
+
+if sys.version_info >= (3, 14):
+    from string.templatelib import Interpolation, Template  # type: ignore[import-not-found]
+
+    SQLExpression: TypeAlias = Template | str
+
+    class _SQLTemplate(_SQLObject):
+        """
+        A SQL query specified with the Python t-string syntax.
+        """
+
+        strings: tuple[str, ...]
+        placeholders: tuple[_SQLPlaceholder, ...]
+
+        def __init__(
+            self,
+            template: Template,
+            *,
+            args: type[Any] | None = None,
+            resultset: type[Any] | None = None,
+        ) -> None:
+            super().__init__(args=args, resultset=resultset)
+
+            for ip in template.interpolations:
+                if ip.conversion is not None:
+                    raise TypeError(f"interpolation `{ip.expression}` expected to apply no conversion")
+                if ip.format_spec:
+                    raise TypeError(f"interpolation `{ip.expression}` expected to apply no format spec")
+                if not isinstance(ip.value, int):
+                    raise TypeError(f"interpolation `{ip.expression}` expected to evaluate to an integer")
+
+            self.strings = template.strings
+
+            if args is not None:
+
+                def _to_placeholder(ip: Interpolation) -> _SQLPlaceholder:
+                    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)}")
+                    return self.parameter_data_types[int(ip.value) - 1]
+
+                self.placeholders = tuple(_to_placeholder(ip) for ip in template.interpolations)
+            else:
+                self.placeholders = ()
+
+        def query(self) -> str:
+            buf = StringIO()
+            for s, p in zip(self.strings[:-1], self.placeholders, strict=True):
+                buf.write(s)
+                buf.write(f"${p.ordinal}")
+            buf.write(self.strings[-1])
+            return buf.getvalue()
+
+else:
+    SQLExpression = str
+
+
+class _SQLString(_SQLObject):
+    """
+    A SQL query specified as a plain string (e.g. f-string).
+    """
+
+    sql: str
+
+    def __init__(
+        self,
+        sql: str,
+        *,
+        args: type[Any] | None = None,
+        resultset: type[Any] | None = None,
+    ) -> None:
+        super().__init__(args=args, resultset=resultset)
+        self.sql = sql
+
+    def query(self) -> str:
+        return self.sql
+
+
+class _SQL:
+    """
+    Represents a SQL statement with associated type information.
+    """
+
+
+Connection: TypeAlias = asyncpg.Connection | asyncpg.pool.PoolConnectionProxy
+
+
+class _SQLImpl(_SQL):
+    """
+    Forwards input data to an `asyncpg.PreparedStatement`, and validates output data (if necessary).
+    """
+
+    sql: _SQLObject
+
+    def __init__(self, sql: _SQLObject) -> None:
+        self.sql = sql
+
+    def __str__(self) -> str:
+        return str(self.sql)
+
+    def __repr__(self) -> str:
+        return repr(self.sql)
+
+    async def _prepare(self, connection: Connection) -> PreparedStatement:
+        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):
+                raise TypeError(f"expected: {data_type} in column `{attr.name}`; got: `{attr.type.kind}` of `{attr.type.name}`")
+
+        return stmt
+
+    async def execute(self, connection: asyncpg.Connection, *args: Any) -> None:
+        await connection.execute(self.sql.query(), *args)
+
+    async def executemany(self, connection: asyncpg.Connection, args: Iterable[Sequence[Any]]) -> None:
+        stmt = await self._prepare(connection)
+        await stmt.executemany(args)
+
+    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
+
+    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
+
+    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)
+        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
+
+
+### 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)
+R1 = TypeVar("R1")
+R2 = TypeVar("R2")
+RX = TypeVarTuple("RX")
+
+
+class SQL_P0(_SQL):
+    @abstractmethod
+    async def execute(self, connection: Connection) -> None: ...
+
+
+class SQL_P0_RS(Generic[R1], SQL_P0):
+    @abstractmethod
+    async def fetch(self, connection: Connection) -> list[tuple[R1]]: ...
+    @abstractmethod
+    async def fetchrow(self, connection: Connection) -> tuple[R1] | None: ...
+    @abstractmethod
+    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]]]: ...
+    @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: ...
+
+
+@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]: ...
+@overload
+def sql(stmt: SQLExpression, *, args: 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]], resultset: 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]], resultset: 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]], 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]]: ...
+
+
+### END OF AUTO-GENERATED BLOCK ###
+
+
+def sql(
+    stmt: SQLExpression,
+    *,
+    args: type[Any] | None = None,
+    resultset: 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.
+    """
+
+    if sys.version_info >= (3, 14):
+        obj: _SQLObject
+        match stmt:
+            case Template():
+                obj = _SQLTemplate(stmt, args=args, resultset=resultset)
+            case str():
+                obj = _SQLString(stmt, args=args, resultset=resultset)
+    else:
+        obj = _SQLString(stmt, args=args, resultset=resultset)
+
+    return _SQLImpl(obj)

asyncpg_typed-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: asyncpg_typed
+Version: 0.1.0
+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
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.31
+Requires-Dist: typing-extensions>=4.15; python_version < "3.11"
+Provides-Extra: vector
+Requires-Dist: asyncpg-vector>=0.1; extra == "vector"
+Provides-Extra: dev
+Requires-Dist: asyncpg-stubs>=0.31; extra == "dev"
+Requires-Dist: build>=1.3; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Dynamic: license-file
+
+# Type-safe queries for asyncpg
+
+[asyncpg](https://magicstack.github.io/asyncpg/current/) is a high-performance database client to connect to a PostgreSQL server, and execute SQL statements using the async/await paradigm in Python. The library exposes a `Connection` object, which has methods like `execute` and `fetch` that run SQL queries against the database. Unfortunately, these methods take the query as a plain `str`, arguments as `object`, and the resultset is exposed as a `Record`, which is a `tuple`/`dict` hybrid whose `get` and indexer have a return type of `Any`. There is no mechanism to check compatibility of input or output arguments, even if their types are preliminarily known.
+
+This Python library provides "compile-time" validation for SQL queries that linters and type checkers can enforce. By creating a generic `SQL` object and associating input and output type information with the query, the signatures of `execute` and `fetch` reveal the exact expected and returned types.
+
+
+## Motivating example
+
+```python
+# create a typed object, setting expected and returned types
+select_where_sql = sql(
+    """--sql
+    SELECT boolean_value, integer_value, string_value
+    FROM sample_data
+    WHERE boolean_value = $1 AND integer_value > $2
+    ORDER BY integer_value;
+    """,
+    args=tuple[bool, int],
+    resultset=tuple[bool, int, str | None],
+)
+
+conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
+try:
+    # ✅ Valid signature
+    rows = await select_where_sql.fetch(conn, False, 2)
+
+    # ✅ Type of "rows" is "list[tuple[bool, int, str | None]]"
+    reveal_type(rows)
+
+    # ⚠️ Argument missing for parameter "arg2"
+    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"
+    rows = await select_where_sql.fetch(conn, False, 3.14)
+
+finally:
+    await conn.close()
+```
+
+
+## Syntax
+
+### Creating a SQL object
+
+Instantiate a SQL object with the `sql` function:
+
+```python
+def sql(
+    stmt: str | 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
+) -> _SQL: ...
+```
+
+The parameter `stmt` represents a SQL expression, either as a string (including an *f-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);"
+```
+
+If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
+
+```python
+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:
+
+* (required) simple type
+* optional simple type (`T | None`)
+* `tuple` of several (required or optional) simple types.
+
+Simple types include:
+
+* `bool`
+* `int`
+* `float`
+* `decimal.Decimal`
+* `datetime.date`
+* `datetime.time`
+* `datetime.datetime`
+* `str`
+* `bytes`
+* `uuid.UUID`
+
+Types are grouped together with `tuple`:
+
+```python
+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 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.
+
+| PostgreSQL type   | Python type        |
+| ----------------- | ------------------ |
+| `bool`            | `bool`             |
+| `smallint`        | `int`              |
+| `integer`         | `int`              |
+| `bigint`          | `int`              |
+| `real`/`float4`   | `float`            |
+| `double`/`float8` | `float`            |
+| `decimal`         | `Decimal`          |
+| `numeric`         | `Decimal`          |
+| `date`            | `date`             |
+| `time`            | `time` (naive)     |
+| `timetz`          | `time` (tz)        |
+| `timestamp`       | `datetime` (naive) |
+| `timestamptz`     | `datetime` (tz)    |
+| `char(N)`         | `str`              |
+| `varchar(N)`      | `str`              |
+| `text`            | `str`              |
+| `bytea`           | `bytes`            |
+| `json`            | `str`              |
+| `jsonb`           | `str`              |
+| `uuid`            | `UUID`             |
+
+### 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`.
+
+The following functions are available on SQL objects:
+
+```python
+async def execute(self, connection: Connection, *args: *P) -> None: ...
+async def executemany(self, connection: Connection, args: Iterable[tuple[*P]]) -> None: ...
+async def fetch(self, connection: Connection, *args: *P) -> list[tuple[*R]]: ...
+async def fetchmany(self, connection: Connection, args: Iterable[tuple[*P]]) -> list[tuple[*R]]: ...
+async def fetchrow(self, connection: Connection, *args: *P) -> tuple[*R] | None: ...
+async def fetchval(self, connection: Connection, *args: *P) -> R1: ...
+```
+
+`Connection` may be an `asyncpg.Connection` or an `asyncpg.pool.PoolConnectionProxy` acquired from a connection pool.
+
+`*P` and `*R` denote several types (a type pack) corresponding to those listed in `args` and `resultset`, respectively.
+
+Only those functions are prompted on code completion that make sense in the context of the given number of input and output arguments. Specifically, `fetchval` is available only for a single type passed to `resultset`, and `executemany` and `fetchmany` are available only if the query takes (one or more) parameters.
+
+
+## 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. 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.

asyncpg_typed-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+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,,

asyncpg_typed-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

asyncpg_typed-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asyncpg_typed-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+asyncpg_typed

asyncpg_typed-0.1.0.dist-info/zip-safe

@@ -0,0 +1 @@
+