iceaxe 0.12.0.dev1__tar.gz → 0.12.2__tar.gz

{iceaxe-0.12.0.dev1/iceaxe.egg-info → iceaxe-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iceaxe
-Version: 0.12.0.dev1
+Version: 0.12.2
 Summary: A modern, fast ORM for Python.
 Author-email: Pierce Freeman <pierce@freeman.vc>
 Requires-Python: >=3.11
@@ -76,6 +76,29 @@ class Person(TableBase):
     age: int
 ```
 
+Structured JSON values and lightweight scalar subclasses also work naturally in table definitions:
+
+```python
+from iceaxe import Field, TableBase
+from pydantic import BaseModel
+from uuid import UUID
+
+class PersonId(UUID):
+    pass
+
+class Preferences(BaseModel):
+    theme: str
+    notifications: bool
+
+class Person(TableBase):
+    id: PersonId = Field(primary_key=True)
+    preferences: Preferences = Field(is_json=True)
+```
+
+`Field(is_json=True)` will round-trip Pydantic models through a JSON column, and simple subclasses of
+types like `UUID`, `str`, `int`, `date`, and `datetime` are stored using their base Postgres type while
+being returned as their subclass in Python.
+
 Okay now you have a model. How do you interact with it?
 
 Databases are based on a few core primitives to insert data, update it, and fetch it out again.
@@ -120,6 +143,9 @@ For local development or side projects, you can use `magic_migrate` to automatic
 await conn.magic_migrate("my_project")
 ```
 
+If you want to limit the sync to a subset of tables or label the generated revision, you can also pass
+`models=[...]` and `message="..."`.
+
 This will:
 1. Compare your current database schema against your model definitions
 2. Generate a migration file if changes are detected
@@ -243,6 +269,28 @@ results = await conn.exec(query)
 
 As expected this will deliver results - and typehint - as a `list[tuple[int, FavoriteColor]]`
 
+For the common "fetch the first matching model or fail" case, use `.one()`:
+
+```python
+from iceaxe import NoObjectFound
+
+try:
+    person = await conn.exec(
+        select(Person)
+        .where(Person.id == 1)
+        .one()
+    )
+except NoObjectFound:
+    person = None
+```
+
+`.one()` only applies to a single full-model select like `select(Person)`. It adds `LIMIT 1`,
+returns a single `Person` instead of `list[Person]`, and raises `NoObjectFound` if the query
+returns no rows.
+
+When a query fails, Iceaxe raises `IceaxeQueryError` with the SQL text and variables attached to
+the exception message while still preserving the original asyncpg exception type.
+
 ## Production
 
 Note that underlying Postgres connection wrapped by `conn` will be alive for as long as your object is in memory. This uses up one

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/README.md

@@ -62,6 +62,29 @@ class Person(TableBase):
     age: int
 ```
 
+Structured JSON values and lightweight scalar subclasses also work naturally in table definitions:
+
+```python
+from iceaxe import Field, TableBase
+from pydantic import BaseModel
+from uuid import UUID
+
+class PersonId(UUID):
+    pass
+
+class Preferences(BaseModel):
+    theme: str
+    notifications: bool
+
+class Person(TableBase):
+    id: PersonId = Field(primary_key=True)
+    preferences: Preferences = Field(is_json=True)
+```
+
+`Field(is_json=True)` will round-trip Pydantic models through a JSON column, and simple subclasses of
+types like `UUID`, `str`, `int`, `date`, and `datetime` are stored using their base Postgres type while
+being returned as their subclass in Python.
+
 Okay now you have a model. How do you interact with it?
 
 Databases are based on a few core primitives to insert data, update it, and fetch it out again.
@@ -106,6 +129,9 @@ For local development or side projects, you can use `magic_migrate` to automatic
 await conn.magic_migrate("my_project")
 ```
 
+If you want to limit the sync to a subset of tables or label the generated revision, you can also pass
+`models=[...]` and `message="..."`.
+
 This will:
 1. Compare your current database schema against your model definitions
 2. Generate a migration file if changes are detected
@@ -229,6 +255,28 @@ results = await conn.exec(query)
 
 As expected this will deliver results - and typehint - as a `list[tuple[int, FavoriteColor]]`
 
+For the common "fetch the first matching model or fail" case, use `.one()`:
+
+```python
+from iceaxe import NoObjectFound
+
+try:
+    person = await conn.exec(
+        select(Person)
+        .where(Person.id == 1)
+        .one()
+    )
+except NoObjectFound:
+    person = None
+```
+
+`.one()` only applies to a single full-model select like `select(Person)`. It adds `LIMIT 1`,
+returns a single `Person` instead of `list[Person]`, and raises `NoObjectFound` if the query
+returns no rows.
+
+When a query fails, Iceaxe raises `IceaxeQueryError` with the SQL text and variables attached to
+the exception message while still preserving the original asyncpg exception type.
+
 ## Production
 
 Note that underlying Postgres connection wrapped by `conn` will be alive for as long as your object is in memory. This uses up one

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/__tests__/conftest.py

@@ -1,4 +1,5 @@
 import logging
+import os
 
 import asyncpg
 import pytest
@@ -20,7 +21,9 @@ def docker_postgres():
     This allows running individual tests without needing Docker Compose.
     """
     # Create and start a PostgreSQL container
-    postgres_container = docker_helpers.PostgresContainer()
+    postgres_container = docker_helpers.PostgresContainer(
+        postgres_version=os.environ.get("ICEAXE_POSTGRES_VERSION", "16")
+    )
 
     # Start the container and yield connection details
     connection_info = postgres_container.start()
@@ -194,6 +197,13 @@ async def clear_all_database_objects(db_connection: DBConnection):
     )
 
 
+@pytest_asyncio.fixture
+async def postgres_server_version_num(db_connection: DBConnection) -> int:
+    server_version_value = await db_connection.conn.fetchval("SHOW server_version_num")
+    assert server_version_value is not None
+    return int(server_version_value)
+
+
 @pytest.fixture
 def clear_registry():
     current_registry = DBModelMetaclass._registry

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/__tests__/schemas/test_db_memory_serializer.py

@@ -8,6 +8,7 @@ from uuid import UUID
 import pytest
 from pydantic import BaseModel, create_model
 from pydantic.fields import FieldInfo
+from typing_extensions import TypedDict
 
 from iceaxe import Field, TableBase
 from iceaxe.base import IndexConstraint, UniqueConstraint
@@ -1656,3 +1657,27 @@ def test_pydantic_model_json_field(clear_all_database_objects):
 
     assert settings_column.column_type == ColumnType.JSON
     assert not settings_column.nullable
+
+
+def test_json_container_fields_use_json_column(clear_all_database_objects):
+    class ExampleOption(TypedDict):
+        key: str
+        label: str
+
+    class TestModel(TableBase):
+        id: int = Field(primary_key=True)
+        settings: dict = Field(is_json=True)
+        tags: list[str] = Field(is_json=True)
+        option: ExampleOption = Field(is_json=True)
+        options: list[ExampleOption] = Field(is_json=True)
+
+    migrator = DatabaseMemorySerializer()
+    db_objects = list(migrator.delegate([TestModel]))
+
+    columns = [obj for obj, _ in db_objects if isinstance(obj, DBColumn)]
+
+    for column_name in {"settings", "tags", "option", "options"}:
+        column = next(c for c in columns if c.column_name == column_name)
+        assert column.column_type == ColumnType.JSON
+        assert column.column_is_list is False
+        assert not column.nullable

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/__tests__/schemas/test_db_serializer.py

@@ -241,6 +241,61 @@ async def test_simple_db_serializer(
     compare_db_objects(db_objects, base_db_objects + expected_db_objects)
 
 
+@pytest.mark.asyncio
+async def test_db_serializer_ignores_postgres_not_null_constraints(
+    db_connection: DBConnection,
+    clear_all_database_objects,
+    postgres_server_version_num: int,
+):
+    await db_connection.conn.execute(
+        """
+        CREATE TABLE pg18_not_null_model (
+            id SERIAL PRIMARY KEY,
+            required_value TEXT NOT NULL,
+            optional_value TEXT
+        );
+        """
+    )
+
+    pg_constraint_rows = await db_connection.conn.fetch(
+        """
+        SELECT c.contype
+        FROM pg_constraint c
+        INNER JOIN pg_class t ON c.conrelid = t.oid
+        WHERE t.relname = $1
+        """,
+        "pg18_not_null_model",
+    )
+    pg_constraint_types = {
+        DatabaseSerializer._unwrap_db_str(row["contype"]) for row in pg_constraint_rows
+    }
+
+    if postgres_server_version_num >= 180000:
+        assert "n" in pg_constraint_types
+
+    db_serializer = DatabaseSerializer()
+    db_objects = []
+    async for values in db_serializer.get_objects(db_connection):
+        db_objects.append(values)
+
+    table_constraints = [
+        obj
+        for obj, _ in db_objects
+        if isinstance(obj, DBConstraint) and obj.table_name == "pg18_not_null_model"
+    ]
+    assert {constraint.constraint_name for constraint in table_constraints} == {
+        "pg18_not_null_model_pkey"
+    }
+
+    columns = {
+        obj.column_name: obj
+        for obj, _ in db_objects
+        if isinstance(obj, DBColumn) and obj.table_name == "pg18_not_null_model"
+    }
+    assert columns["required_value"].nullable is False
+    assert columns["optional_value"].nullable is True
+
+
 @pytest.mark.asyncio
 async def test_db_serializer_foreign_key(
     db_connection: DBConnection,

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/__tests__/test_base.py

@@ -1,11 +1,15 @@
+from enum import StrEnum
 from typing import Annotated, Any, Generic, TypeVar, cast
 from uuid import UUID
 
+import pytest
+
 from iceaxe.base import (
     DBModelMetaclass,
     TableBase,
 )
 from iceaxe.field import DBFieldInfo, Field
+from iceaxe.schemas.db_memory_serializer import DatabaseMemorySerializer
 
 
 class _AnnotatedDummy:
@@ -42,6 +46,28 @@ def test_not_autodetect_generic(clear_registry):
     assert DBModelMetaclass.get_registry() == [WillAutodetect]
 
 
+def test_generic_concrete_subclass_preserves_bound_annotations(clear_registry):
+    T = TypeVar("T", bound=StrEnum)
+
+    class MyEnum(StrEnum):
+        A = "A"
+
+    class GenericBase(TableBase, Generic[T], autodetect=False):
+        typed_value: T
+        user_id: UUID
+
+    class Concrete(GenericBase[MyEnum], TableBase):
+        pass
+
+    assert {
+        key: info.annotation for key, info in Concrete.get_client_fields().items()
+    } == {
+        "typed_value": MyEnum,
+        "user_id": UUID,
+    }
+    assert list(DatabaseMemorySerializer().delegate([Concrete]))
+
+
 def test_model_fields():
     class User(TableBase):
         id: int
@@ -118,3 +144,22 @@ def test_model_fields_with_simple_uuid_subclass():
     assert isinstance(event.id, CustomUUID)
     assert isinstance(event.maybe_id, CustomUUID)
     assert all(isinstance(value, CustomUUID) for value in event.ids)
+
+
+def test_metaclass_resets_construction_state_after_model_error(clear_registry):
+    class BrokenType:
+        @classmethod
+        def __get_pydantic_core_schema__(cls, source_type, handler):
+            raise RuntimeError("boom")
+
+    with pytest.raises(RuntimeError, match="boom"):
+
+        class BrokenModel(TableBase, autodetect=False):
+            value: BrokenType
+
+    assert DBModelMetaclass.is_constructing is False
+
+    class WorkingModel(TableBase, autodetect=False):
+        id: int
+
+    assert cast(Any, WorkingModel).id.key == "id"

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/__tests__/test_session.py

@@ -9,6 +9,7 @@ import asyncpg
 import pytest
 from asyncpg.connection import Connection
 from pydantic import BaseModel
+from typing_extensions import TypedDict
 
 from iceaxe.__tests__.conf_models import (
     ArtifactDemo,
@@ -728,6 +729,39 @@ async def test_pydantic_json_deserialization_from_database(
     ]
 
 
+@pytest.mark.asyncio
+async def test_typed_dict_json_round_trip(db_connection: DBConnection):
+    class ExampleOption(TypedDict):
+        key: str
+        label: str
+
+    class TypedDictJsonDemo(TableBase):
+        id: int | None = Field(primary_key=True, default=None)
+        options: list[ExampleOption] = Field(is_json=True)
+
+    await db_connection.conn.execute("DROP TABLE IF EXISTS typeddictjsondemo")
+    await create_all(db_connection, [TypedDictJsonDemo])
+
+    options: list[ExampleOption] = [
+        {"key": "option_a", "label": "Option A"},
+        {"key": "option_b", "label": "Option B"},
+    ]
+    demo = TypedDictJsonDemo(options=options)
+    await db_connection.insert([demo])
+
+    full_result = await db_connection.exec(
+        QueryBuilder().select(TypedDictJsonDemo).where(TypedDictJsonDemo.id == demo.id)
+    )
+    assert full_result == [TypedDictJsonDemo(id=demo.id, options=options)]
+
+    column_result = await db_connection.exec(
+        QueryBuilder()
+        .select(TypedDictJsonDemo.options)
+        .where(TypedDictJsonDemo.id == demo.id)
+    )
+    assert column_result == [options]
+
+
 @pytest.mark.asyncio
 async def test_get(db_connection: DBConnection):
     """

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/base.py

@@ -70,9 +70,11 @@ class DBModelMetaclass(_model_construction.ModelMetaclass):
         raw_kwargs = {**kwargs}
 
         mcs.is_constructing = True
-        autodetect = mcs._extract_kwarg(kwargs, "autodetect", True)
-        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
-        mcs.is_constructing = False
+        try:
+            autodetect = mcs._extract_kwarg(kwargs, "autodetect", True)
+            cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+        finally:
+            mcs.is_constructing = False
 
         # Allow future calls to subclasses / generic instantiations to reference the same
         # kwargs as the base class

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/field.py

@@ -167,7 +167,20 @@ class DBFieldInfo(FieldInfo):
             db_kwargs["autoincrement"] = autoincrement
 
         kwargs = cast(DBFieldInputs, {**field_attributes, **db_kwargs})
-        return cls(**kwargs)
+        extended_field = cls(**kwargs)
+
+        # Preserve Pydantic's internal rebuild state so generic specializations can
+        # recreate inherited fields from their original annotations.
+        for attr_name in getattr(FieldInfo, "__slots__", ()):
+            value = getattr(field, attr_name)
+            if attr_name in {"metadata", "_attributes_set", "_qualifiers"}:
+                value = value.copy()
+            setattr(extended_field, attr_name, value)
+
+        extended_field._attributes_set.update(
+            {key: value for key, value in db_kwargs.items() if value is not _Unset}
+        )
+        return extended_field
 
     def to_db_value(self, value: Any):
         if self.is_json:

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/schemas/db_memory_serializer.py

@@ -50,8 +50,8 @@ from iceaxe.sql_types import enum_to_name
 from iceaxe.typing import (
     ALL_ENUM_TYPES,
     DATE_TYPES,
-    JSON_WRAPPER_FALLBACK,
     PRIMITIVE_WRAPPER_TYPES,
+    is_json_container_type,
     resolve_typehint,
 )
 
@@ -435,14 +435,26 @@ class DatabaseHandler:
         # Resolve the type of the column, if generic
         if isinstance(storage_annotation, TypeVar):
             typevar_map = get_typevar_mapping(table)
-            storage_annotation = typevar_map[storage_annotation]
-            resolved_annotation = resolve_typehint(storage_annotation)
+            annotation = typevar_map[storage_annotation]
+            resolved_annotation = resolve_typehint(annotation)
             storage_annotation = (
                 get_simple_subclass_base_type(resolved_annotation.runtime_type)
                 or resolved_annotation.runtime_type
             )
             is_list = resolved_annotation.is_list
 
+        # JSON-backed fields should remain JSON even when their annotation is a
+        # top-level list container such as `list[str]` or `list[TypedDict]`.
+        if info.is_json and (
+            is_type_compatible(annotation, BaseModel)
+            or is_json_container_type(annotation)
+            or is_type_compatible(storage_annotation, BaseModel)
+            or is_json_container_type(storage_annotation)
+        ):
+            return TypeDeclarationResponse(
+                primitive_type=ColumnType.JSON,
+            )
+
         # Should be prioritized in terms of MRO; StrEnums should be processed
         # before the str types
         if is_type_compatible(storage_annotation, ALL_ENUM_TYPES):
@@ -514,7 +526,7 @@ class DatabaseHandler:
                     f"Pydantic model fields must have Field(is_json=True) specified: {storage_annotation}\n"
                     f"Column: {table.__name__}.{key}"
                 )
