arkindex-base-worker 0.3.6rc4__py3-none-any.whl → 0.3.7__py3-none-any.whl

arkindex_worker/worker/element.py

@@ -1,14 +1,16 @@
 """
 ElementsWorker methods for elements and element types.
 """
+
 from collections.abc import Iterable
 from typing import NamedTuple
 from uuid import UUID
+from warnings import warn
 
 from peewee import IntegrityError
 
 from arkindex_worker import logger
-from arkindex_worker.cache import CachedElement, CachedImage
+from arkindex_worker.cache import CachedElement, CachedImage, unsupported_cache
 from arkindex_worker.models import Element
 
 
@@ -29,6 +31,7 @@ class MissingTypeError(Exception):
 
 
 class ElementMixin:
+    @unsupported_cache
     def create_required_types(self, element_types: list[ElementType]):
         """Creates given element types in the corpus.
 
@@ -81,13 +84,15 @@ class ElementMixin:
 
         return True
 
+    @unsupported_cache
     def create_sub_element(
         self,
         element: Element,
         type: str,
         name: str,
-        polygon: list[list[int | float]],
+        polygon: list[list[int | float]] | None = None,
         confidence: float | None = None,
+        image: str | None = None,
         slim_output: bool = True,
     ) -> str:
         """
@@ -96,8 +101,10 @@ class ElementMixin:
         :param Element element: The parent element.
         :param type: Slug of the element type for this child element.
         :param name: Name of the child element.
-        :param polygon: Polygon of the child element.
+        :param polygon: Optional polygon of the child element.
         :param confidence: Optional confidence score, between 0.0 and 1.0.
