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

asyncpg_typed/__init__.py

@@ -4,7 +4,7 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2025, Levente Hunyadi"
 __license__ = "MIT"
@@ -16,12 +16,14 @@ import sys
 import typing
 from abc import abstractmethod
 from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
 from datetime import date, datetime, time, timedelta
 from decimal import Decimal
 from functools import reduce
 from io import StringIO
+from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network
 from types import UnionType
-from typing import Any, Protocol, TypeAlias, TypeVar, Union, get_args, get_origin, overload
+from typing import Any, Protocol, TypeAlias, TypeGuard, TypeVar, Union, get_args, get_origin, overload
 from uuid import UUID
 
 import asyncpg
@@ -38,9 +40,24 @@ RequiredJsonType = bool | int | float | str | dict[str, "JsonType"] | list["Json
 
 TargetType: TypeAlias = type[Any] | UnionType
 
+Connection: TypeAlias = asyncpg.Connection | asyncpg.pool.PoolConnectionProxy
+
+
+class TypeMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a PostgreSQL type incompatible with the declared Python type."
+
+
+class EnumMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a PostgreSQL enum type whose permitted set of values differs from what is declared in Python."
+
+
+class NoneTypeError(TypeError):
+    "Raised when a column marked as required contains a `NULL` value."
+
+
 if sys.version_info >= (3, 11):
 
-    def is_enum_type(typ: object) -> bool:
+    def is_enum_type(typ: Any) -> TypeGuard[type[enum.Enum]]:
         """
         `True` if the specified type is an enumeration type.
         """
@@ -49,7 +66,7 @@ if sys.version_info >= (3, 11):
 
 else:
 
-    def is_enum_type(typ: object) -> bool:
+    def is_enum_type(typ: Any) -> TypeGuard[type[enum.Enum]]:
         """
         `True` if the specified type is an enumeration type.
         """
@@ -91,6 +108,14 @@ def is_json_type(tp: Any) -> bool:
     return tp in [JsonType, RequiredJsonType]
 
 
+def is_inet_type(tp: Any) -> bool:
+    """
+    `True` if the type represents an IP address or network.
+    """
+
+    return tp in [IPv4Address, IPv6Address, IPv4Network, IPv6Network]
+
+
 def make_union_type(tpl: list[Any]) -> UnionType:
     """
     Creates a `UnionType` (a.k.a. `A | B | C`) dynamically at run time.
@@ -119,25 +144,54 @@ def get_required_type(tp: Any) -> Any:
         return type(None)
 
 
-_json_converter: Callable[[str], JsonType]
-if typing.TYPE_CHECKING:
+def _standard_json_decoder() -> Callable[[str], JsonType]:
     import json
 
     _json_decoder = json.JSONDecoder()
-    _json_converter = _json_decoder.decode
-else:
-    try:
-        import orjson
+    return _json_decoder.decode
 
-        _json_converter = orjson.loads
-    except ModuleNotFoundError:
-        import json
 
-        _json_decoder = json.JSONDecoder()
-        _json_converter = _json_decoder.decode
+def _json_decoder() -> Callable[[str], JsonType]:
+    if typing.TYPE_CHECKING:
+        return _standard_json_decoder()
+    else:
+        try:
+            import orjson
+
+            return orjson.loads
+        except ModuleNotFoundError:
+            return _standard_json_decoder()
 
 
-def get_converter_for(tp: Any) -> Callable[[Any], Any]:
+JSON_DECODER = _json_decoder()
+
+
+def _standard_json_encoder() -> Callable[[JsonType], str]:
+    import json
+
+    _json_encoder = json.JSONEncoder(ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+    return _json_encoder.encode
+
+
+def _json_encoder() -> Callable[[JsonType], str]:
+    if typing.TYPE_CHECKING:
+        return _standard_json_encoder()
+    else:
+        try:
+            import orjson
+
+            def _wrap(value: JsonType) -> str:
+                return orjson.dumps(value).decode()
+
+            return _wrap
+        except ModuleNotFoundError:
+            return _standard_json_encoder()
+
+
+JSON_ENCODER = _json_encoder()
+
+
+def get_output_converter_for(tp: Any) -> Callable[[Any], Any]:
     """
     Returns a callable that takes a wire type and returns a target type.
 
@@ -147,65 +201,165 @@ def get_converter_for(tp: Any) -> Callable[[Any], Any]:
 
     if is_json_type(tp):
         # asyncpg returns fields of type `json` and `jsonb` as `str`, which must be de-serialized
-        return _json_converter
+        return JSON_DECODER
     else:
         # target data types that require conversion must have a single-argument `__init__` that takes an object of the source type
         return tp
 
 
+def get_input_converter_for(tp: Any) -> Callable[[Any], Any]:
+    """
+    Returns a callable that takes a source type and returns a wire type.
+
+    A source type is one of the types supported by the library.
+    A wire type is one of the types returned by asyncpg.
+    """
+
+    if is_json_type(tp):
+        # asyncpg expects fields of type `json` and `jsonb` as `str`, which must be serialized
+        return JSON_ENCODER
+    else:
+        # source data types that require conversion must have a single-argument `__init__` that takes an object of the source type
+        return tp
+
+
 # maps PostgreSQL internal type names to compatible Python types
-_name_to_type: dict[str, tuple[Any, ...]] = {
+_NAME_TO_TYPE: dict[str, tuple[Any, ...]] = {
+    # boolean type
     "bool": (bool,),
+    # numeric types
     "int2": (int,),
     "int4": (int,),
     "int8": (int,),
     "float4": (float,),
     "float8": (float,),
     "numeric": (Decimal,),
+    # date and time types
     "date": (date,),
     "time": (time,),
     "timetz": (time,),
     "timestamp": (datetime,),
     "timestamptz": (datetime,),
     "interval": (timedelta,),
+    # character sequence types
     "bpchar": (str,),
     "varchar": (str,),
     "text": (str,),
+    # binary sequence types
     "bytea": (bytes,),
+    # unique identifier type
+    "uuid": (UUID,),
+    # address types
+    "cidr": (IPv4Network, IPv6Network, IPv4Network | IPv6Network),
+    "inet": (IPv4Network, IPv6Network, IPv4Network | IPv6Network, IPv4Address, IPv6Address, IPv4Address | IPv6Address),
+    "macaddr": (str,),
+    "macaddr8": (str,),
+    # JSON type
     "json": (str, RequiredJsonType),
     "jsonb": (str, RequiredJsonType),
-    "uuid": (UUID,),
+    # XML type
     "xml": (str,),
+    # geometric types
+    "point": (asyncpg.Point,),
+    "line": (asyncpg.Line,),
+    "lseg": (asyncpg.LineSegment,),
+    "box": (asyncpg.Box,),
+    "path": (asyncpg.Path,),
+    "polygon": (asyncpg.Polygon,),
+    "circle": (asyncpg.Circle,),
+    # range types
+    "int4range": (asyncpg.Range[int],),
+    "int4multirange": (list[asyncpg.Range[int]],),
+    "int8range": (asyncpg.Range[int],),
+    "int8multirange": (list[asyncpg.Range[int]],),
+    "numrange": (asyncpg.Range[Decimal],),
+    "nummultirange": (list[asyncpg.Range[Decimal]],),
+    "tsrange": (asyncpg.Range[datetime],),
+    "tsmultirange": (list[asyncpg.Range[datetime]],),
+    "tstzrange": (asyncpg.Range[datetime],),
+    "tstzmultirange": (list[asyncpg.Range[datetime]],),
+    "daterange": (asyncpg.Range[date],),
+    "datemultirange": (list[asyncpg.Range[date]],),
 }
 
 
-def check_data_type(schema: str, name: str, data_type: TargetType) -> bool:
+def type_to_str(tp: Any) -> str:
+    "Emits a friendly name for a type."
+
+    if isinstance(tp, type):
+        return tp.__name__
+    else:
+        return str(tp)
+
+
+class _TypeVerifier:
     """
     Verifies if the Python target type can represent the PostgreSQL source type.
     """
 
-    if schema == "pg_catalog":
-        if is_enum_type(data_type):
-            return name in ["bpchar", "varchar", "text"]
+    _connection: Connection
 
-        expected_types = _name_to_type.get(name)
-        return expected_types is not None and data_type in expected_types
-    else:
-        if is_standard_type(data_type):
-            return False
+    def __init__(self, connection: Connection) -> None:
+        self._connection = connection
+
+    async def _check_enum_type(self, pg_name: str, pg_type: asyncpg.Type, data_type: type[enum.Enum]) -> None:
+        """
+        Verifies if a Python enumeration type matches a PostgreSQL enumeration type.
+        """
 
-        # user-defined type registered with `conn.set_type_codec()`
-        return True
+        for e in data_type:
+            if not isinstance(e.value, str):
+                raise TypeMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` with `str` values; got: `{type_to_str(type(e.value))}` for enum field `{e.name}`")
 
+        py_values = set(e.value for e in data_type)
 
+        rows = await self._connection.fetch("SELECT enumlabel FROM pg_enum WHERE enumtypid = $1 ORDER BY enumsortorder;", pg_type.oid)
+        db_values = set(row[0] for row in rows)
+
+        db_extra = db_values - py_values
+        if db_extra:
+            raise EnumMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` to match values of PostgreSQL enum type `{pg_type.name}` for {pg_name}; missing value(s): {', '.join(f'`{val}`' for val in db_extra)})")
+
+        py_extra = py_values - db_values
+        if py_extra:
+            raise EnumMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` to match values of PostgreSQL enum type `{pg_type.name}` for {pg_name}; got extra value(s): {', '.join(f'`{val}`' for val in py_extra)})")
+
+    async def check_data_type(self, pg_name: str, pg_type: asyncpg.Type, data_type: TargetType) -> None:
+        """
+        Verifies if the Python target type can represent the PostgreSQL source type.
+        """
+
+        if pg_type.schema == "pg_catalog":  # well-known PostgreSQL types
+            if is_enum_type(data_type):
+                if pg_type.name not in ["bpchar", "varchar", "text"]:
+                    raise TypeMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` instead of `char`, `varchar` or `text`")
+            else:
+                expected_types = _NAME_TO_TYPE.get(pg_type.name)
+                if expected_types is None:
+                    raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: unrecognized PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+                elif data_type not in expected_types:
+                    raise TypeMismatchError(
+                        f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; "
+                        f"got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`, which converts to one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
+                    )
+        elif pg_type.kind == "composite":  # PostgreSQL composite types
+            # user-defined composite types registered with `conn.set_type_codec()` typically using `format="tuple"`
+            pass
+        else:  # custom PostgreSQL types
+            if is_enum_type(data_type):
+                await self._check_enum_type(pg_name, pg_type, data_type)
+            elif is_standard_type(data_type):
+                raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+            else:
+                # user-defined types registered with `conn.set_type_codec()`
+                pass
+
+
+@dataclass(frozen=True)
 class _SQLPlaceholder:
     ordinal: int
     data_type: TargetType
 
-    def __init__(self, ordinal: int, data_type: TargetType) -> None:
-        self.ordinal = ordinal
-        self.data_type = data_type
-
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.ordinal}, {self.data_type!r})"
 