-        elif is_type_compatible(storage_annotation, JSON_WRAPPER_FALLBACK):
+        elif is_json_container_type(storage_annotation):
             if info.is_json:
                 return TypeDeclarationResponse(
                     primitive_type=ColumnType.JSON,

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/schemas/db_serializer.py

@@ -29,6 +29,13 @@ class DatabaseSerializer:
 
     """
 
+    pg_constraint_type_map = {
+        "p": ConstraintType.PRIMARY_KEY,
+        "f": ConstraintType.FOREIGN_KEY,
+        "u": ConstraintType.UNIQUE,
+        "c": ConstraintType.CHECK,
+    }
+
     def __init__(self, ignore_tables: list[str] | None = None):
         # Internal tables used for migration management, shouldn't be managed in-memory and therefore
         # won't be mirrored by our DBMemorySerializer. We exclude them from this serialization lest there
@@ -52,6 +59,20 @@ class DatabaseSerializer:
 
         raise ValueError(f"Unexpected type for database value: {type(value)}")
 
+    def _pg_constraint_type(
+        self, value: str | bytes | bytearray | memoryview
+    ) -> ConstraintType | None:
+        contype = self._unwrap_db_str(value)
+        if contype == "n":
+            # PostgreSQL 18 reports NOT NULL as pg_constraint rows. Iceaxe
+            # serializes nullability from information_schema.columns instead.
+            return None
+
+        try:
+            return self.pg_constraint_type_map[contype]
+        except KeyError:
+            raise ValueError(f"Unknown constraint type: {value}") from None
+
     async def get_objects(self, connection: DBConnection):
         tables = []
         async for table, dependencies in self.get_tables(connection):
@@ -156,18 +177,9 @@ class DatabaseSerializer:
         """
         result = await session.conn.fetch(query, table_name)
         for row in result:
-            contype = self._unwrap_db_str(row["contype"])
-            # Determine type
-            if contype == "p":
-                ctype = ConstraintType.PRIMARY_KEY
-            elif contype == "f":
-                ctype = ConstraintType.FOREIGN_KEY
-            elif contype == "u":
-                ctype = ConstraintType.UNIQUE
-            elif contype == "c":
-                ctype = ConstraintType.CHECK
-            else:
-                raise ValueError(f"Unknown constraint type: {row['contype']}")
+            ctype = self._pg_constraint_type(row["contype"])
+            if ctype is None:
+                continue
 
             columns = await self.fetch_constraint_columns(
                 session, row["conkey"], table_name

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/session_optimized.c

@@ -1,4 +1,4 @@
-/* Generated by Cython 3.2.4 */
+/* Generated by Cython 3.2.5 */
 
 /* BEGIN: Cython Metadata
 {
@@ -35,8 +35,8 @@ END: Cython Metadata */
 #elif PY_VERSION_HEX < 0x03080000
     #error Cython requires Python 3.8+.
 #else
-#define __PYX_ABI_VERSION "3_2_4"
-#define CYTHON_HEX_VERSION 0x030204F0
+#define __PYX_ABI_VERSION "3_2_5"
+#define CYTHON_HEX_VERSION 0x030205F0
 #define CYTHON_FUTURE_DIVISION 1
 /* CModulePreamble */
 #include <stddef.h>
@@ -2154,22 +2154,22 @@ static int __Pyx__ArgTypeTest(PyObject *obj, PyTypeObject *type, const char *nam
         __Pyx__ArgTypeTest(obj, type, name, exact))
 
 /* TypeImport.proto */
-#ifndef __PYX_HAVE_RT_ImportType_proto_3_2_4
-#define __PYX_HAVE_RT_ImportType_proto_3_2_4
+#ifndef __PYX_HAVE_RT_ImportType_proto_3_2_5
+#define __PYX_HAVE_RT_ImportType_proto_3_2_5
 #if defined (__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
 #include <stdalign.h>
 #endif
 #if (defined (__STDC_VERSION__) && __STDC_VERSION__ >= 201112L) || __cplusplus >= 201103L
-#define __PYX_GET_STRUCT_ALIGNMENT_3_2_4(s) alignof(s)
+#define __PYX_GET_STRUCT_ALIGNMENT_3_2_5(s) alignof(s)
 #else
-#define __PYX_GET_STRUCT_ALIGNMENT_3_2_4(s) sizeof(void*)
+#define __PYX_GET_STRUCT_ALIGNMENT_3_2_5(s) sizeof(void*)
 #endif
-enum __Pyx_ImportType_CheckSize_3_2_4 {
-   __Pyx_ImportType_CheckSize_Error_3_2_4 = 0,
-   __Pyx_ImportType_CheckSize_Warn_3_2_4 = 1,
-   __Pyx_ImportType_CheckSize_Ignore_3_2_4 = 2
+enum __Pyx_ImportType_CheckSize_3_2_5 {
+   __Pyx_ImportType_CheckSize_Error_3_2_5 = 0,
+   __Pyx_ImportType_CheckSize_Warn_3_2_5 = 1,
+   __Pyx_ImportType_CheckSize_Ignore_3_2_5 = 2
 };
-static PyTypeObject *__Pyx_ImportType_3_2_4(PyObject* module, const char *module_name, const char *class_name, size_t size, size_t alignment, enum __Pyx_ImportType_CheckSize_3_2_4 check_size);
+static PyTypeObject *__Pyx_ImportType_3_2_5(PyObject* module, const char *module_name, const char *class_name, size_t size, size_t alignment, enum __Pyx_ImportType_CheckSize_3_2_5 check_size);
 #endif
 
 /* HasAttr.proto (used by ImportImpl) */
@@ -5302,7 +5302,7 @@ PyObject *__pyx_args, PyObject *__pyx_kwds
   {
     PyObject ** const __pyx_pyargnames[] = {&__pyx_mstate_global->__pyx_n_u_values,&__pyx_mstate_global->__pyx_n_u_select_raws,&__pyx_mstate_global->__pyx_n_u_select_types,0};
     const Py_ssize_t __pyx_kwds_len = (__pyx_kwds) ? __Pyx_NumKwargs_FASTCALL(__pyx_kwds) : 0;
-    if (unlikely(__pyx_kwds_len) < 0) __PYX_ERR(0, 208, __pyx_L3_error)
+    if (unlikely(__pyx_kwds_len < 0)) __PYX_ERR(0, 208, __pyx_L3_error)
     if (__pyx_kwds_len > 0) {
       switch (__pyx_nargs) {
         case  3:
@@ -5480,15 +5480,15 @@ static int __Pyx_modinit_type_import_code(__pyx_mstatetype *__pyx_mstate) {
   /*--- Type import code ---*/
   __pyx_t_1 = PyImport_ImportModule(__Pyx_BUILTIN_MODULE_NAME); if (unlikely(!__pyx_t_1)) __PYX_ERR(1, 9, __pyx_L1_error)
   __Pyx_GOTREF(__pyx_t_1);
-  __pyx_mstate->__pyx_ptype_7cpython_4type_type = __Pyx_ImportType_3_2_4(__pyx_t_1, __Pyx_BUILTIN_MODULE_NAME, "type",
+  __pyx_mstate->__pyx_ptype_7cpython_4type_type = __Pyx_ImportType_3_2_5(__pyx_t_1, __Pyx_BUILTIN_MODULE_NAME, "type",
   #if defined(PYPY_VERSION_NUM) && PYPY_VERSION_NUM < 0x050B0000
-  sizeof(PyTypeObject), __PYX_GET_STRUCT_ALIGNMENT_3_2_4(PyTypeObject),
+  sizeof(PyTypeObject), __PYX_GET_STRUCT_ALIGNMENT_3_2_5(PyTypeObject),
   #elif CYTHON_COMPILING_IN_LIMITED_API
   0, 0,
   #else
-  sizeof(PyHeapTypeObject), __PYX_GET_STRUCT_ALIGNMENT_3_2_4(PyHeapTypeObject),
+  sizeof(PyHeapTypeObject), __PYX_GET_STRUCT_ALIGNMENT_3_2_5(PyHeapTypeObject),
   #endif
-  __Pyx_ImportType_CheckSize_Warn_3_2_4); if (!__pyx_mstate->__pyx_ptype_7cpython_4type_type) __PYX_ERR(1, 9, __pyx_L1_error)
+  __Pyx_ImportType_CheckSize_Warn_3_2_5); if (!__pyx_mstate->__pyx_ptype_7cpython_4type_type) __PYX_ERR(1, 9, __pyx_L1_error)
   __Pyx_DECREF(__pyx_t_1); __pyx_t_1 = 0;
   __Pyx_RefNannyFinishContext();
   return 0;
@@ -6890,7 +6890,7 @@ bad:
 }
 
 /* dict_iter */
-#if CYTHON_COMPILING_IN_PYPY
+#if CYTHON_AVOID_BORROWED_REFS
 #include <string.h>
 #endif
 static CYTHON_INLINE PyObject* __Pyx_dict_iterator(PyObject* iterable, int is_dict, PyObject* method_name,
@@ -6898,7 +6898,7 @@ static CYTHON_INLINE PyObject* __Pyx_dict_iterator(PyObject* iterable, int is_di
     is_dict = is_dict || likely(PyDict_CheckExact(iterable));
     *p_source_is_dict = is_dict;
     if (is_dict) {
-#if !CYTHON_COMPILING_IN_PYPY
+#if !CYTHON_AVOID_BORROWED_REFS
         *p_orig_length = PyDict_Size(iterable);
         Py_INCREF(iterable);
         return iterable;
@@ -6927,7 +6927,7 @@ static CYTHON_INLINE PyObject* __Pyx_dict_iterator(PyObject* iterable, int is_di
         iterable = __Pyx_PyObject_CallMethod0(iterable, method_name);
         if (!iterable)
             return NULL;
-#if !CYTHON_COMPILING_IN_PYPY
+#if !CYTHON_AVOID_BORROWED_REFS
         if (PyTuple_CheckExact(iterable) || PyList_CheckExact(iterable))
             return iterable;
 #endif
@@ -7126,8 +7126,8 @@ bad:
     CYTHON_UNUSED_VAR(max_char);
     CYTHON_UNUSED_VAR(result_ulength);
     for (i=0; i<value_count; i++) {
-        if (__Pyx_PyTuple_SET_ITEM(value_tuple, i, values[i]) != (0)) goto bad;
         Py_INCREF(values[i]);
+        if (__Pyx_PyTuple_SET_ITEM(value_tuple, i, values[i]) != (0)) goto bad;
     }
     result = PyUnicode_Join(__pyx_mstate_global->__pyx_empty_unicode, value_tuple);
 bad:
@@ -7631,11 +7631,11 @@ __Pyx_PyTuple_FromArray(PyObject *const *src, Py_ssize_t n)
     res = PyTuple_New(n);
     if (unlikely(res == NULL)) return NULL;
     for (i = 0; i < n; i++) {
+        Py_INCREF(src[i]);
         if (unlikely(__Pyx_PyTuple_SET_ITEM(res, i, src[i]) < (0))) {
             Py_DECREF(res);
             return NULL;
         }
-        Py_INCREF(src[i]);
     }
     return res;
 }
@@ -8573,10 +8573,10 @@ static int __Pyx__ArgTypeTest(PyObject *obj, PyTypeObject *type, const char *nam
 }
 
 /* TypeImport */
-#ifndef __PYX_HAVE_RT_ImportType_3_2_4
-#define __PYX_HAVE_RT_ImportType_3_2_4
-static PyTypeObject *__Pyx_ImportType_3_2_4(PyObject *module, const char *module_name, const char *class_name,
-    size_t size, size_t alignment, enum __Pyx_ImportType_CheckSize_3_2_4 check_size)
+#ifndef __PYX_HAVE_RT_ImportType_3_2_5
+#define __PYX_HAVE_RT_ImportType_3_2_5
+static PyTypeObject *__Pyx_ImportType_3_2_5(PyObject *module, const char *module_name, const char *class_name,
+    size_t size, size_t alignment, enum __Pyx_ImportType_CheckSize_3_2_5 check_size)
 {
     PyObject *result = 0;
     Py_ssize_t basicsize;
@@ -8632,7 +8632,7 @@ static PyTypeObject *__Pyx_ImportType_3_2_4(PyObject *module, const char *module
             module_name, class_name, size, basicsize+itemsize);
         goto bad;
     }
-    if (check_size == __Pyx_ImportType_CheckSize_Error_3_2_4 &&
+    if (check_size == __Pyx_ImportType_CheckSize_Error_3_2_5 &&
             ((size_t)basicsize > size || (size_t)(basicsize + itemsize) < size)) {
         PyErr_Format(PyExc_ValueError,
             "%.200s.%.200s size changed, may indicate binary incompatibility. "
@@ -8640,7 +8640,7 @@ static PyTypeObject *__Pyx_ImportType_3_2_4(PyObject *module, const char *module
             module_name, class_name, size, basicsize, basicsize+itemsize);
         goto bad;
     }
-    else if (check_size == __Pyx_ImportType_CheckSize_Warn_3_2_4 && (size_t)basicsize > size) {
+    else if (check_size == __Pyx_ImportType_CheckSize_Warn_3_2_5 && (size_t)basicsize > size) {
         if (PyErr_WarnFormat(NULL, 0,
                 "%.200s.%.200s size changed, may indicate binary incompatibility. "
                 "Expected %zd from C header, got %zd from PyObject",
@@ -9690,7 +9690,6 @@ __Pyx_CyFunction_get_is_coroutine_value(__pyx_CyFunctionObject *op) {
         PyList_SET_ITEM(fromlist, 0, marker);
 #else
         if (unlikely(PyList_SetItem(fromlist, 0, marker) < 0)) {
-            Py_DECREF(marker);
             Py_DECREF(fromlist);
             return NULL;
         }
@@ -9931,8 +9930,7 @@ __Pyx_CyFunction_clear(__pyx_CyFunctionObject *m)
     Py_CLEAR(m->func_doc);
     Py_CLEAR(m->func_globals);
     Py_CLEAR(m->func_code);
-#if !CYTHON_COMPILING_IN_LIMITED_API
-#if PY_VERSION_HEX < 0x030900B1
+#if PY_VERSION_HEX < 0x030900B1 || CYTHON_COMPILING_IN_LIMITED_API
     Py_CLEAR(__Pyx_CyFunction_GetClassObj(m));
 #else
     {
@@ -9940,7 +9938,6 @@ __Pyx_CyFunction_clear(__pyx_CyFunctionObject *m)
         ((PyCMethodObject *) (m))->mm_class = NULL;
         Py_XDECREF(cls);
     }
-#endif
 #endif
     Py_CLEAR(m->defaults_tuple);
     Py_CLEAR(m->defaults_kwdict);
@@ -9992,11 +9989,10 @@ static int __Pyx_CyFunction_traverse(__pyx_CyFunctionObject *m, visitproc visit,
     Py_VISIT(m->func_doc);
     Py_VISIT(m->func_globals);
     __Pyx_VISIT_CONST(m->func_code);
-#if !CYTHON_COMPILING_IN_LIMITED_API
     Py_VISIT(__Pyx_CyFunction_GetClassObj(m));
-#endif
     Py_VISIT(m->defaults_tuple);
     Py_VISIT(m->defaults_kwdict);
+    Py_VISIT(m->func_annotations);
     Py_VISIT(m->func_is_coroutine);
     Py_VISIT(m->defaults);
     return 0;
@@ -10708,8 +10704,8 @@ __Pyx_PyType_GetFullyQualifiedName(PyTypeObject* tp)
 #if CYTHON_VECTORCALL
 static int __Pyx_VectorcallBuilder_AddArg(PyObject *key, PyObject *value, PyObject *builder, PyObject **args, int n) {
     (void)__Pyx_PyObject_FastCallDict;
-    if (__Pyx_PyTuple_SET_ITEM(builder, n, key) != (0)) return -1;
     Py_INCREF(key);
+    if (__Pyx_PyTuple_SET_ITEM(builder, n, key) != (0)) return -1;
     args[n] = value;
     return 0;
 }

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/iceaxe/typing.py

@@ -16,9 +16,12 @@ from typing import (
     Union,
     get_args,
     get_origin,
+    is_typeddict as stdlib_is_typeddict,
 )
 from uuid import UUID
 
+from typing_extensions import is_typeddict as extensions_is_typeddict
+
 if TYPE_CHECKING:
     from iceaxe.alias_values import Alias
     from iceaxe.base import (
@@ -140,6 +143,27 @@ def resolve_typehint(annotation: Any) -> ResolvedTypehint:
     )
 
 
+def is_json_container_type(annotation: Any) -> bool:
+    """
+    Return whether an annotation represents a JSON container shape.
+
+    Iceaxe stores `dict[...]`, `list[...]`, plain `dict` / `list`, and
+    `TypedDict` values in JSON columns when `Field(is_json=True)` is specified.
+    This helper intentionally focuses on the container forms that need special
+    schema inference without trying to classify arbitrary JSON-serializable
+    scalar types.
+
+    """
+    annotation = unwrap_annotated(annotation)
+    if annotation in {dict, list}:
+        return True
+    if stdlib_is_typeddict(annotation) or extensions_is_typeddict(annotation):
+        return True
+
+    origin = get_origin(annotation)
+    return origin in {dict, list}
+
+
 def transform_typehint(
     annotation: Any,
     transform: Callable[[Any], Any],

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2/iceaxe.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iceaxe
-Version: 0.12.0.dev1
+Version: 0.12.2
 Summary: A modern, fast ORM for Python.
 Author-email: Pierce Freeman <pierce@freeman.vc>
 Requires-Python: >=3.11
@@ -76,6 +76,29 @@ class Person(TableBase):
     age: int
 ```
 
+Structured JSON values and lightweight scalar subclasses also work naturally in table definitions:
+
+```python
+from iceaxe import Field, TableBase
+from pydantic import BaseModel
+from uuid import UUID
+
+class PersonId(UUID):
+    pass
+
+class Preferences(BaseModel):
+    theme: str
+    notifications: bool
+
+class Person(TableBase):
+    id: PersonId = Field(primary_key=True)
+    preferences: Preferences = Field(is_json=True)
+```
+
+`Field(is_json=True)` will round-trip Pydantic models through a JSON column, and simple subclasses of
+types like `UUID`, `str`, `int`, `date`, and `datetime` are stored using their base Postgres type while
+being returned as their subclass in Python.
+
 Okay now you have a model. How do you interact with it?
 
 Databases are based on a few core primitives to insert data, update it, and fetch it out again.
@@ -120,6 +143,9 @@ For local development or side projects, you can use `magic_migrate` to automatic
 await conn.magic_migrate("my_project")
 ```
 
+If you want to limit the sync to a subset of tables or label the generated revision, you can also pass
+`models=[...]` and `message="..."`.
+
 This will:
 1. Compare your current database schema against your model definitions
 2. Generate a migration file if changes are detected
@@ -243,6 +269,28 @@ results = await conn.exec(query)
 
 As expected this will deliver results - and typehint - as a `list[tuple[int, FavoriteColor]]`
 
+For the common "fetch the first matching model or fail" case, use `.one()`:
+
+```python
+from iceaxe import NoObjectFound
+
+try:
+    person = await conn.exec(
+        select(Person)
+        .where(Person.id == 1)
+        .one()
+    )
+except NoObjectFound:
+    person = None
+```
+
+`.one()` only applies to a single full-model select like `select(Person)`. It adds `LIMIT 1`,
+returns a single `Person` instead of `list[Person]`, and raises `NoObjectFound` if the query
+returns no rows.
+
+When a query fails, Iceaxe raises `IceaxeQueryError` with the SQL text and variables attached to
+the exception message while still preserving the original asyncpg exception type.
+
 ## Production
 
 Note that underlying Postgres connection wrapped by `conn` will be alive for as long as your object is in memory. This uses up one

{iceaxe-0.12.0.dev1 → iceaxe-0.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iceaxe"
-version = "0.12.0.dev1"
+version = "0.12.2"
 description = "A modern, fast ORM for Python."
 readme = "README.md"
 requires-python = ">=3.11"