+        :param image: Optional image ID of the child element.
+        :param slim_output: Whether to return the child ID or the full child.
         :returns: UUID of the created element.
         """
         assert element and isinstance(
@@ -109,19 +116,29 @@ class ElementMixin:
         assert name and isinstance(
             name, str
         ), "name shouldn't be null and should be of type str"
-        assert polygon and isinstance(
+        assert polygon is None or isinstance(
             polygon, list
-        ), "polygon shouldn't be null and should be of type list"
-        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"
+        ), "polygon should be None or a list"
+        if polygon is not None:
+            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"
+        assert image is None or isinstance(image, str), "image should be None or string"
+        if image is not None:
+            # Make sure it's a valid UUID
+            try:
+                UUID(image)
+            except ValueError as e:
+                raise ValueError("image is not a valid uuid.") from e
+        if polygon and image is None:
+            assert element.zone, "An image or a parent with an image is required to create an element with a polygon."
         assert isinstance(slim_output, bool), "slim_output should be of type bool"
 
         if self.is_read_only:
@@ -133,7 +150,7 @@ class ElementMixin:
             body={
                 "type": type,
                 "name": name,
-                "image": element.zone.image.id,
+                "image": image,
                 "corpus": element.corpus.id,
                 "polygon": polygon,
                 "parent": element.id,
@@ -270,6 +287,36 @@ class ElementMixin:
 
         return created_ids
 
+    @unsupported_cache
+    def create_element_parent(
+        self,
+        parent: Element,
+        child: Element,
+    ) -> dict[str, str]:
+        """
+        Link an element to a parent through the API.
+
+        :param parent: Parent element.
+        :param child: Child element.
+        :returns: A dict from the ``CreateElementParent`` API endpoint.
+        """
+        assert parent and isinstance(
+            parent, Element
+        ), "parent shouldn't be null and should be of type Element"
+        assert child and isinstance(
+            child, Element
+        ), "child shouldn't be null and should be of type Element"
+
+        if self.is_read_only:
+            logger.warning("Cannot link elements as this worker is in read-only mode")
+            return
+
+        return self.request(
+            "CreateElementParent",
+            parent=parent.id,
+            child=child.id,
+        )
+
     def partial_update_element(
         self, element: Element | CachedElement, **kwargs
     ) -> dict:
@@ -288,7 +335,7 @@ class ElementMixin:
             * *image* (``UUID``): Optional ID of the image of this element
 
 
-        :returns: A dict from the ``PartialUpdateElement`` API endpoint,
+        :returns: A dict from the ``PartialUpdateElement`` API endpoint.
         """
         assert element and isinstance(
             element, Element | CachedElement
@@ -380,6 +427,13 @@ class ElementMixin:
         """
         List children of an element.
 
+        Warns:
+        ----
+        The following parameters are **deprecated**:
+
+        - `transcription_worker_version` in favor of `transcription_worker_run`
+        - `worker_version` in favor of `worker_run`
+
         :param element: Parent element to find children of.
         :param folder: Restrict to or exclude elements with folder types.
            This parameter is not supported when caching is enabled.
@@ -387,9 +441,9 @@ class ElementMixin:
            This parameter is not supported when caching is enabled.
         :param recursive: Look for elements recursively (grand-children, etc.)
            This parameter is not supported when caching is enabled.
-        :param transcription_worker_version: Restrict to elements that have a transcription created by a worker version with this UUID.
+        :param transcription_worker_version: **Deprecated** Restrict to elements that have a transcription created by a worker version with this UUID. Set to False to look for elements that have a manual transcription.
            This parameter is not supported when caching is enabled.
-        :param transcription_worker_run: Restrict to elements that have a transcription created by a worker run with this UUID.
+        :param transcription_worker_run: Restrict to elements that have a transcription created by a worker run with this UUID. Set to False to look for elements that have a manual transcription.
            This parameter is not supported when caching is enabled.
         :param type: Restrict to elements with a specific type slug
            This parameter is not supported when caching is enabled.
@@ -405,7 +459,7 @@ class ElementMixin:
         :param with_zone: Include the ``zone`` attribute in the response,
            holding the element's image and polygon.
            This parameter is not supported when caching is enabled.
-        :param worker_version: Restrict to elements created by a worker version with this UUID.
+        :param worker_version: **Deprecated** Restrict to elements created by a worker version with this UUID.
         :param worker_run: Restrict to elements created by a worker run with this UUID.
         :return: An iterable of dicts from the ``ListElementChildren`` API endpoint,
            or an iterable of [CachedElement][arkindex_worker.cache.CachedElement] when caching is enabled.
@@ -424,6 +478,11 @@ class ElementMixin:
             assert isinstance(recursive, bool), "recursive should be of type bool"
             query_params["recursive"] = recursive
         if transcription_worker_version is not None:
+            warn(
+                "`transcription_worker_version` usage is deprecated. Consider using `transcription_worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 transcription_worker_version, str | bool
             ), "transcription_worker_version should be of type str or bool"
@@ -464,6 +523,11 @@ class ElementMixin:
             assert isinstance(with_zone, bool), "with_zone should be of type bool"
             query_params["with_zone"] = with_zone
         if worker_version is not None:
+            warn(
+                "`worker_version` usage is deprecated. Consider using `worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 worker_version, str | bool
             ), "worker_version should be of type str or bool"
@@ -542,6 +606,13 @@ class ElementMixin:
         """
         List parents of an element.
 
+        Warns:
+        ----
+        The following parameters are **deprecated**:
+
+        - `transcription_worker_version` in favor of `transcription_worker_run`
+        - `worker_version` in favor of `worker_run`
+
         :param element: Child element to find parents of.
         :param folder: Restrict to or exclude elements with folder types.
            This parameter is not supported when caching is enabled.
@@ -549,7 +620,7 @@ class ElementMixin:
            This parameter is not supported when caching is enabled.
         :param recursive: Look for elements recursively (grand-children, etc.)
            This parameter is not supported when caching is enabled.
-        :param transcription_worker_version: Restrict to elements that have a transcription created by a worker version with this UUID.
+        :param transcription_worker_version: **Deprecated** Restrict to elements that have a transcription created by a worker version with this UUID.
            This parameter is not supported when caching is enabled.
         :param transcription_worker_run: Restrict to elements that have a transcription created by a worker run with this UUID.
            This parameter is not supported when caching is enabled.
@@ -567,7 +638,7 @@ class ElementMixin:
         :param with_zone: Include the ``zone`` attribute in the response,
            holding the element's image and polygon.
            This parameter is not supported when caching is enabled.
-        :param worker_version: Restrict to elements created by a worker version with this UUID.
+        :param worker_version: **Deprecated** Restrict to elements created by a worker version with this UUID.
         :param worker_run: Restrict to elements created by a worker run with this UUID.
         :return: An iterable of dicts from the ``ListElementParents`` API endpoint,
            or an iterable of [CachedElement][arkindex_worker.cache.CachedElement] when caching is enabled.
@@ -586,6 +657,11 @@ class ElementMixin:
             assert isinstance(recursive, bool), "recursive should be of type bool"
             query_params["recursive"] = recursive
         if transcription_worker_version is not None:
+            warn(
+                "`transcription_worker_version` usage is deprecated. Consider using `transcription_worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 transcription_worker_version, str | bool
             ), "transcription_worker_version should be of type str or bool"
@@ -626,6 +702,11 @@ class ElementMixin:
             assert isinstance(with_zone, bool), "with_zone should be of type bool"
             query_params["with_zone"] = with_zone
         if worker_version is not None:
+            warn(
+                "`worker_version` usage is deprecated. Consider using `worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 worker_version, str | bool
             ), "worker_version should be of type str or bool"

arkindex_worker/worker/entity.py

@@ -4,11 +4,16 @@ ElementsWorker methods for entities.
 
 from operator import itemgetter
 from typing import TypedDict
+from warnings import warn
 
 from peewee import IntegrityError
 
 from arkindex_worker import logger
-from arkindex_worker.cache import CachedEntity, CachedTranscriptionEntity
+from arkindex_worker.cache import (
+    CachedEntity,
+    CachedTranscriptionEntity,
+    unsupported_cache,
+)
 from arkindex_worker.models import Element, Transcription
 
 
@@ -28,6 +33,7 @@ class MissingEntityType(Exception):
 
 
 class EntityMixin:
+    @unsupported_cache
     def check_required_entity_types(
         self, entity_types: list[str], create_missing: bool = True
     ):
@@ -205,6 +211,7 @@ class EntityMixin:
                 )
         return transcription_ent
 
