Rename upsert_sql exclude -> insert_only

Author: bdowning

sql_athame/dataclasses.py

@@ -847,14 +847,14 @@ async def insert(
     def upsert_sql(
         cls,
         insert_sql: Fragment,
-        exclude: FieldNamesSet = (),
+        insert_only: FieldNamesSet = (),
         force_update: FieldNamesSet = (),
     ) -> Fragment:
         """Generate UPSERT (INSERT ... ON CONFLICT DO UPDATE) SQL.
 
         Args:
             insert_sql: Base INSERT statement Fragment
-            exclude: Field names to exclude from the UPDATE clause
+            insert_only: Field names to exclude from the UPDATE clause
             force_update: Field names to force include in UPDATE clause, overriding insert_only settings
 
         Returns:
@@ -869,22 +869,22 @@ def upsert_sql(
             Fields marked with ColumnInfo(insert_only=True) are automatically
             excluded from the UPDATE clause, unless overridden by force_update.
         """
-        # Combine exclude parameter with auto-detected insert_only fields, but remove force_update fields
+        # Combine insert_only parameter with auto-detected insert_only fields, but remove force_update fields
         auto_insert_only = cls.insert_only_field_names() - set(force_update)
-        manual_exclude = set(exclude) - set(
+        manual_insert_only = set(insert_only) - set(
             force_update
-        )  # Remove force_update from manual excludes too
-        all_exclude = manual_exclude | auto_insert_only
+        )  # Remove force_update from manual insert_only too
+        all_insert_only = manual_insert_only | auto_insert_only
         cached = cls._cached(
-            ("upsert_sql", tuple(sorted(all_exclude))),
+            ("upsert_sql", tuple(sorted(all_insert_only))),
             lambda: sql(
                 " ON CONFLICT ({pks}) DO UPDATE SET {assignments}",
                 insert_sql=insert_sql,
                 pks=sql.list(cls.primary_key_names_sql()),
                 assignments=sql.list(
                     sql("{field}=EXCLUDED.{field}", field=x)
                     for x in cls.field_names_sql(
-                        exclude=(*cls.primary_key_names, *all_exclude)
+                        exclude=(*cls.primary_key_names, *all_insert_only)
                     )
                 ),
             ).flatten(),
@@ -928,7 +928,7 @@ async def upsert(
             "{} RETURNING xmax",
             self.upsert_sql(
                 self.insert_sql(exclude=exclude),
-                exclude=update_exclude,
+                insert_only=update_exclude,
                 force_update=force_update,
             ),
         )
@@ -1173,7 +1173,7 @@ async def upsert_multiple_executemany(
         args = [r.field_values() for r in rows]
         query = cls.upsert_sql(
             cls.insert_multiple_executemany_chunk_sql(1),
-            exclude=insert_only,
+            insert_only=insert_only,
             force_update=force_update,
         ).query()[0]
         if args:
@@ -1201,7 +1201,7 @@ async def upsert_multiple_unnest(
         return await connection_or_pool.execute(
             *cls.upsert_sql(
                 cls.insert_multiple_sql(rows),
-                exclude=insert_only,
+                insert_only=insert_only,
                 force_update=force_update,
             )
         )
@@ -1233,7 +1233,7 @@ async def upsert_multiple_array_safe(
             last = await connection_or_pool.execute(
                 *cls.upsert_sql(
                     cls.insert_multiple_array_safe_sql(chunk),
-                    exclude=insert_only,
+                    insert_only=insert_only,
                     force_update=force_update,
                 )
             )

tests/test_dataclasses.py

@@ -177,7 +177,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
     t = Test(1, 42, "str", "2023-01-01")
 
     # Test with insert_only parameter - created_at should be excluded from UPDATE
-    assert list(t.upsert_sql(t.insert_sql(), exclude={"created_at"})) == [
+    assert list(t.upsert_sql(t.insert_sql(), insert_only={"created_at"})) == [
         'INSERT INTO "table" ("id", "foo", "bar", "created_at") VALUES ($1, $2, $3, $4) '
         'ON CONFLICT ("id") DO UPDATE SET "foo"=EXCLUDED."foo", "bar"=EXCLUDED."bar"',
         1,
@@ -187,7 +187,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
     ]
 
     # Test with both exclude and insert_only-style exclude
-    assert list(t.upsert_sql(t.insert_sql(), exclude={"bar", "created_at"})) == [
+    assert list(t.upsert_sql(t.insert_sql(), insert_only={"bar", "created_at"})) == [
         'INSERT INTO "table" ("id", "foo", "bar", "created_at") VALUES ($1, $2, $3, $4) '
         'ON CONFLICT ("id") DO UPDATE SET "foo"=EXCLUDED."foo"',
         1,
@@ -294,7 +294,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
     # We simulate what happens inside the upsert method
     all_insert_only = test_instance.insert_only_field_names()
     insert_sql = test_instance.insert_sql()
-    upsert_sql = Test.upsert_sql(insert_sql, exclude=all_insert_only)
+    upsert_sql = Test.upsert_sql(insert_sql, insert_only=all_insert_only)
 
     upsert_query = upsert_sql.query()[0]
 
@@ -325,7 +325,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
     manual_exclude = {"version"}
 
     insert_sql = test_instance.insert_sql()
-    upsert_sql = Test.upsert_sql(insert_sql, exclude=manual_exclude)
+    upsert_sql = Test.upsert_sql(insert_sql, insert_only=manual_exclude)
     upsert_query = upsert_sql.query()[0]
 
     # Both created_at (auto) and version (manual) should be excluded from UPDATE
@@ -387,7 +387,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
     assert '"created_at"=EXCLUDED."created_at"' not in upsert_query
 
     # Test that manual exclude still works in combination
-    upsert_sql_with_exclude = Test.upsert_sql(insert_sql, exclude={"updated_at"})
+    upsert_sql_with_exclude = Test.upsert_sql(insert_sql, insert_only={"updated_at"})
     upsert_query_with_exclude = upsert_sql_with_exclude.query()[0]
 
     # Now both created_at (auto) and updated_at (manual) should be excluded from UPDATE
@@ -425,7 +425,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
 
     # Test force_update with manual insert_only
     manual_upsert = Test.upsert_sql(
-        insert_sql, exclude={"updated_at"}, force_update={"created_at"}
+        insert_sql, insert_only={"updated_at"}, force_update={"created_at"}
     )
     manual_query = manual_upsert.query()[0]
     assert '"name"=EXCLUDED."name"' in manual_query
@@ -434,7 +434,7 @@ class Test(ModelBase, table_name="table", primary_key="id"):
 
     # Test partial force_update - only override specific fields
     partial_upsert = Test.upsert_sql(
-        insert_sql, exclude={"name"}, force_update={"created_at"}
+        insert_sql, insert_only={"name"}, force_update={"created_at"}
     )
     partial_query = partial_upsert.query()[0]
     assert '"name"=EXCLUDED."name"' not in partial_query  # Excluded manually