Docs for .transform() add_foreign_keys= and foreign_keys=, refs #577

Plus extended tests to cover the more explicit definitions.

docs/python-api.rst

@@ -1467,6 +1467,39 @@ The ``column_order=`` parameter can be used to change the order of the columns.
     # Change column order
     table.transform(column_order=("name", "age", "id")
 
+Adding foreign key constraints
+------------------------------
+
+You can add one or more foreign key constraints to a table using the ``add_foreign_keys=`` parameter:
+
+.. code-block:: python
+
+    db["places"].transform(
+        add_foreign_keys=(
+            ("country", "country", "id"),
+            ("continent", "continent", "id")
+        )
+    )
+
+This accepts the same arguments described in :ref:`specifying foreign keys <python_api_foreign_keys>` - so you can specify them as a full tuple of ``(column, other_table, other_column)``, or you can take a shortcut and pass just the name of the column, provided the table can be automatically derived from the column name:
+
+.. code-block:: python
+
+    db["places"].transform(
+        add_foreign_keys=(("country", "continent"))
+    )
+
+Replacing foreign key constraints
+---------------------------------
+
+The ``foreign_keys=`` parameter is similar to  to ``add_foreign_keys=`` but can be be used to replace all foreign key constraints on a table, dropping any that are not explicitly mentioned:
+
+.. code-block:: python
+
+    db["places"].transform(
+        add_foreign_keys=(("continent",))
+    )
+
 Dropping foreign key constraints
 --------------------------------
 

tests/test_transform.py

@@ -429,7 +429,18 @@ def test_transform_add_foreign_keys_from_scratch(fresh_db):
     )
 
 
-def test_transform_add_foreign_keys_from_partial(fresh_db):
+@pytest.mark.parametrize(
+    "add_foreign_keys",
+    (
+        ("country", "continent"),
+        # Fully specified
+        (
+            ("country", "country", "id"),
+            ("continent", "continent", "id"),
+        ),
+    ),
+)
+def test_transform_add_foreign_keys_from_partial(fresh_db, add_foreign_keys):
     _add_country_city_continent(fresh_db)
     fresh_db["places"].insert(
         _CAVEAU,
@@ -440,7 +451,7 @@ def test_transform_add_foreign_keys_from_partial(fresh_db):
         ForeignKey(table="places", column="city", other_table="city", other_column="id")
     ]
     # Now add three more using .transform()
-    fresh_db["places"].transform(add_foreign_keys=("country", "continent"))
+    fresh_db["places"].transform(add_foreign_keys=add_foreign_keys)
     # Should now have all three:
     assert fresh_db["places"].foreign_keys == [
         ForeignKey(
@@ -458,7 +469,18 @@ def test_transform_add_foreign_keys_from_partial(fresh_db):
     ]
 
 
-def test_transform_replace_foreign_keys(fresh_db):
+@pytest.mark.parametrize(
+    "foreign_keys",
+    (
+        ("country", "continent"),
+        # Fully specified
+        (
+            ("country", "country", "id"),
+            ("continent", "continent", "id"),
+        ),
+    ),
+)
+def test_transform_replace_foreign_keys(fresh_db, foreign_keys):
     _add_country_city_continent(fresh_db)
     fresh_db["places"].insert(
         _CAVEAU,
@@ -466,9 +488,7 @@ def test_transform_replace_foreign_keys(fresh_db):
     )
     assert len(fresh_db["places"].foreign_keys) == 1
     # Replace with two different ones
-    fresh_db["places"].transform(
+    fresh_db["places"].transform(foreign_keys=foreign_keys)
-        foreign_keys=("country", "continent"),
-    )
     assert fresh_db["places"].schema == (
         'CREATE TABLE "places" (\n'
         "   [id] INTEGER,\n"