+    @unsupported_cache
     def create_transcription_entities(
         self,
         transcription: Transcription,
@@ -297,13 +304,21 @@ class EntityMixin:
         self,
         transcription: Transcription,
         worker_version: str | bool | None = None,
+        worker_run: str | bool | None = None,
     ):
         """
         List existing entities on a transcription
         This method does not support cache
 
+        Warns:
+        ----
+        The following parameters are **deprecated**:
+
+        - `worker_version` in favor of `worker_run`
+
         :param transcription: The transcription to list entities on.
-        :param worker_version: Restrict to entities created by a worker version with this UUID. Set to False to look for manually created transcriptions.
+        :param worker_version: **Deprecated** Restrict to entities created by a worker version with this UUID. Set to False to look for manually created entities.
+        :param worker_run: Restrict to entities created by a worker run with this UUID. Set to False to look for manually created entities.
         """
         query_params = {}
         assert transcription and isinstance(
@@ -311,6 +326,11 @@ class EntityMixin:
         ), "transcription shouldn't be null and should be a Transcription"
 
         if worker_version is not None:
+            warn(
+                "`worker_version` usage is deprecated. Consider using `worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 worker_version, str | bool
             ), "worker_version should be of type str or bool"
@@ -320,6 +340,15 @@ class EntityMixin:
                     worker_version is False
                 ), "if of type bool, worker_version can only be set to False"
             query_params["worker_version"] = worker_version
+        if worker_run is not None:
+            assert isinstance(
+                worker_run, str | bool
+            ), "worker_run should be of type str or bool"
+            if isinstance(worker_run, bool):
+                assert (
+                    worker_run is False
+                ), "if of type bool, worker_run can only be set to False"
+            query_params["worker_run"] = worker_run
 
         return self.api_client.paginate(
             "ListTranscriptionEntities", id=transcription.id, **query_params
@@ -351,8 +380,9 @@ class EntityMixin:
                 "ListCorpusEntities", id=self.corpus_id, **query_params
             )
         }
+        count = len(self.entities)
         logger.info(
-            f"Loaded {len(self.entities)} entities in corpus ({self.corpus_id})"
+            f'Loaded {count} entit{"ies" if count > 1 else "y"} in corpus ({self.corpus_id})'
         )
 
     def list_corpus_entity_types(
@@ -367,6 +397,7 @@ class EntityMixin:
                 "ListCorpusEntityTypes", id=self.corpus_id
             )
         }
+        count = len(self.entity_types)
         logger.info(
-            f"Loaded {len(self.entity_types)} entity types in corpus ({self.corpus_id})."
+            f'Loaded {count} entity type{"s"[:count>1]} in corpus ({self.corpus_id}).'
         )

arkindex_worker/worker/metadata.py

@@ -5,7 +5,7 @@ ElementsWorker methods for metadata.
 from enum import Enum
 
 from arkindex_worker import logger
-from arkindex_worker.cache import CachedElement
+from arkindex_worker.cache import CachedElement, unsupported_cache
 from arkindex_worker.models import Element
 
 
