asyncpg-typed 0.1.0__tar.gz → 0.1.1__tar.gz

asyncpg_typed-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -85,19 +85,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 +108,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 +125,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -131,7 +133,7 @@ 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.
 
@@ -159,6 +161,7 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `json`            | `str`              |
 | `jsonb`           | `str`              |
 | `uuid`            | `UUID`             |
+| enumeration       | `E: StrEnum`       |
 
 ### Using a SQL object
 

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.1}/README.md

@@ -47,19 +47,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:
@@ -68,11 +70,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:
 
@@ -86,6 +87,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -93,7 +95,7 @@ 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.
 
@@ -121,6 +123,7 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `json`            | `str`              |
 | `jsonb`           | `str`              |
 | `uuid`            | `UUID`             |
+| enumeration       | `E: StrEnum`       |
 
 ### Using a SQL object
 

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.1}/asyncpg_typed/__init__.py

@@ -4,15 +4,15 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __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
@@ -27,9 +27,9 @@ 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]
@@ -38,9 +38,29 @@ DATA_TYPES: list[type[Any]] = [bool, int, float, Decimal, date, time, datetime,
 NUM_ARGS = 8
 
 
+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,7 +77,7 @@ 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__
@@ -115,21 +135,20 @@ _name_to_type: dict[str, Any] = {
 }
 
 
-def check_data_type(name: str, data_type: type[Any]) -> bool:
+def check_data_type(schema: str, 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
+    if schema == "pg_catalog":
+        expected_type = _name_to_type.get(name)
+        return expected_type == data_type
+    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:
@@ -152,35 +171,28 @@ class _SQLObject:
     parameter_data_types: tuple[_SQLPlaceholder, ...]
     resultset_data_types: tuple[type[Any], ...]
     required: int
+    cast: int
 
     def __init__(
         self,
-        *,
-        args: type[Any] | None = None,
-        resultset: type[Any] | None = None,
+        input_data_types: tuple[type[Any], ...],
+        output_data_types: tuple[type[Any], ...],
     ) -> 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/conversion (1: pass to __init__; 0: skip)
+        cast = 0
+        for index, data_type in enumerate(self.resultset_data_types):
+            cast |= is_enum_type(data_type) << index
+        self.cast = cast
+
     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 +331,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 +345,10 @@ if sys.version_info >= (3, 14):
             self,
             template: Template,
             *,
-            args: type[Any] | None = None,
-            resultset: type[Any] | None = None,
+            args: tuple[type[Any], ...],
+            resultset: tuple[type[Any], ...],
         ) -> None:
-            super().__init__(args=args, resultset=resultset)
+            super().__init__(args, resultset)
 
             for ip in template.interpolations:
                 if ip.conversion is not None:
@@ -348,7 +360,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 +381,7 @@ if sys.version_info >= (3, 14):
             return buf.getvalue()
 
 else:
-    SQLExpression = str
+    SQLExpression = LiteralString
 
 
 class _SQLString(_SQLObject):
@@ -383,10 +395,10 @@ class _SQLString(_SQLObject):
         self,
         sql: str,
         *,
-        args: type[Any] | None = None,
-        resultset: type[Any] | None = None,
+        args: tuple[type[Any], ...],
+        resultset: tuple[type[Any], ...],
     ) -> None:
-        super().__init__(args=args, resultset=resultset)
+        super().__init__(args, resultset)
         self.sql = sql
 
     def query(self) -> str:
@@ -422,7 +434,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,40 +446,51 @@ 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:
+            data_types = self.sql.resultset_data_types
+            resultset = [tuple((data_types[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
+        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:
+            data_types = self.sql.resultset_data_types
+            resultset = tuple((data_types[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
+        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.resultset_data_types[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)
+PS = TypeVar("PS")
 P1 = TypeVar("P1")
 P2 = TypeVar("P2")
 P3 = TypeVar("P3")
@@ -476,7 +499,7 @@ 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)
+RS = TypeVar("RS")
 R1 = TypeVar("R1")
 R2 = TypeVar("R2")
 RX = TypeVarTuple("RX")
@@ -722,27 +745,27 @@ class SQL_P8_RX(Generic[P1, P2, P3, P4, P5, P6, P7, P8, R1, R2, Unpack[RX]], SQL
 @overload
 def sql(stmt: SQLExpression) -> SQL_P0: ...
 @overload
-def sql(stmt: SQLExpression, *, resultset: type[RS]) -> SQL_P0_RS[RS]: ...
+def sql(stmt: SQLExpression, *, result: type[RS]) -> SQL_P0_RS[RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_P0_RS[R1]: ...
 @overload
 def sql(stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P0_RX[R1, R2, Unpack[RX]]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[PS]) -> SQL_P1[PS]: ...
+def sql(stmt: SQLExpression, *, arg: type[PS]) -> SQL_P1[PS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1]]) -> SQL_P1[P1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[PS], resultset: type[RS]) -> SQL_P1_RS[PS, RS]: ...
+def sql(stmt: SQLExpression, *, arg: type[PS], result: type[RS]) -> SQL_P1_RS[PS, RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1]], resultset: type[tuple[R1]]) -> SQL_P1_RS[P1, R1]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[PS], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[PS, R1, R2, Unpack[RX]]: ...
+def sql(stmt: SQLExpression, *, arg: type[PS], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[PS, R1, R2, Unpack[RX]]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_P1_RX[P1, R1, R2, Unpack[RX]]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]]) -> SQL_P2[P1, P2]: ...
 @overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[RS]) -> SQL_P2_RS[P1, P2, RS]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], result: type[RS]) -> SQL_P2_RS[P1, P2, RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[tuple[R1]]) -> SQL_P2_RS[P1, P2, R1]: ...
 @overload
@@ -750,7 +773,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2]], resultset: type[tuple
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], result: type[RS]) -> SQL_P3_RS[P1, P2, P3, RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], resultset: type[tuple[R1]]) -> SQL_P3_RS[P1, P2, P3, R1]: ...
 @overload
@@ -758,7 +781,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3]], resultset: type[t
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], result: type[RS]) -> SQL_P4_RS[P1, P2, P3, P4, RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], resultset: type[tuple[R1]]) -> SQL_P4_RS[P1, P2, P3, P4, R1]: ...
 @overload
@@ -766,7 +789,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4]], resultset: ty
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], result: type[RS]) -> SQL_P5_RS[P1, P2, P3, P4, P5, RS]: ...
 @overload
 def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], resultset: type[tuple[R1]]) -> SQL_P5_RS[P1, P2, P3, P4, P5, R1]: ...
 @overload
@@ -774,7 +797,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5]], resultset
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]], result: type[RS]) -> SQL_P6_RS[P1, P2, P3, P4, P5, P6, RS]: ...
 @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
@@ -782,7 +805,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6]], resul
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], result: type[RS]) -> SQL_P7_RS[P1, P2, P3, P4, P5, P6, P7, RS]: ...
 @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
@@ -790,7 +813,7 @@ def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7]], r
 @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]: ...
+def sql(stmt: SQLExpression, *, args: type[tuple[P1, P2, P3, P4, P5, P6, P7, P8]], result: type[RS]) -> SQL_P8_RS[P1, P2, P3, P4, P5, P6, P7, P8, RS]: ...
 @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
@@ -805,23 +828,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 → asyncpg_typed-0.1.1}/asyncpg_typed.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -85,19 +85,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 +108,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 +125,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -131,7 +133,7 @@ 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.
 
@@ -159,6 +161,7 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `json`            | `str`              |
 | `jsonb`           | `str`              |
 | `uuid`            | `UUID`             |
+| enumeration       | `E: StrEnum`       |
 
 ### Using a SQL object
 

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.1}/asyncpg_typed.egg-info/SOURCES.txt

@@ -1,4 +1,5 @@
 LICENSE
+MANIFEST.in
 README.md
 pyproject.toml
 asyncpg_typed/__init__.py
@@ -9,8 +10,10 @@ asyncpg_typed.egg-info/dependency_links.txt
 asyncpg_typed.egg-info/requires.txt
 asyncpg_typed.egg-info/top_level.txt
 asyncpg_typed.egg-info/zip-safe
-test/test_code.py
-test/test_data.py
-test/test_template.py
-test/test_type.py
-test/test_vector.py
+tests/__init__.py
+tests/connection.py
+tests/test_code.py
+tests/test_data.py
+tests/test_template.py
+tests/test_type.py
+tests/test_vector.py

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "asyncpg_typed"
 description = "Type-safe queries for asyncpg"
 readme = { file = "README.md", content-type = "text/markdown" }