@@ -215,33 +369,51 @@ class _SQLObject:
     Associates input and output type information with a SQL statement.
     """
 
-    parameter_data_types: tuple[_SQLPlaceholder, ...]
-    resultset_data_types: tuple[TargetType, ...]
-    required: int
-    cast: int
-    converters: tuple[Callable[[Any], Any], ...]
+    _parameter_data_types: tuple[_SQLPlaceholder, ...]
+    _resultset_data_types: tuple[TargetType, ...]
+    _parameter_cast: int
+    _parameter_converters: tuple[Callable[[Any], Any], ...]
+    _required: int
+    _resultset_cast: int
+    _resultset_converters: tuple[Callable[[Any], Any], ...]
+
+    @property
+    def parameter_data_types(self) -> tuple[_SQLPlaceholder, ...]:
+        return self._parameter_data_types
+
+    @property
+    def resultset_data_types(self) -> tuple[TargetType, ...]:
+        return self._resultset_data_types
 
     def __init__(
         self,
         input_data_types: tuple[TargetType, ...],
         output_data_types: tuple[TargetType, ...],
     ) -> None:
-        self.parameter_data_types = tuple(_SQLPlaceholder(ordinal, get_required_type(arg)) for ordinal, arg in enumerate(input_data_types, start=1))
-        self.resultset_data_types = tuple(get_required_type(data_type) for data_type in output_data_types)
+        self._parameter_data_types = tuple(_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 types that require cast or serialization (1: apply conversion; 0: forward value as-is)
+        parameter_cast = 0
+        for index, placeholder in enumerate(self._parameter_data_types):
+            parameter_cast |= is_json_type(placeholder.data_type) << index
+        self._parameter_cast = parameter_cast
+
+        self._parameter_converters = tuple(get_input_converter_for(placeholder.data_type) for placeholder in self._parameter_data_types)
 
         # create a bit-field of required types (1: required; 0: optional)
         required = 0
         for index, data_type in enumerate(output_data_types):
             required |= (not is_optional_type(data_type)) << index
-        self.required = required
+        self._required = required
 
-        # create a bit-field of types that require cast or serialization (1: apply conversion; 0: forward value as-is)
-        cast = 0
-        for index, data_type in enumerate(self.resultset_data_types):
-            cast |= (is_enum_type(data_type) or is_json_type(data_type)) << index
-        self.cast = cast
+        # create a bit-field of types that require cast or de-serialization (1: apply conversion; 0: forward value as-is)
+        resultset_cast = 0
+        for index, data_type in enumerate(self._resultset_data_types):
+            resultset_cast |= (is_enum_type(data_type) or is_json_type(data_type) or is_inet_type(data_type)) << index
+        self._resultset_cast = resultset_cast
 
-        self.converters = tuple(get_converter_for(data_type) for data_type in self.resultset_data_types)
+        self._resultset_converters = tuple(get_output_converter_for(data_type) for data_type in self._resultset_data_types)
 
     def _raise_required_is_none(self, row: tuple[Any, ...], row_index: int | None = None) -> None:
         """
