feat(api): add cascade delete support for parent geography resources

Author: 1mpossible-code

data/countries.py

@@ -271,15 +271,26 @@ def can_delete_country(country_code: str) -> tuple[bool, str]:
 
 def delete_country(code: str) -> bool:
     """
-    Delete a country by its code.
-    Cascading: Deletes all states and cities in this country first.
+    Delete a country by its code when no dependent states exist.
     """
-    if not can_delete_country(code)[0]:
-        raise ValueError(can_delete_country(code)[1])
+    can_delete, reason = can_delete_country(code)
+    if not can_delete:
+        raise ValueError(reason)
 
+    result = dbc.delete(COUNTRIES_COLLECT, {COUNTRY_CODE: code})
+    if result > 0:
+        country_by_code_cache.invalidate(code.upper())
+        return True
+    return False
+
+
+def delete_country_cascade(code: str) -> bool:
+    """
+    Delete a country and any dependent states/cities.
+    """
     states.delete_states_by_country(code)
 
-    result = dbc.delete(COUNTRIES_COLLECT, {COUNTRY_CODE: code})
+    result = dbc.delete(COUNTRIES_COLLECT, {COUNTRY_CODE: code.upper()})
     if result > 0:
         country_by_code_cache.invalidate(code.upper())
         return True

data/states.py

@@ -220,16 +220,26 @@ def can_delete_state(state_code: str) -> tuple[bool, str]:
 
 def delete_state(code: str) -> bool:
     """
-    Delete a state by its code.
-    Cascading: Deletes all cities in this state first.
+    Delete a state by its code when no dependent cities exist.
     """
     can_delete, reason = can_delete_state(code)
     if not can_delete:
         raise ValueError(reason)
 
+    result = dbc.delete(STATES_COLLECT, {STATE_CODE: code})
+    if result > 0:
+        state_by_code_cache.invalidate(code.upper())
+        return True
+    return False
+
+
+def delete_state_cascade(code: str) -> bool:
+    """
+    Delete a state and any dependent cities.
+    """
     cities.delete_cities_by_state(code)
 
-    result = dbc.delete(STATES_COLLECT, {STATE_CODE: code})
+    result = dbc.delete(STATES_COLLECT, {STATE_CODE: code.upper()})
     if result > 0:
         state_by_code_cache.invalidate(code.upper())
         return True

server/countries_endpoints.py

@@ -426,11 +426,22 @@ def put(self, country_code):
     )
     def delete(self, country_code):
         """
-        Delete a country
-        Removes the country from the database if no dependent states exist.
+        Delete a country.
+        By default this fails if dependent states exist.
+        Pass ?cascade=true to remove dependent states and cities first.
         """
+        cascade = request.args.get("cascade", "false").lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
+
         try:
-            success = countries_data.delete_country(country_code.upper())
+            if cascade:
+                success = countries_data.delete_country_cascade(country_code.upper())
+            else:
+                success = countries_data.delete_country(country_code.upper())
         except ValueError as e:
             countries_ns.abort(HTTPStatus.CONFLICT, str(e))
         except Exception as e:

server/states_endpoints.py

@@ -326,10 +326,22 @@ def put(self, state_code: str):
     )
     def delete(self, state_code: str):
         """
-        Delete a state by its code. Fails with 409 if dependent cities exist.
+        Delete a state by its code.
+        By default this fails with 409 if dependent cities exist.
+        Pass ?cascade=true to remove dependent cities first.
         """
+        cascade = request.args.get("cascade", "false").lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
+
         try:
-            success = states_data.delete_state(state_code.upper())
+            if cascade:
+                success = states_data.delete_state_cascade(state_code.upper())
+            else:
+                success = states_data.delete_state(state_code.upper())
         except ValueError as e:
             states_ns.abort(HTTPStatus.CONFLICT, str(e))
         except Exception as e:

server/tests/test_countries_endpoints.py

@@ -221,6 +221,26 @@ def test_delete_country_with_dependent_states(self, client):
             data = json.loads(response.data)
             assert '5 state' in data['message'].lower()
 
+    def test_delete_country_with_cascade_success(self, client):
+        """DELETE /countries/{code}?cascade=true uses cascading delete."""
+        with patch('data.countries.delete_country_cascade') as mock_delete:
+            mock_delete.return_value = True
+
+            response = client.delete('/countries/US?cascade=true')
+
+            assert response.status_code == HTTPStatus.NO_CONTENT
+            mock_delete.assert_called_once_with('US')
+
+    def test_delete_country_with_cascade_not_found(self, client):
+        """DELETE /countries/{code}?cascade=true returns 404 when missing."""
+        with patch('data.countries.delete_country_cascade') as mock_delete:
+            mock_delete.return_value = False
+
+            response = client.delete('/countries/XX?cascade=true')
+
+            assert response.status_code == HTTPStatus.NOT_FOUND
+            mock_delete.assert_called_once_with('XX')
+
     def test_get_countries_by_continent_success(self, client):
         """Test successful retrieval of countries by continent."""
         with patch('data.countries.get_countries_by_continent') as mock_get:

server/tests/test_states_endpoints.py

@@ -200,6 +200,24 @@ def test_delete_state_with_dependent_cities(self, client):
             data = resp.get_json()
             assert 'depend' in data['message'].lower()
 
+    def test_delete_state_with_cascade_success(self, client):
+        with patch('data.states.delete_state_cascade') as mock_delete:
+            mock_delete.return_value = True
+
+            resp = client.delete('/states/NY?cascade=true')
+
+            assert resp.status_code == HTTPStatus.NO_CONTENT
+            mock_delete.assert_called_once_with('NY')
+
+    def test_delete_state_with_cascade_not_found(self, client):
+        with patch('data.states.delete_state_cascade') as mock_delete:
+            mock_delete.return_value = False
+
+            resp = client.delete('/states/ZZ?cascade=true')
+
+            assert resp.status_code == HTTPStatus.NOT_FOUND
+            mock_delete.assert_called_once_with('ZZ')
+
     def test_get_state_by_name_success(self, client):
         """Test successful retrieval of state by name."""
         with patch('data.states.get_state_by_name') as mock_get: