iron-sql 0.5.2__tar.gz → 0.5.4__tar.gz

{iron_sql-0.5.2 → iron_sql-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iron-sql
-Version: 0.5.2
+Version: 0.5.4
 Summary: iron_sql generates typed async PostgreSQL clients and runtime helpers from schemas and SQL queries
 Keywords: postgresql,sql,sqlc,psycopg,codegen,async
 Author: Ilia Ablamonov
@@ -16,7 +16,7 @@ Requires-Dist: psycopg>=3.3.2
 Requires-Dist: psycopg-pool>=3.3.0
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: inflection>=0.5.1 ; extra == 'codegen'
-Requires-Dist: sqlc>=1.30.0.post18 ; extra == 'codegen'
+Requires-Dist: sqlc>=1.30.0.post19 ; extra == 'codegen'
 Requires-Python: >=3.13
 Project-URL: Homepage, https://github.com/Flamefork/iron_sql
 Project-URL: Repository, https://github.com/Flamefork/iron_sql.git

{iron_sql-0.5.2 → iron_sql-0.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iron-sql"
-version = "0.5.2"
+version = "0.5.4"
 
 description = "iron_sql generates typed async PostgreSQL clients and runtime helpers from schemas and SQL queries"
 readme = "README.md"
@@ -26,7 +26,7 @@ dependencies = [
 [project.optional-dependencies]
 codegen = [
     "inflection>=0.5.1",
-    "sqlc>=1.30.0.post18",
+    "sqlc>=1.30.0.post19",
 ]
 
 [project.urls]
@@ -53,14 +53,6 @@ dev = [
 
 [tool.pyright]
 typeCheckingMode = "strict"
-reportUnknownArgumentType = "none"
-reportUnknownLambdaType = "none"
-reportUnknownMemberType = "none"
-reportUnknownParameterType = "none"
-reportUnknownVariableType = "none"
-reportMissingParameterType = "none"
-reportMissingTypeArgument = "none"
-reportMissingTypeStubs = "none"
 deprecateTypingAliases = true
 reportImportCycles = true
 reportUnnecessaryTypeIgnoreComment = true

{iron_sql-0.5.2 → iron_sql-0.5.4}/src/iron_sql/codegen/generator.py

@@ -31,9 +31,18 @@ class ColumnSpec:
     name: str
     table: str
     py_type: str
+    element_py_type: str | None = None
     json_type: str | None = None
 
 
+_JSON_PARAM_DUMPERS = {
+    "json": "runtime.dump_json_value",
+    "jsonb": "runtime.dump_json_value",
+    "text": "runtime.dump_json_text",
+    "varchar": "runtime.dump_json_text",
+}
+
+
 @dataclass(kw_only=True, frozen=True)
 class ParamSpec:
     name: str
@@ -51,19 +60,23 @@ class ParamSpec:
 
     @property
     def serialized_expr(self) -> str:
+        expr = self.name
+        wraps_value = False
         if self.json_type:
-            return f"runtime.serialize_json_param({self.json_type}, {self.name}, {self.db_type!r})"  # noqa: E501
-
+            dump_fn = _JSON_PARAM_DUMPERS[self.db_type]
+            expr = f"{dump_fn}({self.json_type}, {self.name})"
+            wraps_value = True
         match self.db_type:
             case "json":
-                expr = f"psycopg.types.json.Json({self.name})"
+                expr = f"psycopg.types.json.Json({expr})"
+                wraps_value = True
             case "jsonb":
-                expr = f"psycopg.types.json.Jsonb({self.name})"
+                expr = f"psycopg.types.json.Jsonb({expr})"
+                wraps_value = True
             case _:
-                return self.name
-
-        if not self.not_null:
-            return f"{expr} if {self.name} is not None else None"
+                pass
+        if wraps_value and not self.not_null:
+            expr = f"{expr} if {self.name} is not None else None"
         return expr
 
 
@@ -159,16 +172,17 @@ class TypeResolver:
     json_column_type_overrides: dict[tuple[str, str], str]
 
     def column_spec(self, column: Column) -> ColumnSpec:
-        _, py_type, json_type = self._resolve(column)
+        _, py_type, element_py_type, json_type = self._resolve(column)
         return ColumnSpec(
             name=column.name,
             table=column.table.name if column.table else "unknown",
             py_type=py_type,
+            element_py_type=element_py_type,
             json_type=json_type,
         )
 
     def param_spec(self, column: Column, name: str, *, is_named: bool) -> ParamSpec:
-        db_type, py_type, json_type = self._resolve(column)
+        db_type, py_type, _, json_type = self._resolve(column)
         return ParamSpec(
             name=name,
             py_type=py_type,
@@ -179,7 +193,7 @@ class TypeResolver:
             json_type=json_type,
         )
 
-    def _resolve(self, column: Column) -> tuple[str, str, str | None]:
+    def _resolve(self, column: Column) -> tuple[str, str, str | None, str | None]:
         db_type = column.type.name.removeprefix("pg_catalog.")
 
         json_type = None
@@ -210,13 +224,15 @@ class TypeResolver:
             )
             py_type = "object"
 
+        element_py_type = None
         if column.is_array:
+            element_py_type = py_type
             py_type = f"Sequence[{py_type}]"
 
         if not column.not_null:
             py_type += " | None"
 
-        return db_type, py_type, json_type
+        return db_type, py_type, element_py_type, json_type
 
 
 def collect_used_enums(sqlc_res: SQLCResult) -> set[tuple[str, str]]:
@@ -316,11 +332,24 @@ def generate_sql_module(  # noqa: PLR0913, PLR0914
 
     used_enums = collect_used_enums(sqlc_res)
 
-    enums = sorted(
-        render_enum_class(e, module_name, to_pascal_fn, to_snake_fn)
+    enum_specs = [
+        (schema, e)
         for schema in sqlc_res.catalog.schemas
         for e in schema.enums
         if (schema.name, e.name) in used_enums
+    ]
+
+    enums = sorted(
+        render_enum_class(e, module_name, to_pascal_fn, to_snake_fn)
+        for _, e in enum_specs
+    )
+
+    enum_registry = sorted(
+        (
+            f"{schema.name}.{e.name}",
+            enum_class_name(e.name, module_name, to_pascal_fn, to_snake_fn),
+        )
+        for schema, e in enum_specs
     )
 
     query_classes = render_query_classes(
@@ -341,6 +370,7 @@ def generate_sql_module(  # noqa: PLR0913, PLR0914
         sql_fn_name,
         entities,
         enums,
+        enum_registry,
         query_classes,
         query_overloads,
         query_dict_entries,
@@ -390,12 +420,7 @@ def render_query_classes(
                 for p in q.params
             ],
             query_result_types[q.name],
-            len(q.columns),
-            (
-                resolver.column_spec(q.columns[0]).json_type
-                if len(q.columns) == 1
-                else None
-            ),
+            tuple(resolver.column_spec(column) for column in q.columns),
             query_locations_by_name[q.name],
         )
         for q in sorted(sqlc_queries, key=lambda q: query_order[q.name])
@@ -408,7 +433,7 @@ def resolve_json_model_overrides(
     if not overrides:
         return "", {}
 
-    json_compatible_types = {"json", "jsonb", "text", "varchar"}
+    json_compatible_types = set(_JSON_PARAM_DUMPERS)
     col_types = {
         (table.rel.name, column.name): column.type.name.removeprefix("pg_catalog.")
         for schema in catalog.schemas
@@ -465,6 +490,7 @@ def render_module(  # noqa: PLR0913, PLR0917
     sql_fn_name: str,
     entities: list[str],
     enums: list[str],
+    enum_registry: list[tuple[str, str]],
     query_classes: list[str],
     query_overloads: list[str],
     query_dict_entries: list[str],
@@ -489,6 +515,20 @@ def render_module(  # noqa: PLR0913, PLR0917
 
     imports_block = "\n".join(imports)
 
+    pre_pool_blocks: list[str] = []
+    if enums:
+        pre_pool_blocks.append("\n\n\n".join(enums))
+    if enum_registry:
+        registry_entries = ",\n    ".join(
+            f'("{pg_name}", {class_name})' for pg_name, class_name in enum_registry
+        )
+        registry_type = "list[tuple[str, type[StrEnum]]]"
+        pre_pool_blocks.append(
+            f"ENUM_TYPES: {registry_type} = [\n    {registry_entries},\n]"
+        )
+        pool_args.append("enum_types=ENUM_TYPES")
+    pre_pool_section = "".join(f"{block}\n\n\n" for block in pre_pool_blocks)
+
     pool_args_str = ",\n    ".join(pool_args)
 
     return f"""
@@ -525,7 +565,7 @@ from iron_sql import runtime
 {imports_block}
 
 
-{module_name.upper()}_POOL = runtime.ConnectionPool(
+{pre_pool_section}{module_name.upper()}_POOL = runtime.ConnectionPool(
     {pool_args_str},
 )
 
@@ -561,9 +601,6 @@ async def {module_name}_notify(channel: str, payload: str = "") -> None:
         await runtime.notify(conn, channel, payload)
 
 
-{"\n\n\n".join(enums)}
-
-
 {"\n\n\n".join(entities)}
 
 
@@ -593,14 +630,23 @@ def {sql_fn_name}(sql: str, row_type: str | None = None) -> Query[Any]:
     """.strip()  # noqa: E501
 
 
+def enum_class_name(
+    enum_name: str,
+    module_name: str,
+    to_pascal_fn: Callable[[str], str],
+    to_snake_fn: Callable[[str], str],
+) -> str:
+    return to_pascal_fn(f"{module_name}_{to_snake_fn(enum_name)}")
+
+
 def render_enum_class(
     enum: Enum,
     module_name: str,
     to_pascal_fn: Callable[[str], str],
     to_snake_fn: Callable[[str], str],
 ) -> str:
-    class_name = to_pascal_fn(f"{module_name}_{to_snake_fn(enum.name)}")
-    members = []
+    class_name = enum_class_name(enum.name, module_name, to_pascal_fn, to_snake_fn)
+    members: list[str] = []
     seen_names: dict[str, int] = {}
 
     for val in enum.vals:
@@ -642,7 +688,7 @@ class {name}:
 
 
 def deduplicate_params(params: list[ParamSpec]) -> list[ParamSpec]:
-    seen = defaultdict(int)
+    seen: defaultdict[str, int] = defaultdict(int)
     result: list[ParamSpec] = []
     for param in params:
         seen[param.name] += 1
@@ -658,8 +704,7 @@ def render_query_class(
     sql: str,
     query_params: list[ParamSpec],
     result: str,
-    columns_num: int,
-    scalar_json_type: str | None,
+    result_columns: tuple[ColumnSpec, ...],
     locations: list[str],
 ) -> str:
     query_params = deduplicate_params(query_params)
@@ -681,24 +726,9 @@ def render_query_class(
     query_fn_params.insert(0, "self")
 
     base_result = result.removesuffix(" | None")
+    row_factory = render_row_factory(result, result_columns)
 
-    if columns_num == 0:
-        row_factory = "psycopg.rows.scalar_row"
-    elif columns_num == 1:
-        not_null_str = "True" if not result.endswith(" | None") else "False"
-        validate_arg = (
-            f", validate=lambda _v: runtime.validate_json_field({scalar_json_type}, _v)"
-            if scalar_json_type
-            else ""
-        )
-        row_factory = (
-            f"runtime.typed_scalar_row"
-            f"({base_result}, not_null={not_null_str}{validate_arg})"
-        )
-    else:
-        row_factory = f"psycopg.rows.class_row({result})"
-
-    if columns_num > 0:
+    if result_columns:
         methods = f"""
 
 async def query_all_rows({", ".join(query_fn_params)}) -> list[{result}]:
@@ -738,6 +768,34 @@ class {query_name}(Query[{result}]):
     """.strip()
 
 
+def render_row_factory(result: str, columns: tuple[ColumnSpec, ...]) -> str:
+    match columns:
+        case ():
+            return "psycopg.rows.scalar_row"
+        case (column,):
+            return render_scalar_row_factory(result, column)
+        case _:
+            return f"psycopg.rows.class_row({result})"
+
+
+def render_scalar_row_factory(result: str, column: ColumnSpec) -> str:
+    base_result = result.removesuffix(" | None")
+    not_null = "True" if not result.endswith(" | None") else "False"
+
+    if column.element_py_type is not None:
+        return f"runtime.typed_array_row({column.element_py_type}, not_null={not_null})"
+
+    validate_arg = (
+        f", validate=lambda _v: runtime.validate_json_field({column.json_type}, _v)"
+        if column.json_type
+        else ""
+    )
+    if " | " in base_result and not validate_arg:
+        return f"runtime.typed_value_row(not_null={not_null})"
+
+    return f"runtime.typed_scalar_row({base_result}, not_null={not_null}{validate_arg})"
+
+
 def render_query_overload(
     sql_fn_name: str, query_name: str, sql: str, row_type: str | None
 ) -> str:
@@ -846,7 +904,7 @@ def build_entities(
         key=lambda e: (e.table_name is None, e.table_name or ""),
     )
 
-    query_result_types = {}
+    query_result_types: dict[str, str] = {}
     for q in queries_from_sqlc:
         if len(q.columns) == 0:
             query_result_types[q.name] = "None"

{iron_sql-0.5.2 → iron_sql-0.5.4}/src/iron_sql/runtime.py

@@ -1,5 +1,6 @@
 import asyncio
 import contextlib
+import functools
 import itertools
 import types
 from collections.abc import AsyncGenerator
@@ -8,29 +9,28 @@ from collections.abc import Callable
 from collections.abc import Sequence
 from contextlib import asynccontextmanager
 from contextvars import ContextVar
-from enum import Enum
+from enum import StrEnum
 from typing import Any
 from typing import ClassVar
 from typing import Literal
 from typing import Self
 from typing import TypedDict
+from typing import TypeGuard
 from typing import overload
 
 import psycopg
 import psycopg.abc
 import psycopg.rows
 import psycopg.sql
-import psycopg.types.json
+import psycopg.types.enum
 import psycopg_pool
+from psycopg._cursor_base import BaseCursor
 from pydantic import TypeAdapter
 
-_adapter_cache: dict[object, TypeAdapter[object]] = {}
 
-
-def get_adapter(typ: object) -> TypeAdapter[object]:
-    if typ not in _adapter_cache:
-        _adapter_cache[typ] = TypeAdapter(typ)
-    return _adapter_cache[typ]
+@functools.cache
+def get_adapter(typ: object) -> TypeAdapter[Any]:
+    return TypeAdapter(typ)
 
 
 class NoRowsError(Exception):
@@ -43,7 +43,7 @@ class TooManyRowsError(Exception):
 
 @asynccontextmanager
 async def listen(
-    conn: psycopg.AsyncConnection, channel: str
+    conn: psycopg.AsyncConnection[Any], channel: str
 ) -> AsyncGenerator[AsyncGenerator[str]]:
     _validate_channel(channel)
     if await _has_active_listen_subscriptions(conn):
@@ -65,7 +65,9 @@ async def listen(
             await execute_unlisten(conn, channel)
 
 
-async def notify(conn: psycopg.AsyncConnection, channel: str, payload: str) -> None:
+async def notify(
+    conn: psycopg.AsyncConnection[Any], channel: str, payload: str
+) -> None:
     _validate_channel(channel)
     await conn.execute(
         psycopg.sql.SQL("NOTIFY {}, {}").format(
@@ -75,21 +77,21 @@ async def notify(conn: psycopg.AsyncConnection, channel: str, payload: str) -> N
     )
 
 
-async def execute_listen(conn: psycopg.AsyncConnection, channel: str) -> None:
+async def execute_listen(conn: psycopg.AsyncConnection[Any], channel: str) -> None:
     _validate_channel(channel)
     await conn.execute(
         psycopg.sql.SQL("LISTEN {}").format(psycopg.sql.Identifier(channel))
     )
 
 
-async def execute_unlisten(conn: psycopg.AsyncConnection, channel: str) -> None:
+async def execute_unlisten(conn: psycopg.AsyncConnection[Any], channel: str) -> None:
     _validate_channel(channel)
     await conn.execute(
         psycopg.sql.SQL("UNLISTEN {}").format(psycopg.sql.Identifier(channel))
     )
 
 
-async def _has_active_listen_subscriptions(conn: psycopg.AsyncConnection) -> bool:
+async def _has_active_listen_subscriptions(conn: psycopg.AsyncConnection[Any]) -> bool:
     async with conn.cursor() as cur:
         await cur.execute("SELECT EXISTS (SELECT FROM pg_listening_channels())")
         row = await cur.fetchone()
@@ -113,7 +115,9 @@ def _next_cursor_name() -> str:
 
 
 @asynccontextmanager
-async def _ensure_transaction(conn: psycopg.AsyncConnection) -> AsyncGenerator[None]:
+async def _ensure_transaction(
+    conn: psycopg.AsyncConnection[Any],
+) -> AsyncGenerator[None]:
     match conn.info.transaction_status:
         case psycopg.pq.TransactionStatus.IDLE:
             async with conn.transaction():
@@ -129,10 +133,10 @@ class Query[T]:
     _stmt: ClassVar[psycopg.sql.SQL]
     _row_factory: psycopg.rows.BaseRowFactory[T]
     _connection_factory: Callable[
-        [], contextlib.AbstractAsyncContextManager[psycopg.AsyncConnection]
+        [], contextlib.AbstractAsyncContextManager[psycopg.AsyncConnection[Any]]
     ]
 
-    def with_connection(self, connection: psycopg.AsyncConnection) -> Self:
+    def with_connection(self, connection: psycopg.AsyncConnection[Any]) -> Self:
         q = self.__class__()
         q._connection_factory = lambda: contextlib.nullcontext(connection)  # noqa: SLF001
         return q
@@ -179,6 +183,35 @@ class PoolOptions(TypedDict, total=False):
     reconnect_failed: Callable[[psycopg_pool.AsyncConnectionPool[Any]], Awaitable[None]]
 
 
+async def register_enums(
+    conn: psycopg.AsyncConnection[Any],
+    enum_types: Sequence[tuple[str, type[StrEnum]]],
+) -> None:
+    for pg_name, enum_cls in enum_types:
+        info = await psycopg.types.enum.EnumInfo.fetch(conn, pg_name)
+        if info is None:
+            msg = f"Enum type {pg_name!r} not found in database"
+            raise RuntimeError(msg)
+        psycopg.types.enum.register_enum(
+            info,
+            conn,
+            enum_cls,
+            mapping=[(member, member.value) for member in enum_cls],
+        )
+
+
+def _enum_configure(
+    enum_types: Sequence[tuple[str, type[StrEnum]]],
+    user_configure: Callable[[psycopg.AsyncConnection[Any]], Awaitable[None]] | None,
+) -> Callable[[psycopg.AsyncConnection[Any]], Awaitable[None]]:
+    async def configure(conn: psycopg.AsyncConnection[Any]) -> None:
+        await register_enums(conn, enum_types)
+        if user_configure is not None:
+            await user_configure(conn)
+
+    return configure
+
+
 class ConnectionPool:
     def __init__(
         self,
@@ -187,11 +220,13 @@ class ConnectionPool:
         name: str | None = None,
         application_name: str | None = None,
         pool_options: PoolOptions | None = None,
+        enum_types: Sequence[tuple[str, type[StrEnum]]] = (),
     ) -> None:
         self.conninfo = conninfo
         self.name = name
         self.application_name = application_name
         self.pool_options = pool_options or {}
+        self.enum_types = enum_types
         self._init_psycopg_pool()
 
     async def close(self) -> None:
@@ -217,7 +252,7 @@ class ConnectionPool:
         await self.psycopg_pool.check()
 
     @asynccontextmanager
-    async def connection(self) -> AsyncGenerator[psycopg.AsyncConnection]:
+    async def connection(self) -> AsyncGenerator[psycopg.AsyncConnection[Any]]:
         task = asyncio.current_task()
         cancelling_before = 0 if task is None else task.cancelling()
         await self.psycopg_pool.open()
@@ -232,6 +267,10 @@ class ConnectionPool:
         forwarded: dict[str, Any] = {
             k: v for k, v in self.pool_options.items() if k != "kwargs"
         }
+        if self.enum_types:
+            forwarded["configure"] = _enum_configure(
+                self.enum_types, forwarded.get("configure")
+            )
         conn_kwargs = {
             **user_kwargs,
             # https://www.psycopg.org/psycopg3/docs/basic/transactions.html#autocommit-transactions
@@ -249,8 +288,8 @@ class ConnectionPool:
 
     @asynccontextmanager
     async def connection_in_context(
-        self, context_var: ContextVar[psycopg.AsyncConnection | None]
-    ) -> AsyncGenerator[psycopg.AsyncConnection]:
+        self, context_var: ContextVar[psycopg.AsyncConnection[Any] | None]
+    ) -> AsyncGenerator[psycopg.AsyncConnection[Any]]:
         conn = context_var.get()
         if conn is not None:
             yield conn
@@ -263,42 +302,40 @@ class ConnectionPool:
                 context_var.reset(token)
 
 
-def validate_json_field(typ: object, value: object) -> object:
-    if value is None:
-        return None
+def validate_json_field[T](typ: type[T], value: object) -> T:
     adapter = get_adapter(typ)
     if isinstance(value, str | bytes):
         return adapter.validate_json(value)
     return adapter.validate_python(value)
 
 
-def json_validated(**json_fields: object):
-    def decorator[T](cls: type[T]) -> type[T]:
-        original = getattr(cls, "__post_init__", None)
+def json_validated[T](**json_fields: object) -> Callable[[type[T]], type[T]]:
+    def decorator(cls: type[T]) -> type[T]:
+        original_post_init = getattr(cls, "__post_init__", None)
 
         def __post_init__(self: object) -> None:  # noqa: N807
-            if original is not None:
-                original(self)
+            if original_post_init is not None:
+                original_post_init(self)
             for name, typ in json_fields.items():
-                setattr(self, name, validate_json_field(typ, getattr(self, name)))
+                current = getattr(self, name)
+                if current is None:
+                    continue
+                setattr(self, name, validate_json_field(typ, current))  # pyright: ignore[reportArgumentType]
 
-        cls.__post_init__ = __post_init__  # type: ignore[attr-defined]
+        setattr(cls, "__post_init__", __post_init__)  # noqa: B010
         return cls
 
     return decorator
 
 
-def serialize_json_param(typ: object, value: object, db_type: str) -> object:
-    if value is None:
-        return None
+def dump_json_value(typ: object, value: object) -> object:
     adapter = get_adapter(typ)
-    match db_type:
-        case "json":
-            return psycopg.types.json.Json(adapter.dump_python(value, mode="json"))
-        case "jsonb":
-            return psycopg.types.json.Jsonb(adapter.dump_python(value, mode="json"))
-        case _:
-            return adapter.dump_json(value).decode()
+    return adapter.dump_python(value, mode="json")
+
+
+def dump_json_text(typ: object, value: object) -> str:
+    adapter = get_adapter(typ)
+    return adapter.dump_json(value).decode()
 
 
 def get_one_row[T](rows: list[T]) -> T:
@@ -338,7 +375,9 @@ def typed_scalar_row[T](
 def typed_scalar_row[T](
     typ: type[T], *, not_null: bool, validate: Callable[[object], T] | None = None
 ) -> psycopg.rows.BaseRowFactory[T | None]:
-    def typed_scalar_row_(cursor) -> psycopg.rows.RowMaker[T | None]:
+    def typed_scalar_row_(
+        cursor: BaseCursor[Any, Any],
+    ) -> psycopg.rows.RowMaker[T | None]:
         scalar_row_ = psycopg.rows.scalar_row(cursor)
 
         def typed_scalar_row__(values: Sequence[Any]) -> T | None:
@@ -350,13 +389,98 @@ def typed_scalar_row[T](
                 return None
             if validate:
                 return validate(val)
-            if not isinstance(val, typ):
-                if issubclass(typ, Enum):
-                    return typ(val)
-                msg = f"Expected scalar of type {typ}, got {type(val)}"
-                raise TypeError(msg)
-            return val
+            return _check_scalar_type(val, typ)
 
         return typed_scalar_row__
 
     return typed_scalar_row_
+
+
+@overload
+def typed_value_row[T](
+    *,
+    not_null: Literal[True],
+) -> psycopg.rows.BaseRowFactory[T]: ...
+
+
+@overload
+def typed_value_row[T](
+    *,
+    not_null: Literal[False],
+) -> psycopg.rows.BaseRowFactory[T | None]: ...
+
+
+def typed_value_row[T](*, not_null: bool) -> psycopg.rows.BaseRowFactory[T | None]:
+    def typed_value_row_(
+        cursor: BaseCursor[Any, Any],
+    ) -> psycopg.rows.RowMaker[T | None]:
+        scalar_row_ = psycopg.rows.scalar_row(cursor)
+
+        def typed_value_row__(values: Sequence[Any]) -> T | None:
+            val = scalar_row_(values)
+            if val is None:
+                if not_null:
+                    msg = "Expected non-null value, got None"
+                    raise TypeError(msg)
+                return None
+            return val
+
+        return typed_value_row__
+
+    return typed_value_row_
+
+
+@overload
+def typed_array_row[T](
+    elem_typ: type[T],
+    *,
+    not_null: Literal[True],
+) -> psycopg.rows.BaseRowFactory[list[T]]: ...
+
+
+@overload
+def typed_array_row[T](
+    elem_typ: type[T],
+    *,
+    not_null: Literal[False],
+) -> psycopg.rows.BaseRowFactory[list[T] | None]: ...
+
+
+def typed_array_row[T](
+    elem_typ: type[T], *, not_null: bool
+) -> psycopg.rows.BaseRowFactory[list[T] | None]:
+    def typed_array_row_(
+        cursor: BaseCursor[Any, Any],
+    ) -> psycopg.rows.RowMaker[list[T] | None]:
+        scalar_row_ = psycopg.rows.scalar_row(cursor)
+
+        def typed_array_row__(values: Sequence[Any]) -> list[T] | None:
+            val = scalar_row_(values)
+            if val is None:
+                if not_null:
+                    msg = "Expected non-null value, got None"
+                    raise TypeError(msg)
+                return None
+            if not _is_object_list(val):
+                msg = f"Expected scalar of type list[{elem_typ}], got {type(val)}"
+                raise TypeError(msg)
+            return [_check_scalar_type(v, elem_typ) for v in val]
+
+        return typed_array_row__
+
+    return typed_array_row_
+
+
+def _check_scalar_type[T](val: object, typ: type[T]) -> T:
+    if _is_instance(val, typ):
+        return val
+    msg = f"Expected scalar of type {typ}, got {type(val)}"
+    raise TypeError(msg)
+
+
+def _is_instance[T](val: object, typ: type[T]) -> TypeGuard[T]:
+    return isinstance(val, typ)
+
+
+def _is_object_list(val: object) -> TypeGuard[list[object]]:
+    return isinstance(val, list)