@@ -249,12 +421,12 @@ class _SQLObject:
         """
 
         for col_index in range(len(row)):
-            if (self.required >> col_index & 1) and row[col_index] is None:
+            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")
+                raise NoneTypeError(f"expected: {self._resultset_data_types[col_index]} in {row_col_spec}; got: NULL")
 
     def check_rows(self, rows: list[tuple[Any, ...]]) -> None:
         """
@@ -264,7 +436,7 @@ class _SQLObject:
         if not rows:
             return
 
-        required = self.required
+        required = self._required
         if not required:
             return
 
@@ -317,7 +489,7 @@ class _SQLObject:
         Verifies if declared types match actual value types in a single row.
         """
 
-        required = self.required
+        required = self._required
         if not required:
             return
 
@@ -361,8 +533,72 @@ class _SQLObject:
         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")
+        if self._required and value is None:
+            raise NoneTypeError(f"expected: {self._resultset_data_types[0]}; got: NULL")
+
+    def convert_arg_lists(self, arg_lists: Iterable[Sequence[Any]]) -> Iterable[Sequence[Any]]:
+        """
+        Converts a list of Python query argument tuples to a list of PostgreSQL parameter tuples.
+        """
+
+        cast = self._parameter_cast
+        if cast:
+            converters = self._parameter_converters
+            yield from (tuple((converters[i](value) if (value := arg[i]) is not None and cast >> i & 1 else value) for i in range(len(arg))) for arg in arg_lists)
+        else:
+            yield from arg_lists
+
+    def convert_arg_list(self, arg_list: Sequence[Any]) -> Sequence[Any]:
+        """
+        Converts Python query arguments to PostgreSQL parameters.
+        """
+
+        cast = self._parameter_cast
+        if cast:
+            converters = self._parameter_converters
+            return tuple((converters[i](value) if (value := arg_list[i]) is not None and cast >> i & 1 else value) for i in range(len(arg_list)))
+        else:
+            return tuple(value for value in arg_list)
+
+    def convert_rows(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
+        """
+        Converts columns in the PostgreSQL result-set to their corresponding Python target types.
+
+        :param rows: List of rows returned by PostgreSQL.
+        :returns: List of tuples with each tuple element having the configured Python target type.
+        """
+
+        cast = self._resultset_cast
+        if cast:
+            converters = self._resultset_converters
+            return [tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
+        else:
+            return [tuple(value for value in row) for row in rows]
+
+    def convert_row(self, row: asyncpg.Record) -> tuple[Any, ...]:
+        """
+        Converts columns in the PostgreSQL result-set to their corresponding Python target types.
+
+        :param row: A single row returned by PostgreSQL.
+        :returns: A tuple with each tuple element having the configured Python target type.
+        """
+
+        cast = self._resultset_cast
+        if cast:
+            converters = self._resultset_converters
+            return tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
+        else:
+            return tuple(value for value in row)
+
+    def convert_value(self, value: Any) -> Any:
+        """
+        Converts a single PostgreSQL value to its corresponding Python target type.
+
+        :param value: A single value returned by PostgreSQL.
+        :returns: A converted value having the configured Python target type.
+        """
+
+        return self._resultset_converters[0](value) if value is not None and self._resultset_cast else value
 
     @abstractmethod
     def query(self) -> str:
@@ -388,8 +624,8 @@ if sys.version_info >= (3, 14):
         A SQL query specified with the Python t-string syntax.
         """
 
