j

API/HydrusNetwork.py

@@ -542,6 +542,53 @@ class HydrusNetwork:
         }
         return self._post("/add_tags/add_tags", data=body)
 
+    def mutate_tags_by_key(
+        self,
+        hash: Union[str,
+                    Iterable[str]],
+        service_key: str,
+        *,
+        add_tags: Optional[Iterable[str]] = None,
+        remove_tags: Optional[Iterable[str]] = None,
+    ) -> dict[str,
+              Any]:
+        """Add or remove tags with a single /add_tags/add_tags call.
+
+        Hydrus Client API: POST /add_tags/add_tags
+        Use `service_keys_to_actions_to_tags` so the client can apply additions
+        and removals in a single request (action '0' = add, '1' = remove).
+        """
+        hash_list = self._ensure_hashes(hash)
+        def _clean(tags: Optional[Iterable[str]]) -> list[str]:
+            if not tags:
+                return []
+            clean_list: list[str] = []
+            for tag in tags:
+                if not isinstance(tag, str):
+                    continue
+                text = tag.strip()
+                if not text:
+                    continue
+                clean_list.append(text)
+            return clean_list
+
+        actions: dict[str, list[str]] = {}
+        adds = _clean(add_tags)
+        removes = _clean(remove_tags)
+        if adds:
+            actions["0"] = adds
+        if removes:
+            actions["1"] = removes
+        if not actions:
+            return {}
+        body = {
+            "hashes": hash_list,
+            "service_keys_to_actions_to_tags": {
+                str(service_key): actions
+            },
+        }
+        return self._post("/add_tags/add_tags", data=body)
+
     def associate_url(self,
                       file_hashes: Union[str,
                                          Iterable[str]],