@@ -50,12 +50,13 @@ class MetaType(Enum):
 
     URL = "url"
     """
-    A metadata with a string value that should be interpreted as an URL.
+    A metadata with a string value that should be interpreted as a URL.
     Only the ``http`` and ``https`` schemes are allowed.
     """
 
 
 class MetaDataMixin:
+    @unsupported_cache
     def create_metadata(
         self,
         element: Element | CachedElement,
@@ -106,17 +107,18 @@ class MetaDataMixin:
 
         return metadata["id"]
 
-    def create_metadatas(
+    @unsupported_cache
+    def create_metadata_bulk(
         self,
         element: Element | CachedElement,
-        metadatas: list[dict[str, MetaType | str | int | float | None]],
+        metadata_list: list[dict[str, MetaType | str | int | float | None]],
     ) -> list[dict[str, str]]:
         """
         Create multiple metadata on an existing element.
         This method does not support cache.
 
         :param element: The element to create multiple metadata on.
-        :param metadatas: The list of dict whose keys are the following:
+        :param metadata_list: The list of dict whose keys are the following:
             - type: MetaType
             - name: str
             - value: str | int | float
@@ -126,13 +128,13 @@ class MetaDataMixin:
             element, Element | CachedElement
         ), "element shouldn't be null and should be of type Element or CachedElement"
 
-        assert metadatas and isinstance(
-            metadatas, list
-        ), "type shouldn't be null and should be of type list of Dict"
+        assert metadata_list and isinstance(
+            metadata_list, list
+        ), "metadata_list shouldn't be null and should be of type list of dict"
 
         # Make a copy to avoid modifying the metadata_list argument
         metas = []
-        for index, metadata in enumerate(metadatas):
+        for index, metadata in enumerate(metadata_list):
             assert isinstance(
                 metadata, dict
             ), f"Element at index {index} in metadata_list: Should be of type dict"
@@ -178,16 +180,24 @@ class MetaDataMixin:
         return created_metadata_list
 
     def list_element_metadata(
-        self, element: Element | CachedElement
+        self, element: Element | CachedElement, load_parents: bool | None = None
     ) -> list[dict[str, str]]:
         """
         List all metadata linked to an element.
         This method does not support cache.
 
         :param element: The element to list metadata on.
+        :param load_parents: Also include all metadata from the element's parents in the response.
         """
         assert element and isinstance(
             element, Element | CachedElement
         ), "element shouldn't be null and should be of type Element or CachedElement"
 
-        return self.api_client.paginate("ListElementMetaData", id=element.id)
+        query_params = {}
+        if load_parents is not None:
+            assert isinstance(load_parents, bool), "load_parents should be of type bool"
+            query_params["load_parents"] = load_parents
+
+        return self.api_client.paginate(
+            "ListElementMetaData", id=element.id, **query_params
+        )

arkindex_worker/worker/training.py

@@ -81,6 +81,10 @@ class TrainingMixin:
 
     model_version = None
 
+    @property
+    def is_finetuning(self) -> bool:
+        return bool(self.model_version_id)
+
     @skip_if_read_only
     def publish_model_version(
         self,
@@ -276,8 +280,17 @@ class TrainingMixin:
                 },
             )
         except ErrorResponse as e:
+            # Temporary fix while waiting for `ValidateModelVersion` refactoring as it can
+            # return errors even when the model version is properly validated
+            if e.status_code in [403, 500]:
+                logger.warning(
+                    f'An error occurred while validating model version {self.model_version["id"]}, please check its status.'
+                )
+                return
+
             if e.status_code != 409:
                 raise e
+
             logger.warning(
                 f"An available model version exists with hash {hash}, using it instead of the pending version."
             )

arkindex_worker/worker/transcription.py

@@ -4,6 +4,7 @@ ElementsWorker methods for transcriptions.
 
 from collections.abc import Iterable
 from enum import Enum
+from warnings import warn
 
 from peewee import IntegrityError
 
@@ -366,14 +367,22 @@ class TranscriptionMixin:
         element_type: str | None = None,
         recursive: bool | None = None,
         worker_version: str | bool | None = None,
+        worker_run: str | bool | None = None,
     ) -> Iterable[dict] | Iterable[CachedTranscription]:
         """
         List transcriptions on an element.
 
+        Warns:
+        ----
+        The following parameters are **deprecated**:
+
+        - `worker_version` in favor of `worker_run`
+
         :param element: The element to list transcriptions on.
         :param element_type: Restrict to transcriptions whose elements have an element type with this slug.
         :param recursive: Include transcriptions of any descendant of this element, recursively.
-        :param worker_version: Restrict to transcriptions created by a worker version with this UUID. Set to False to look for manually created transcriptions.
+        :param worker_version: **Deprecated** Restrict to transcriptions created by a worker version with this UUID. Set to False to look for manually created transcriptions.
+        :param worker_run: Restrict to transcriptions created by a worker run with this UUID. Set to False to look for manually created transcriptions.
         :returns: An iterable of dicts representing each transcription,
            or an iterable of CachedTranscription when cache support is enabled.
         """
@@ -388,6 +397,11 @@ class TranscriptionMixin:
             assert isinstance(recursive, bool), "recursive should be of type bool"
             query_params["recursive"] = recursive
         if worker_version is not None:
+            warn(
+                "`worker_version` usage is deprecated. Consider using `worker_run` instead.",
+                DeprecationWarning,
+                stacklevel=1,
+            )
             assert isinstance(
                 worker_version, str | bool
             ), "worker_version should be of type str or bool"
@@ -396,6 +410,15 @@ class TranscriptionMixin:
                     worker_version is False
                 ), "if of type bool, worker_version can only be set to False"
             query_params["worker_version"] = worker_version
+        if worker_run is not None:
+            assert isinstance(
+                worker_run, str | bool
+            ), "worker_run should be of type str or bool"
+            if isinstance(worker_run, bool):
+                assert (
+                    worker_run is False
+                ), "if of type bool, worker_run can only be set to False"
+            query_params["worker_run"] = worker_run
 
         if self.use_cache:
             if not recursive:
@@ -427,10 +450,27 @@ class TranscriptionMixin:
 
             if worker_version is not None:
                 # If worker_version=False, filter by manual worker_version e.g. None
-                worker_version_id = worker_version if worker_version else None
-                transcriptions = transcriptions.where(
-                    CachedTranscription.worker_version_id == worker_version_id
-                )
+                worker_version_id = worker_version or None
+                if worker_version_id:
+                    transcriptions = transcriptions.where(
+                        CachedTranscription.worker_version_id == worker_version_id
+                    )
+                else:
+                    transcriptions = transcriptions.where(
+                        CachedTranscription.worker_version_id.is_null()
+                    )
+
+            if worker_run is not None:
+                # If worker_run=False, filter by manual worker_run e.g. None
+                worker_run_id = worker_run or None
+                if worker_run_id:
+                    transcriptions = transcriptions.where(
+                        CachedTranscription.worker_run_id == worker_run_id
+                    )
+                else:
+                    transcriptions = transcriptions.where(
+                        CachedTranscription.worker_run_id.is_null()
+                    )
         else:
             transcriptions = self.api_client.paginate(
                 "ListTranscriptions", id=element.id, **query_params

arkindex_worker/worker/version.py

@@ -2,10 +2,27 @@
 ElementsWorker methods for worker versions.
 """
 
+import functools
+from warnings import warn
+
+
+def worker_version_deprecation(func):
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        warn("WorkerVersion usage is deprecated.", DeprecationWarning, stacklevel=2)
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
 
 class WorkerVersionMixin:
+    @worker_version_deprecation
     def get_worker_version(self, worker_version_id: str) -> dict:
         """
+        Warns:
+        ----
+        This method is **deprecated**.
+
         Retrieve a worker version, using the [ElementsWorker][arkindex_worker.worker.ElementsWorker]'s internal cache when possible.
 
         :param worker_version_id: ID of the worker version to retrieve.
@@ -22,8 +39,13 @@ class WorkerVersionMixin:
 
         return worker_version
 
+    @worker_version_deprecation
     def get_worker_version_slug(self, worker_version_id: str) -> str:
         """
+        Warns:
+        ----
+        This method is **deprecated**.
+
         Retrieve the slug of the worker of a worker version, from a worker version UUID.
         Uses a worker version from the internal cache if possible, otherwise makes an API request.
 

hooks/pre_gen_project.py

@@ -0,0 +1,3 @@
+# Normalize the slug to generate __package and __module private variables
+{{cookiecutter.update({"__package": cookiecutter.slug.lower().replace("_", "-")})}}  # noqa: F821
+{{cookiecutter.update({"__module": cookiecutter.slug.lower().replace("-", "_")})}}  # noqa: F821