-        strings: tuple[str, ...]
-        placeholders: tuple[_SQLPlaceholder, ...]
+        _strings: tuple[str, ...]
+        _placeholders: tuple[_SQLPlaceholder, ...]
 
         def __init__(
             self,
@@ -408,7 +644,7 @@ if sys.version_info >= (3, 14):
                 if not isinstance(ip.value, int):
                     raise TypeError(f"interpolation `{ip.expression}` expected to evaluate to an integer")
 
-            self.strings = template.strings
+            self._strings = template.strings
 
             if len(self.parameter_data_types) > 0:
 
@@ -418,16 +654,16 @@ if sys.version_info >= (3, 14):
                         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)
+                self._placeholders = tuple(_to_placeholder(ip) for ip in template.interpolations)
             else:
-                self.placeholders = ()
+                self._placeholders = ()
 
         def query(self) -> str:
             buf = StringIO()
-            for s, p in zip(self.strings[:-1], self.placeholders, strict=True):
+            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])
+            buf.write(self._strings[-1])
             return buf.getvalue()
 
 else:
@@ -439,7 +675,7 @@ class _SQLString(_SQLObject):
     A SQL query specified as a plain string (e.g. f-string).
     """
 
-    sql: str
+    _sql: str
 
     def __init__(
         self,
@@ -449,10 +685,10 @@ class _SQLString(_SQLObject):
         resultset: tuple[TargetType, ...],
     ) -> None:
         super().__init__(args, resultset)
-        self.sql = sql
+        self._sql = sql
 
     def query(self) -> str:
-        return self.sql
+        return self._sql
 
 
 class _SQL(Protocol):
@@ -461,80 +697,69 @@ class _SQL(Protocol):
     """
 
 