-keywords = ["asyncpg", "typed", "database-client"]
+keywords = ["asyncpg", "typed", "database-client", "postgres"]
 license = "MIT"
 authors = [
     { name = "Levente Hunyadi", email = "hunyadi@gmail.com" }

asyncpg_typed-0.1.1/tests/connection.py

@@ -0,0 +1,19 @@
+"""
+Type-safe queries for asyncpg.
+
+:see: https://github.com/hunyadi/asyncpg_typed
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import asyncpg
+
+
+@asynccontextmanager
+async def get_connection() -> AsyncIterator[asyncpg.Connection]:
+    conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
+    try:
+        yield conn
+    finally:
+        await conn.close()

{asyncpg_typed-0.1.0/test → asyncpg_typed-0.1.1/tests}/test_code.py

@@ -10,7 +10,7 @@ from io import StringIO
 from pathlib import Path
 from typing import TextIO
 
-from asyncpg_typed import DATA_TYPES, NUM_ARGS
+from asyncpg_typed import NUM_ARGS
 
 
 def _args_and_results(p: int, r: int, s: bool = False) -> str:
@@ -83,11 +83,11 @@ def _param_spec(p: int, r: int, s: bool = False) -> str:
     if (s and p > 1) or (not s and p > 0):
         params.append(f"args: type[tuple{_args(p)}]")
     elif s and p == 1:
-        params.append("args: type[PS]")
+        params.append("arg: type[PS]")
     if (s and r > 1) or (not s and r > 0):
         params.append(f"resultset: type[tuple{_results(r)}]")
     elif s and r == 1:
-        params.append("resultset: type[RS]")
+        params.append("result: type[RS]")
     if len(params) > 1:
         return f", {', '.join(params)}" if params else ""
     else:
@@ -109,13 +109,12 @@ def _write_function(out: TextIO, p: int, r: int, s: bool) -> None:
 
 
 def write_code(out: TextIO) -> None:
-    data_types_list = ", ".join(f"{data_type.__name__}, {data_type.__name__} | None" for data_type in DATA_TYPES)
-    print(f'PS = TypeVar("PS", {data_types_list})', file=out)
+    print('PS = TypeVar("PS")', file=out)
 
     for p in range(1, NUM_ARGS + 1):
         print(f'P{p} = TypeVar("P{p}")', file=out)
 
-    print(f'RS = TypeVar("RS", {data_types_list})', file=out)
+    print('RS = TypeVar("RS")', file=out)
     print('R1 = TypeVar("R1")', file=out)
     print('R2 = TypeVar("R2")', file=out)
     print('RX = TypeVarTuple("RX")', file=out)

{asyncpg_typed-0.1.0/test → asyncpg_typed-0.1.1/tests}/test_data.py

@@ -4,9 +4,9 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
+import enum
+import sys
 import unittest
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
 from datetime import date, datetime, time, timedelta, timezone
 from decimal import Decimal
 from random import randint, sample
@@ -14,29 +14,31 @@ from types import UnionType
 from typing import Any
 from uuid import UUID, uuid4
 
-import asyncpg
-
 from asyncpg_typed import sql
+from tests.connection import get_connection
 
 
 class RollbackException(RuntimeError):
     pass
 
 
-@asynccontextmanager
-async def get_connection() -> AsyncIterator[asyncpg.Connection]:
-    conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
-    try:
-        yield conn
-    finally:
-        await conn.close()
+if sys.version_info < (3, 11):
+
+    class State(str, enum.Enum):
+        ACTIVE = "active"
+        INACTIVE = "inactive"
+else:
+
+    class State(enum.StrEnum):
+        ACTIVE = "active"
+        INACTIVE = "inactive"
 
 
 class TestDataTypes(unittest.IsolatedAsyncioTestCase):
     async def test_numeric_types(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE numeric_types(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 boolean_value boolean NOT NULL,
@@ -80,7 +82,7 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
     async def test_datetime_types(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE datetime_types(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 date_value date NOT NULL,
@@ -127,7 +129,7 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
     async def test_sequence_types(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE sequence_types(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 bytes_value bytea NOT NULL,
@@ -167,7 +169,7 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
     async def test_composite_type(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE composite_types(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 uuid_value uuid NOT NULL,
@@ -204,10 +206,79 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
             await insert_sql.executemany(conn, [record1, record2])
             self.assertEqual(await select_sql.fetch(conn), [record1, record2])
 
+    async def test_enum_type(self) -> None:
+        create_sql = sql(
+            """
+            --sql
+            DO $$ BEGIN
+                CREATE TYPE state AS ENUM ('active', 'inactive');
+            EXCEPTION
+                WHEN duplicate_object THEN null;
+            END $$;
+
+            --sql
+            CREATE TEMPORARY TABLE enum_types(
+                id bigint GENERATED ALWAYS AS IDENTITY,
+                enum_value state NOT NULL,
+                CONSTRAINT pk_sample_data PRIMARY KEY (id)
+            );
+            """
+        )
+
+        insert_sql = sql(
+            """
+            --sql
+            INSERT INTO enum_types (enum_value)
+            VALUES ($1);
+            """,
+            arg=State,
+        )
+
+        select_sql = sql(
+            """
+            --sql
+            SELECT enum_value, enum_value
+            FROM enum_types
+            ORDER BY id;
+            """,
+            resultset=tuple[State, State | None],
+        )
+
+        value_sql = sql(
+            """
+            --sql
+            SELECT enum_value
+            FROM enum_types
+            ORDER BY id;
+            """,
+            result=State,
+        )
+
+        async with get_connection() as conn:
+            await create_sql.execute(conn)
+            await insert_sql.executemany(conn, [(State.ACTIVE,), (State.INACTIVE,)])
+
+            rows = await select_sql.fetch(conn)
+            for row in rows:
+                for column in row:
+                    self.assertIsInstance(column, State)
+            self.assertEqual(rows, [(State.ACTIVE, State.ACTIVE), (State.INACTIVE, State.INACTIVE)])
+
+            record = await select_sql.fetchrow(conn)
+            self.assertIsNotNone(record)
+            if record:
+                for column in record:
+                    self.assertIsInstance(column, State)
+                self.assertEqual(record, (State.ACTIVE, State.ACTIVE))
+
+            value = await value_sql.fetchval(conn)
+            self.assertIsInstance(value, State)
+            self.assertEqual(value, State.ACTIVE)
+
     async def test_sql(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE sample_data(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 boolean_value bool NOT NULL,
@@ -258,7 +329,7 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
             RETURNING id;
             """,
             args=tuple[bool, int, str | None],
-            resultset=int,
+            result=int,
         )
 
         count_sql = sql(
@@ -266,7 +337,7 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
             --sql
             SELECT COUNT(*) FROM sample_data;
             """,
-            resultset=int,
+            result=int,
         )
 
         count_where_sql = sql(
@@ -274,8 +345,8 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
             --sql
             SELECT COUNT(*) FROM sample_data WHERE integer_value > $1;
             """,
-            args=int,
-            resultset=int,
+            arg=int,
+            result=int,
         )
 
         async with get_connection() as conn:
