Add an API helper to update an element

Closes #222 (closed)

arkindex_worker/worker/element.py

@@ -275,6 +275,70 @@ class ElementMixin(object):
 
         return created_ids
 
+    def update_element(
+        self,
+        element: Union[Element, CachedElement],
+        type: Optional[str] = None,
+        name: Optional[str] = None,
+        polygon: Optional[List[List[Union[int, float]]]] = None,
+        confidence: Optional[float] = None,
+    ) -> dict:
+        """
+        Partially update an element through the API.
+
+        :param element: The element to update.
+        :param type: Optional new slug type of the element.
+        :param name: Optional new name of the element.
+        :param polygon: Optional new polygon of the element.
+        :param confidence: Optional new confidence score, between 0.0 and 1.0.
+        :returns: A dict from the ``PartialUpdateElement`` API endpoint,
+        """
+        assert element and isinstance(
+            element, (Element, CachedElement)
+        ), "element shouldn't be null and should be an Element or CachedElement"
+        assert type is None or isinstance(type, str), "type should be None or a str"
+        assert name is None or isinstance(name, str), "name should be None or a str"
+        assert polygon is None or isinstance(
+            polygon, list
+        ), "polygon should be None or a list"
+        if polygon:
+            assert len(polygon) >= 3, "polygon should have at least three points"
+            assert all(
+                isinstance(point, list) and len(point) == 2 for point in polygon
+            ), "polygon points should be lists of two items"
+            assert all(
+                isinstance(coord, (int, float)) for point in polygon for coord in point
+            ), "polygon points should be lists of two numbers"
+        assert confidence is None or (
+            isinstance(confidence, float) and 0 <= confidence <= 1
+        ), "confidence should be None or a float in [0..1] range"
+
+        if self.is_read_only:
+            logger.warning("Cannot update element as this worker is in read-only mode")
+            return
+
+        updated_element = self.request(
+            "PartialUpdateElement",
+            id=element.id,
+            body={
+                "type": type,
+                "name": name,
+                "polygon": polygon,
+                "confidence": confidence,
+            },
+        )
+
+        if self.use_cache:
+            CachedElement.update(
+                {
+                    CachedElement.type: type,
+                    CachedElement.polygon: str(polygon),
+                    CachedElement.confidence: confidence,
+                }
+            ).where(CachedElement.id == element.id).execute()
+
+        return updated_element
+
     def list_element_children(
         self,
         element: Union[Element, CachedElement],