-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
+    _sql: _SQLObject
 
     def __init__(self, sql: _SQLObject) -> None:
-        self.sql = sql
+        self._sql = sql
 
     def __str__(self) -> str:
-        return str(self.sql)
+        return str(self._sql)
 
     def __repr__(self) -> str:
-        return repr(self.sql)
+        return repr(self._sql)
 
     async def _prepare(self, connection: Connection) -> PreparedStatement:
-        stmt = await connection.prepare(self.sql.query())
+        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.schema, attr.type.name, data_type):
-                raise TypeError(f"expected: {data_type} in column `{attr.name}`; got: `{attr.type.kind}` of `{attr.type.name}`")
+        verifier = _TypeVerifier(connection)
+        for param, placeholder in zip(stmt.get_parameters(), self._sql.parameter_data_types, strict=True):
+            await verifier.check_data_type(f"parameter ${placeholder.ordinal}", param, placeholder.data_type)
+        for attr, data_type in zip(stmt.get_attributes(), self._sql.resultset_data_types, strict=True):
+            await verifier.check_data_type(f"column `{attr.name}`", attr.type, data_type)
 
         return stmt
 
     async def execute(self, connection: asyncpg.Connection, *args: Any) -> None:
-        await connection.execute(self.sql.query(), *args)
+        await connection.execute(self._sql.query(), *self._sql.convert_arg_list(args))
 
     async def executemany(self, connection: asyncpg.Connection, args: Iterable[Sequence[Any]]) -> None:
         stmt = await self._prepare(connection)