@@ -341,12 +412,12 @@ class TestDataTypes(unittest.IsolatedAsyncioTestCase):
                     SELECT
                         {nullif(0, index)}, {nullif(1, index)}, {nullif(2, index)}, {nullif(3, index)},
                         {nullif(4, index)}, {nullif(5, index)}, {nullif(6, index)}, {nullif(7, index)};
-                    """,
+                    """,  # pyright: ignore[reportArgumentType]
                     args=tuple[int, int, int, int, int, int, int, int],
                     resultset=tuple[tuple(params)],  # type: ignore[misc]
                 )  # type: ignore[call-overload]
 
-                rows = await passthrough_sql.fetch(conn, *args)
+                rows = await passthrough_sql.fetch(conn, *args)  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
                 resultset: list[int | None] = [i for i in args]
                 resultset[index] = None
                 self.assertEqual(rows, [tuple(resultset)])

{asyncpg_typed-0.1.0/test → asyncpg_typed-0.1.1/tests}/test_template.py

@@ -8,31 +8,20 @@ Type-safe queries for asyncpg.
 
 import sys
 import unittest
-from contextlib import asynccontextmanager
-
-import asyncpg
 
 from asyncpg_typed import sql
+from tests.connection import get_connection
 
 if sys.version_info >= (3, 14):
     from string.templatelib import Interpolation, Template
 
 
-@asynccontextmanager
-async def get_connection():
-    conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
-    try:
-        yield conn
-    finally:
-        await conn.close()
-
-
 @unittest.skipUnless(sys.version_info >= (3, 14), "requires Python 3.14 or later")
 class TestTemplate(unittest.IsolatedAsyncioTestCase):
     async def test_sql(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE TEMPORARY TABLE sample_data(
                 id bigint GENERATED ALWAYS AS IDENTITY,
                 boolean_value bool NOT NULL,

{asyncpg_typed-0.1.0/test → asyncpg_typed-0.1.1/tests}/test_vector.py

@@ -5,33 +5,23 @@ Type-safe queries for asyncpg.
 """
 
 import unittest
-from contextlib import asynccontextmanager
 from random import random
 
-import asyncpg
 from asyncpg_vector import HalfVector, Vector, register_vector
 
 from asyncpg_typed import sql
+from tests.connection import get_connection
 
 
 class RollbackException(RuntimeError):
     pass
 
 
-@asynccontextmanager
-async def get_connection():
-    conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
-    try:
-        yield conn
-    finally:
-        await conn.close()
-
-
 class TestConnection(unittest.IsolatedAsyncioTestCase):
     async def test_vector_type(self) -> None:
         create_sql = sql(
             """
-            ---sql
+            --sql
             CREATE EXTENSION IF NOT EXISTS vector;
 
             --sql