fix(user-sync): actually remove pruned fields via empty relations and remove_empty

Author: raederan

docs/tools/user-sync.md

@@ -20,6 +20,16 @@ Credentials are read from `accounts.pwd.yaml` (or `--cred-filepath`), the same
 mechanism as `OswExpress`. Start with `--dry-run` to preview, then run without
 it to write after confirming at the prompt.
 
+To also remove data no longer wanted (disabled optional fields and
+`employment_contract_status`) from existing items, add `--prune`:
+
+```bash
+uv run python examples/user_sync.py --domain your-instance.example.org --prune --dry-run
+```
+
+Users whose ORCID record exposes no email are listed in a warning at the end of
+the run; a missing email never fails the sync.
+
 ### Options
 
 By default the tool syncs both ORCID and MediaWiki-native accounts and writes

src/osw/tools/user_sync/build.py

@@ -24,11 +24,17 @@ def _labels(text: str) -> List[Any]:
 
 
 def _strip_protected(entity: Any) -> None:
-    """Remove protected relation defaults (e.g. employment_contract_status)."""
+    """Clear protected relations (e.g. employment_contract_status).
+
+    Set to an empty list rather than removed: the model re-applies its default
+    when the field is absent, and the store only overwrites a relation that is
+    present as an explicit empty value (with ``remove_empty=False``).
+    """
     iris = getattr(entity, "__iris__", None)
     if isinstance(iris, dict):
         for name in PROTECTED_FIELDS:
-            iris.pop(name, None)
+            if name in iris:
+                iris[name] = []
 
 
 def build_organization(proposed: ProposedOrganization) -> Organization:
@@ -76,10 +82,8 @@ def apply_update(entity: Any, proposed: ProposedUser, apply_fields: Set[str]) ->
     if "websites" in apply_fields:
         entity.website = set(proposed.websites)
     if "organizations" in apply_fields:
-        if proposed.organizations:
-            entity.__iris__["organization"] = list(proposed.organizations)
-        else:
-            entity.__iris__.pop("organization", None)
+        # Empty list both links (non-empty) and clears (empty, on removal).
+        entity.__iris__["organization"] = list(proposed.organizations)
     if any(name in apply_fields for name in PROTECTED_FIELDS):
         _strip_protected(entity)
     return entity

src/osw/tools/user_sync/sync.py

@@ -103,7 +103,9 @@ def _store_organizations(osw: Any, org_map, report: SyncReport) -> None:
         report.failed["organizations"] = str(exc)
 
 
-def _store_users(osw: Any, resolution: Resolution, report: SyncReport) -> None:
+def _store_users(
+    osw: Any, resolution: Resolution, report: SyncReport, remove_empty: bool = True
+) -> None:
     entities = []
     for resolved in resolution.resolved:
         proposed = resolved.change.proposed
@@ -126,7 +128,10 @@ def _store_users(osw: Any, resolution: Resolution, report: SyncReport) -> None:
         try:
             osw.store_entity(
                 OSW.StoreEntityParam(
-                    entities=entities, overwrite=True, edit_comment="user-sync"
+                    entities=entities,
+                    overwrite=True,
+                    remove_empty=remove_empty,
+                    edit_comment="user-sync",
                 )
             )
         except Exception as exc:  # pragma: no cover - network failure path
@@ -215,7 +220,8 @@ def run_user_sync(
 
     if config.link_organizations:
         _store_organizations(osw, org_map, report)
-    _store_users(osw, resolution, report)
+    # When pruning, keep emptied fields in the payload so they overwrite (delete).
+    _store_users(osw, resolution, report, remove_empty=not config.prune)
     if config.create_redirects:
         _create_redirects(osw, resolution, report)
     _verify(osw, report)

tests/tools/test_user_sync_build.py

@@ -38,17 +38,17 @@ def _entity():
     )
 
 
-def test_strip_protected_removes_only_protected():
+def test_strip_protected_empties_only_protected():
     entity = _entity()
     _strip_protected(entity)
-    assert "employment_contract_status" not in entity.__iris__
-    assert "organization" in entity.__iris__
+    assert entity.__iris__["employment_contract_status"] == []
+    assert entity.__iris__["organization"] == ["Item:OSWa"]
 
 
 def test_apply_update_strips_protected_when_in_fields():
     entity = _entity()
     apply_update(entity, _proposed(), {"employment_contract_status"})
-    assert "employment_contract_status" not in entity.__iris__
+    assert entity.__iris__["employment_contract_status"] == []
 
 
 def test_apply_update_keeps_protected_when_not_in_fields():
@@ -61,7 +61,7 @@ def test_apply_update_keeps_protected_when_not_in_fields():
 def test_apply_update_clears_organization_when_empty():
     entity = _entity()
     apply_update(entity, _proposed(organizations=[]), {"organizations"})
-    assert "organization" not in entity.__iris__
+    assert entity.__iris__["organization"] == []
 
 
 def test_apply_update_sets_organization_when_present():