-        await stmt.executemany(args)
+        await stmt.executemany(self._sql.convert_arg_lists(args))
 
     def _cast_fetch(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
-        cast = self.sql.cast
-        if cast:
-            converters = self.sql.converters
-            resultset = [tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
-        else:
-            resultset = [tuple(value for value in row) for row in rows]
-        self.sql.check_rows(resultset)
+        resultset = self._sql.convert_rows(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)
+        rows = await stmt.fetch(*self._sql.convert_arg_list(args))
         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)
+        rows = await stmt.fetchmany(self._sql.convert_arg_lists(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)
+        row = await stmt.fetchrow(*self._sql.convert_arg_list(args))
         if row is None:
             return None
-        cast = self.sql.cast
-        if cast:
-            converters = self.sql.converters
-            resultset = tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
-        else:
-            resultset = tuple(value for value in row)
-        self.sql.check_row(resultset)
+        resultset = self._sql.convert_row(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)
-        result = self.sql.converters[0](value) if value is not None and self.sql.cast else value
-        self.sql.check_value(result)
+        value = await stmt.fetchval(*self._sql.convert_arg_list(args))
+        result = self._sql.convert_value(value)
+        self._sql.check_value(result)
         return result
 
 
@@ -547,9 +772,7 @@ R2 = TypeVar("R2")
 RX = TypeVarTuple("RX")
 
 
-### START OF AUTO-GENERATED BLOCK ###
-
-
+### START OF AUTO-GENERATED BLOCK FOR Protocol ###
 class SQL_P0(Protocol):
     @abstractmethod
     async def execute(self, connection: Connection) -> None: ...
@@ -598,52 +821,116 @@ class SQL_RX_PX(SQL_PX[Unpack[PX]], Protocol[RT, Unpack[PX]]):
     async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> RT | None: ...
 
 
-@overload
-def sql(stmt: SQLExpression) -> SQL_P0: ...
-@overload
-def sql(stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
-
-
-### END OF AUTO-GENERATED BLOCK ###
-
-
-def sql(
-    stmt: SQLExpression,
-    *,
-    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.
+### END OF AUTO-GENERATED BLOCK FOR Protocol ###
+
 
-    :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`).
+class SQLFactory:
     """
+    Creates type-safe SQL queries.
+    """
+
+    ### START OF AUTO-GENERATED BLOCK FOR sql ###
+    @overload
+    def sql(self, stmt: SQLExpression) -> SQL_P0: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
+
+    ### END OF AUTO-GENERATED BLOCK FOR sql ###
+
+    def sql(self, stmt: SQLExpression, *, 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 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`).
+        """
+
+        input_data_types, output_data_types = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+
+        obj: _SQLObject
+        if sys.version_info >= (3, 14):
+            match stmt:
+                case Template():
+                    obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types)
+                case str():
+                    obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+        else:
+            obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+
+        return _SQLImpl(obj)
+
+    ### START OF AUTO-GENERATED BLOCK FOR unsafe_sql ###
+    @overload
+    def unsafe_sql(self, stmt: str) -> SQL_P0: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1]) -> SQL_PX[P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
+
+    ### END OF AUTO-GENERATED BLOCK FOR unsafe_sql ###
+
+    def unsafe_sql(self, stmt: str, *, 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 from a string.
+
+        This offers an alternative to the function :func:`sql` when we want to prevent the type checker from enforcing
+        a string literal, e.g. when we want to embed a variable as the table name to dynamically create a SQL statement.
+
+        :param stmt: SQL statement as a string (or f-string).
+        :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`).
+        """
+
+        input_data_types, output_data_types = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+        return _SQLImpl(obj)
+
+
+def _sql_args_resultset(*, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None) -> tuple[tuple[Any, ...], tuple[Any, ...]]:
+    "Parses an argument/resultset signature into input/output types."
 
     if args is not None and arg is not None:
         raise TypeError("expected: either `args` or `arg`; got: both")
@@ -668,14 +955,10 @@ def sql(
     else:
         output_data_types = ()
 
-    if sys.version_info >= (3, 14):
-        obj: _SQLObject
-        match stmt:
-            case Template():
-                obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types)
-            case str():
-                obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
-    else:
-        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+    return input_data_types, output_data_types
+
+
+FACTORY: SQLFactory = SQLFactory()
 
-    return _SQLImpl(obj)
+sql = FACTORY.sql
+unsafe_sql = FACTORY.unsafe_sql

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.2
+Version: 0.1.3
 Summary: Type-safe queries for asyncpg
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -113,6 +113,8 @@ def sql(
 ) -> _SQL: ...
 ```
 
+#### Parameters to factory function
+
 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`:
@@ -127,24 +129,62 @@ 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 `tuple` of several types `Px` or `Rx`, each of which may be any of the following:
+The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`.
+
+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.
+
+#### Argument and resultset types
+
+When passing Python types via the parameters `args` and `resultset`, each type may be any of the following:
 
 * (required) simple type
 * optional simple type (`T | None`)
+* special union type
 
 Simple types include:
 
 * `bool`
-* `int`
-* `float`
-* `decimal.Decimal`
-* `datetime.date`
-* `datetime.time`
-* `datetime.datetime`
+* numeric types:
+    * `int`
+    * `float`
+    * `decimal.Decimal`
+* date and time types:
+    * `datetime.date`
+    * `datetime.time`
+    * `datetime.datetime`
+    * `datetime.timedelta`
 * `str`
 * `bytes`
 * `uuid.UUID`
-* a user-defined class that derives from `StrEnum`
+* types defined in the module [ipaddress](https://docs.python.org/3/library/ipaddress.html):
+    * `ipaddress.IPv4Address`
+    * `ipaddress.IPv6Address`
+    * `ipaddress.IPv4Network`
+    * `ipaddress.IPv6Network`
+* [asyncpg representations](https://magicstack.github.io/asyncpg/current/api/index.html#module-asyncpg.types) of PostgreSQL geometric types:
+    * `asyncpg.Point`
+    * `asyncpg.Line`
+    * `asyncpg.LineSegment`
+    * `asyncpg.Box`
+    * `asyncpg.Path`
+    * `asyncpg.Polygon`
+    * `asyncpg.Circle`
+* concrete types of [asyncpg.Range](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.types.Range):
+    * `asyncpg.Range[int]`
+    * `asyncpg.Range[Decimal]`
+    * `asyncpg.Range[date]`
+    * `asyncpg.Range[datetime]`
+* a user-defined enumeration class that derives from `StrEnum`
+
+Custom Python types corresponding to PostgreSQL scalar or [composite types](https://www.postgresql.org/docs/current/rowtypes.html) are permitted. These types need to be pre-registered with [set_type_codec](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.connection.Connection.set_type_codec) passing an encoder, a decoder and typically `format="tuple"`.
+
+In general, union types are not allowed. However, there are notable exceptions. Special union types are as follows:
+
+* `JsonType` to represent an object reconstructed from a JSON string
+* `IPv4Address | IPv6Address` to denote either an IPv4 or IPv6 address
+* `IPv4Network | IPv6Network` to denote either an IPv4 or IPv6 network definition
 
 Types are grouped together with `tuple`:
 
@@ -152,39 +192,74 @@ Types are grouped together with `tuple`:
 tuple[bool, int, str | None]
 ```
 
-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`.
+Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types. When there are multiple options separated by a slash, either of the types can be specified as a source or target type.
 
-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.
+| PostgreSQL type              | Python type                        |
+| ---------------------------- | ---------------------------------- |
+| `bool`                       | `bool`                             |
+| `smallint`                   | `int`                              |
+| `integer`                    | `int`                              |
+| `bigint`                     | `int`                              |
+| `real`/`float4`              | `float`                            |
+| `double`/`float8`            | `float`                            |
+| `decimal`/`numeric`          | `Decimal`                          |
+| `date`                       | `date`                             |
+| `time`                       | `time` (naive)                     |
+| `timetz`                     | `time` (tz)                        |
+| `timestamp`                  | `datetime` (naive)                 |
+| `timestamptz`                | `datetime` (tz)                    |
+| `interval`                   | `timedelta`                        |
+| `char(N)`                    | `str`                              |
+| `varchar(N)`                 | `str`                              |
+| `text`                       | `str`                              |
+| `bytea`                      | `bytes`                            |
+| `uuid`                       | `UUID`                             |
+| `cidr`                       | `IPvXNetwork`                      |
+| `inet`                       | `IPvXNetwork`/`IPvXAddress`        |
+| `macaddr`                    | `str`                              |
+| `macaddr8`                   | `str`                              |
+| `json`                       | `str`/`JsonType`                   |
+| `jsonb`                      | `str`/`JsonType`                   |
+| `xml`                        | `str`                              |
+| any enumeration type         | `E: StrEnum`                       |
+| `point`                      | `asyncpg.Point`                    |
+| `line`                       | `asyncpg.Line`                     |
+| `lseg`                       | `asyncpg.LineSegment`              |
+| `box`                        | `asyncpg.Box`                      |
+| `path`                       | `asyncpg.Path`                     |
+| `polygon`                    | `asyncpg.Polygon`                  |
+| `circle`                     | `asyncpg.Circle`                   |
+| `int4range`                  | `asyncpg.Range[int]`               |
+| `int8range`                  | `asyncpg.Range[int]`               |
+| `numrange`                   | `asyncpg.Range[Decimal]`           |
+| `tsrange`                    | `asyncpg.Range[datetime]` (naive)  |
+| `tstzrange`                  | `asyncpg.Range[datetime]` (tz)     |
+| `daterange`                  | `asyncpg.Range[date]`              |
+
+
+PostgreSQL types `json` and `jsonb` are [returned by asyncpg](https://magicstack.github.io/asyncpg/current/usage.html#type-conversion) as Python type `str`. However, if we specify the union type `JsonType` in `args` or `resultset`, the JSON string is parsed as if by calling `json.loads()`. If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
+
+`JsonType` is defined in the module `asyncpg_typed` as follows:
 
-Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types. When there are multiple options separated by a slash, either of the types can be specified as a source or target type.
+```python
+JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
+```
+
+`IPvXNetwork` is a shorthand for either of the following:
+
+* `IPv4Network`
+* `IPv6Network`
+* their union type `IPv4Network | IPv6Network`
 
-| 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)    |
-| `interval`        | `timedelta`        |
-| `char(N)`         | `str`              |
-| `varchar(N)`      | `str`              |
-| `text`            | `str`              |
-| `bytea`           | `bytes`            |
-| `json`            | `str`/`JsonType`   |
-| `jsonb`           | `str`/`JsonType`   |
-| `xml`             | `str`              |
-| `uuid`            | `UUID`             |
-| enumeration       | `E: StrEnum`       |
-
-PostgreSQL types `json` and `jsonb` are [returned by asyncpg](https://magicstack.github.io/asyncpg/current/usage.html#type-conversion) as Python type `str`. However, if we specify the union type `JsonType` in `args` or `resultset`, the JSON string is parsed as if by calling `json.loads()`. (`JsonType` is defined in the module `asyncpg_typed`.) If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
+`IPvXAddress` stands for either of the following:
+
+* `IPv4Address`
+* `IPv6Address`
+* their union type `IPv4Address | IPv6Address`
+
+#### SQL statement as an f-string
+
+In addition to the `sql` function, SQL objects can be created with the functionally identical `unsafe_sql` function. As opposed to its safer alternative, the first parameter of `unsafe_sql` has the plain type `str`, allowing us to pass an f-string. This can prove useful if we want to inject the value of a Python variable at location where binding parameters are not permitted by PostgreSQL syntax, e.g. substitute the name of a database table to dynamically create a SQL statement.
 
 ### Using a SQL object
 
@@ -207,7 +282,12 @@ async def fetchval(self, connection: Connection, *args: *P) -> R1: ...
 
 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. If the expected and actual signatures don't match, an exception `TypeMismatchError` (subclass of `TypeError`) is raised.
+
+The set of values for an enumeration type is validated when a prepared statement is created. The string values declared in a Python `StrEnum` are compared against the values listed in PostgreSQL `CREATE TYPE ... AS ENUM` by querying the system table `pg_enum`. If there are missing or extra values on either side, an exception `EnumMismatchError` (subclass of `TypeError`) is raised.
 
-## Run-time behavior
+Unfortunately, PostgreSQL doesn't propagate nullability via prepared statements: resultset types that are declared as required (e.g. `T` as opposed to `T | None`) are validated at run time. When a `None` value is encountered for a required type, an exception `NoneTypeError` (subclass of `TypeError`) is raised.
 
-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.
+PostgreSQL doesn't differentiate between IPv4 and IPv6 network definitions, or IPv4 and IPv6 addresses in the types `cidr` and `inet`. This means that semantically a union type is returned. If you specify a more restrictive type, the resultset data is validated dynamically at run time.

asyncpg_typed-0.1.3.dist-info/RECORD

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

asyncpg_typed-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-asyncpg_typed/__init__.py,sha256=Z9UqmIr2QcSpGe7qC-ddMDDkwnJSGg5mm1dqiWPKYQM,24915
-asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-asyncpg_typed-0.1.2.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
-asyncpg_typed-0.1.2.dist-info/METADATA,sha256=9wNzfDUQWAOhedM3g3cx_TYYlaaDjlqTrNq1qEqcK0k,9932
-asyncpg_typed-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-asyncpg_typed-0.1.2.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
-asyncpg_typed-0.1.2.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-asyncpg_typed-0.1.2.dist-info/RECORD,,