refactor: remove dry_run from delete() and drop()

The safemode prompt already provides a safer preview-and-confirm
workflow: it executes within a transaction, shows all affected
tables and row counts, and rolls back if the user declines.

dry_run was a weaker alternative (pre-transaction count that could
be stale) that added a union return type and dead parameters.

For programmatic preview, use Diagram.cascade().counts() directly.

The test_delete_dry_run, test_drop_dry_run, and test_part_delete_dry_run
tests are replaced with test_delete_preview_with_counts which
tests the Diagram.cascade().counts() API.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: dimitri-yatsenko

src/datajoint/table.py

@@ -981,15 +981,24 @@ def delete(
         transaction: bool = True,
         prompt: bool | None = None,
         part_integrity: str = "enforce",
-        dry_run: bool = False,
-    ) -> int | dict[str, int]:
+    ) -> int:
         """
         Deletes the contents of the table and its dependent tables, recursively.
 
         Uses graph-driven cascade: builds a dependency diagram, propagates
         restrictions to all descendants, then deletes in reverse topological
         order (leaves first).
 
+        With ``safemode=True`` (the default), delete previews all affected
+        tables and row counts, executes within a transaction, and asks for
+        confirmation before committing. Declining rolls back all changes —
+        effectively a built-in dry run.
+
+        To preview cascade impact without executing, use ``Diagram``::
+
+            diag = dj.Diagram(schema)
+            diag.cascade(MyTable & restriction).counts()
+
         Args:
             transaction: If `True`, use of the entire delete becomes an atomic transaction.
                 This is the default and recommended behavior. Set to `False` if this delete is
@@ -1000,12 +1009,9 @@ def delete(
                 - ``"enforce"`` (default): Error if parts would be deleted without masters.
                 - ``"ignore"``: Allow deleting parts without masters (breaks integrity).
                 - ``"cascade"``: Also delete masters when parts are deleted (maintains integrity).
-            dry_run: If `True`, return a dict mapping full table names to affected
-                row counts without deleting any data. Default False.
 
         Returns:
-            Number of deleted rows (excluding those from dependent tables), or
-            (if ``dry_run``) a dict mapping full table name to affected row count.
+            Number of deleted rows (excluding those from dependent tables).
 
         Raises:
             DataJointError: When deleting within an existing transaction.
@@ -1019,9 +1025,6 @@ def delete(
         diagram = Diagram._from_table(self)
         diagram = diagram.cascade(self, part_integrity=part_integrity)
 
-        if dry_run:
-            return diagram.counts()
-
         conn = self.connection
         prompt = conn._config["safemode"] if prompt is None else prompt
 
@@ -1145,25 +1148,22 @@ def drop_quick(self):
         else:
             logger.info("Nothing to drop: table %s is not declared" % self.full_table_name)
 
-    def drop(self, prompt: bool | None = None, part_integrity: str = "enforce", dry_run: bool = False):
+    def drop(self, prompt: bool | None = None, part_integrity: str = "enforce"):
         """
         Drop the table and all tables that reference it, recursively.
 
         Uses graph-driven traversal: builds a dependency diagram and drops
         in reverse topological order (leaves first).
 
+        With ``safemode=True`` (the default), drop previews all affected
+        tables and row counts and asks for confirmation before proceeding.
+
         Args:
             prompt: If `True`, show what will be dropped and ask for confirmation.
                 If `False`, drop without confirmation. Default is `dj.config['safemode']`.
             part_integrity: Policy for master-part integrity. One of:
                 - ``"enforce"`` (default): Error if parts would be dropped without masters.
                 - ``"ignore"``: Allow dropping parts without masters.
-            dry_run: If `True`, return a dict mapping full table names to row
-                counts without dropping any tables. Default False.
-
-        Returns:
-            dict[str, int] or None: If ``dry_run``, mapping of full table name
-            to row count. Otherwise None.
         """
         if self.restriction:
             raise DataJointError(
@@ -1187,14 +1187,6 @@ def drop(self, prompt: bool | None = None, part_integrity: str = "enforce", dry_
                         )
                     )
 
-        if dry_run:
-            result = {}
-            for ft in diagram:
-                count = len(ft)
-                result[ft.full_table_name] = count
-                logger.info("{table} ({count} tuples)".format(table=ft.full_table_name, count=count))
-            return result
-
         do_drop = True
         if prompt:
             for ft in diagram:

src/datajoint/user_tables.py

@@ -224,7 +224,7 @@ def delete(self, part_integrity: str = "enforce", **kwargs):
                 - ``"ignore"``: Allow direct deletion (breaks master-part integrity).
                 - ``"cascade"``: Delete parts AND cascade up to delete master.
             **kwargs: Additional arguments passed to Table.delete()
-                      (transaction, prompt, dry_run)
+                      (transaction, prompt)
 
         Raises:
             DataJointError: If part_integrity="enforce" (direct Part deletes prohibited)
@@ -237,7 +237,7 @@ def delete(self, part_integrity: str = "enforce", **kwargs):
             )
         return super().delete(part_integrity=part_integrity, **kwargs)
 
-    def drop(self, part_integrity: str = "enforce", dry_run: bool = False):
+    def drop(self, part_integrity: str = "enforce"):
         """
         Drop a Part table.
 
@@ -246,13 +246,12 @@ def drop(self, part_integrity: str = "enforce", dry_run: bool = False):
                 - ``"enforce"`` (default): Error - drop master instead.
                 - ``"ignore"``: Allow direct drop (breaks master-part structure).
                 Note: ``"cascade"`` is not supported for drop (too destructive).
-            dry_run: If `True`, return row counts without dropping. Default False.
 
         Raises:
             DataJointError: If part_integrity="enforce" (direct Part drops prohibited)
         """
         if part_integrity == "ignore":
-            return super().drop(part_integrity="ignore", dry_run=dry_run)
+            return super().drop(part_integrity="ignore")
         elif part_integrity == "enforce":
             raise DataJointError("Cannot drop a Part directly. Drop master instead, or use part_integrity='ignore' to force.")
         else:

tests/integration/test_cascade_delete.py

@@ -190,8 +190,8 @@ class Observation(dj.Manual):
     assert remaining_obs[0]["measurement"] == 15.3
 
 
-def test_delete_dry_run(schema_by_backend):
-    """dry_run=True returns affected row counts without deleting data."""
+def test_delete_preview_with_counts(schema_by_backend):
+    """Diagram.cascade().counts() previews affected rows without deleting."""
 
     @schema_by_backend
     class Parent(dj.Manual):
@@ -216,8 +216,9 @@ class Child(dj.Manual):
     Child.insert1((1, 2, "C1-2"))
     Child.insert1((2, 1, "C2-1"))
 
-    # dry_run on restricted delete
-    counts = (Parent & {"parent_id": 1}).delete(dry_run=True)
+    # Preview restricted cascade via Diagram
+    diag = dj.Diagram._from_table(Parent & {"parent_id": 1})
+    counts = diag.cascade(Parent & {"parent_id": 1}).counts()
 
     assert isinstance(counts, dict)
     assert counts[Parent.full_table_name] == 1
@@ -226,81 +227,3 @@ class Child(dj.Manual):
     # Data must still be intact
     assert len(Parent()) == 2
     assert len(Child()) == 3
-
-    # dry_run on unrestricted delete
-    counts_all = Parent.delete(dry_run=True)
-    assert counts_all[Parent.full_table_name] == 2
-    assert counts_all[Child.full_table_name] == 3
-
-    # Still intact
-    assert len(Parent()) == 2
-    assert len(Child()) == 3
-
-
-def test_drop_dry_run(schema_by_backend):
-    """dry_run=True returns row counts without dropping tables."""
-
-    @schema_by_backend
-    class Parent(dj.Manual):
-        definition = """
-        parent_id : int
-        ---
-        name : varchar(255)
-        """
-
-    @schema_by_backend
-    class Child(dj.Manual):
-        definition = """
-        -> Parent
-        child_id : int
-        ---
-        data : varchar(255)
-        """
-
-    Parent.insert1((1, "P1"))
-    Child.insert1((1, 1, "C1"))
-
-    counts = Parent.drop(dry_run=True)
-
-    assert isinstance(counts, dict)
-    assert counts[Parent.full_table_name] == 1
-    assert counts[Child.full_table_name] == 1
-
-    # Tables must still exist and have data
-    assert Parent.is_declared
-    assert Child.is_declared
-    assert len(Parent()) == 1
-    assert len(Child()) == 1
-
-
-def test_part_delete_dry_run(schema_by_backend):
-    """dry_run=True on Part.delete() returns affected row counts without deleting."""
-
-    @schema_by_backend
-    class Master(dj.Manual):
-        definition = """
-        master_id : int
-        ---
-        name : varchar(255)
-        """
-
-        class Detail(dj.Part):
-            definition = """
-            -> master
-            detail_id : int
-            ---
-            data : varchar(255)
-            """
-
-    Master.insert1((1, "M1"))
-    Master.Detail.insert([(1, 1, "D1"), (1, 2, "D2")])
-
-    # dry_run with part_integrity="ignore" should return counts without deleting
-    counts = (Master.Detail & {"master_id": 1}).delete(part_integrity="ignore", dry_run=True)
-
-    assert isinstance(counts, dict)
-    assert counts[Master.Detail.full_table_name] == 2
-
-    # Data must still be intact
-    assert len(Master()) == 1
-    assert len(Master.Detail()) == 2