arkindex-base-worker 0.4.0b3__tar.gz → 0.4.0rc1__tar.gz

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: arkindex-base-worker
-Version: 0.4.0b3
+Version: 0.4.0rc1
 Summary: Base Worker to easily build Arkindex ML workflows
 Author-email: Teklia <contact@teklia.com>
 Maintainer-email: Teklia <contact@teklia.com>
@@ -40,6 +40,7 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: humanize==4.9.0
 Requires-Dist: peewee~=3.17
 Requires-Dist: Pillow==10.4.0
 Requires-Dist: python-gnupg==0.5.2
@@ -49,7 +50,7 @@ Requires-Dist: zstandard==0.22.0
 Provides-Extra: docs
 Requires-Dist: black==24.4.2; extra == "docs"
 Requires-Dist: mkdocs-material==9.5.31; extra == "docs"
-Requires-Dist: mkdocstrings-python==1.10.7; extra == "docs"
+Requires-Dist: mkdocstrings-python==1.10.8; extra == "docs"
 Provides-Extra: tests
 Requires-Dist: pytest==8.3.2; extra == "tests"
 Requires-Dist: pytest-mock==3.14.0; extra == "tests"

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_base_worker.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: arkindex-base-worker
-Version: 0.4.0b3
+Version: 0.4.0rc1
 Summary: Base Worker to easily build Arkindex ML workflows
 Author-email: Teklia <contact@teklia.com>
 Maintainer-email: Teklia <contact@teklia.com>
@@ -40,6 +40,7 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: humanize==4.9.0
 Requires-Dist: peewee~=3.17
 Requires-Dist: Pillow==10.4.0
 Requires-Dist: python-gnupg==0.5.2
@@ -49,7 +50,7 @@ Requires-Dist: zstandard==0.22.0
 Provides-Extra: docs
 Requires-Dist: black==24.4.2; extra == "docs"
 Requires-Dist: mkdocs-material==9.5.31; extra == "docs"
-Requires-Dist: mkdocstrings-python==1.10.7; extra == "docs"
+Requires-Dist: mkdocstrings-python==1.10.8; extra == "docs"
 Provides-Extra: tests
 Requires-Dist: pytest==8.3.2; extra == "tests"
 Requires-Dist: pytest-mock==3.14.0; extra == "tests"

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_base_worker.egg-info/requires.txt

@@ -1,3 +1,4 @@
+humanize==4.9.0
 peewee~=3.17
 Pillow==10.4.0
 python-gnupg==0.5.2
@@ -8,7 +9,7 @@ zstandard==0.22.0
 [docs]
 black==24.4.2
 mkdocs-material==9.5.31
-mkdocstrings-python==1.10.7
+mkdocstrings-python==1.10.8
 
 [tests]
 pytest==8.3.2

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_worker/image.py

@@ -2,13 +2,18 @@
 Helper methods to download and open IIIF images, and manage polygons.
 """
 
+import functools
+import os
 import re
+import tempfile
 from collections import namedtuple
+from collections.abc import Generator, Iterator
 from io import BytesIO
 from math import ceil
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+import humanize
 import requests
 from PIL import Image
 from shapely.affinity import rotate, scale, translate
@@ -40,8 +45,57 @@ IIIF_URL = re.compile(r"\w+:\/{2}.+\/.+\/.+\/.+\/(?P<size>.+)\/!?\d+\/\w+\.\w+")
 IIIF_FULL = "full"
 # Maximum size available
 IIIF_MAX = "max"
+# Ratio to resize image
+IMAGE_RATIO = [1, 0.9, 0.85, 0.80, 0.75, 0.70, 0.60, 0.50, 0.40, 0.30]
 
 
+def update_pillow_image_size_limit(func):
+    """
+    Update Pillow Image size limit
+    """
+
+    @functools.wraps(func)
+    def wrapper(
+        *args,
+        max_image_pixels: str | int | None = os.getenv("ARKINDEX_MAX_IMAGE_PIXELS"),
+        **kwargs,
+    ):
+        """
+        Wrapper to update Pillow Image size limit and restore it at the end of the function.
+
+        :param *args: Positional arguments passed to the function.
+        :param max_image_pixels: Pillow Image size limit to use.
+        :param **kwargs: Keyword arguments passed to the function.
+        """
+        MAX_IMAGE_PIXELS = Image.MAX_IMAGE_PIXELS
+
+        # Override Pillow Image size limit
+        if max_image_pixels is not None:
+            max_image_pixels = int(max_image_pixels)
+            # Override Pillow limit for detecting decompression bombs, disabled if set to 0
+            if max_image_pixels == 0:
+                logger.warning(
+                    "Pillow Image size limit is completely disabled, make sure you trust the image source."
+                )
+                Image.MAX_IMAGE_PIXELS = None
+            else:
+                Image.MAX_IMAGE_PIXELS = max_image_pixels
+
+        try:
+            results = func(*args, **kwargs)
+        except:
+            # Restore initial Pillow Image size limit
+            Image.MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS
+            raise
+
+        # Restore initial Pillow Image size limit
+        Image.MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS
+        return results
+
+    return wrapper
+
+
+@update_pillow_image_size_limit
 def open_image(
     path: str,
     mode: str | None = "RGB",
@@ -149,6 +203,70 @@ def upload_image(image: Image, url: str) -> requests.Response:
     return resp
 
 
+def resized_images(
+    *args,
+    element: "Element",
+    max_pixels: int | None = None,
+    max_bytes: int | None = None,
+    **kwargs,
+) -> Iterator[Generator[tempfile.NamedTemporaryFile, None, None]]:
+    """
+    Build resized images according to the pixel and byte limits.
+
+    :param *args: Positional arguments passed to [arkindex_worker.models.Element.open_image_tempfile][].
+    :param element: Element whose image needs to be resized.
+    :param max_pixels: Maximum pixel size of the resized images.
+    :param max_bytes: Maximum byte size of the resized images.
+    :param **kwargs: Keyword arguments passed to [arkindex_worker.models.Element.open_image_tempfile][].
+    :returns: An iterator of the temporary file of the resized image.
+    """
+    _, _, element_width, element_height = polygon_bounding_box(element.polygon)
+
+    logger.info(f"This element's image sizes are ({element_width} x {element_height}).")
+    if max_pixels and max(element_width, element_height) > max_pixels:
+        logger.warning(
+            f"Maximum image input size supported is ({max_pixels} x {max_pixels})."
+        )
+        logger.warning("The image will be resized.")
+
+    element_pixel, param = (
+        (element_width, "max_width")
+        if element_width > element_height
+        else (element_height, "max_height")
+    )
+
+    for resized_pixel in sorted(
+        set(
+            min(round(ratio * element_pixel), max_pixels or element_pixel)
+            for ratio in IMAGE_RATIO
+        ),
+        reverse=True,
+    ):
+        with element.open_image_tempfile(
+            *args, **{**kwargs, param: resized_pixel}
+        ) as image:
+            pillow_image = Image.open(image)
+            if (
+                pillow_image.width != element_width
+                or pillow_image.height != element_height
+            ):
+                logger.warning(
+                    f"The image was resized to ({pillow_image.width} x {pillow_image.height})."
+                )
+
+            # The image is still too large
+            image_size = Path(image.name).stat().st_size
+            if max_bytes and image_size > max_bytes:
+                logger.warning(f"The image size is {humanize.naturalsize(image_size)}.")
+                logger.warning(
+                    f"Maximum image input size supported is {humanize.naturalsize(max_bytes)}."
+                )
+                logger.warning("The image will be resized.")
+                continue
+
+            yield image
+
+
 def polygon_bounding_box(polygon: list[list[int | float]]) -> BoundingBox:
     """
     Compute the rectangle bounding box of a polygon.

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_worker/worker/__init__.py

@@ -111,7 +111,7 @@ class ElementsWorker(
             help="One or more Arkindex element ID",
         )
 
-    def list_elements(self) -> Iterable[CachedElement] | list[str]:
+    def get_elements(self) -> Iterable[CachedElement] | list[str]:
         """
         List the elements to be processed, either from the CLI arguments or
         the cache database when enabled.
@@ -173,33 +173,10 @@ class ElementsWorker(
         ), "Worker must be configured to access its process activity state"
         return self.process_information.get("activity_state") == "ready"
 
-    def configure(self):
-        """
-        Setup the worker using CLI arguments and environment variables.
-        """
-        # CLI args are stored on the instance so that implementations can access them
-        self.args = self.parser.parse_args()
-
-        if self.is_read_only:
-            super().configure_for_developers()
-        else:
-            super().configure()
-            super().configure_cache()
-
-        # Retrieve the model configuration
-        if self.model_configuration:
-            self.config.update(self.model_configuration)
-            logger.info("Model version configuration retrieved")
-
-        # Retrieve the user configuration
-        if self.user_configuration:
-            self.config.update(self.user_configuration)
-            logger.info("User configuration retrieved")
-
     def run(self):
         """
         Implements an Arkindex worker that goes through each element returned by
-        [list_elements][arkindex_worker.worker.ElementsWorker.list_elements].
+        [get_elements][arkindex_worker.worker.ElementsWorker.get_elements].
         It calls [process_element][arkindex_worker.worker.ElementsWorker.process_element],
         catching exceptions, and handles saving WorkerActivity updates when enabled.
         """
@@ -207,7 +184,7 @@ class ElementsWorker(
 
         # List all elements either from JSON file
         # or direct list of elements on CLI
-        elements = self.list_elements()
+        elements = self.get_elements()
         if not elements:
             logger.warning("No elements to process, stopping.")
             sys.exit(1)
@@ -224,7 +201,7 @@ class ElementsWorker(
             element = None
             try:
                 if self.use_cache:
-                    # Just use the result of list_elements as the element
+                    # Just use the result of get_elements as the element
                     element = item
                 else:
                     # Load element using the Arkindex API
@@ -397,29 +374,6 @@ class DatasetWorker(BaseWorker, DatasetMixin, TaskMixin):
             default=[],
         )
 
-    def configure(self):
-        """
-        Setup the worker using CLI arguments and environment variables.
-        """
-        # CLI args are stored on the instance so that implementations can access them
-        self.args = self.parser.parse_args()
-
-        if self.is_read_only:
-            super().configure_for_developers()
-        else:
-            super().configure()
-            super().configure_cache()
-
-        # Retrieve the model configuration
-        if self.model_configuration:
-            self.config.update(self.model_configuration)
-            logger.info("Model version configuration retrieved")
-
-        # Retrieve the user configuration
-        if self.user_configuration:
-            self.config.update(self.user_configuration)
-            logger.info("User configuration retrieved")
-
     def cleanup_downloaded_artifact(self) -> None:
         """
         Cleanup the downloaded dataset artifact if any

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_worker/worker/base.py

@@ -219,7 +219,7 @@ class BaseWorker:
         # Load all required secrets
         self.secrets = {name: self.load_secret(Path(name)) for name in required_secrets}
 
-    def configure(self):
+    def configure_worker_run(self):
         """
         Setup the necessary configuration needed using CLI args and environment variables.
         This is the method called when running a worker on Arkindex.
@@ -320,6 +320,29 @@ class BaseWorker:
         else:
             logger.debug("Cache is disabled")
 
+    def configure(self):
+        """
+        Setup the worker using CLI arguments and environment variables.
+        """
+        # CLI args are stored on the instance so that implementations can access them
+        self.args = self.parser.parse_args()
+
+        if self.is_read_only:
+            self.configure_for_developers()
+        else:
+            self.configure_worker_run()
+            self.configure_cache()
+
+        # Retrieve the model configuration
+        if self.model_configuration:
+            self.config.update(self.model_configuration)
+            logger.info("Model version configuration retrieved")
+
+        # Retrieve the user configuration
+        if self.user_configuration:
+            self.config.update(self.user_configuration)
+            logger.info("User configuration retrieved")
+
     def load_secret(self, name: Path):
         """
         Load a Ponos secret by name.

{arkindex_base_worker-0.4.0b3 → arkindex_base_worker-0.4.0rc1}/arkindex_worker/worker/element.py

@@ -483,6 +483,178 @@ class ElementMixin:
 
         return updated_element
 
+    def list_elements(
+        self,
+        folder: bool | None = None,
+        name: str | None = None,
+        top_level: bool | None = None,
+        transcription_worker_version: str | bool | None = None,
+        transcription_worker_run: str | bool | None = None,
+        type: str | None = None,
+        with_classes: bool | None = None,
+        with_corpus: bool | None = None,
+        with_metadata: bool | None = None,
+        with_has_children: bool | None = None,
+        with_zone: bool | None = None,
+        worker_version: str | bool | None = None,
+        worker_run: str | bool | None = None,
+    ) -> Iterable[dict] | Iterable[CachedElement]:
+        """
+        List element in a corpus.
+
+        Warns:
+        ----
+        The following parameters are **deprecated**:
+
+        - `transcription_worker_version` in favor of `transcription_worker_run`
+        - `worker_version` in favor of `worker_run`
+
+        :param folder: Restrict to or exclude elements with folder types.
+           This parameter is not supported when caching is enabled.
+        :param name: Restrict to elements whose name contain a substring (case-insensitive).
+           This parameter is not supported when caching is enabled.
+        :param top_level: Restrict to or exclude folder elements without parent elements (top-level elements).
+           This parameter is not supported when caching is enabled.
+        :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. 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.
+        :param with_classes: Include each element's classifications in the response.
+           This parameter is not supported when caching is enabled.
+        :param with_corpus: Include each element's corpus in the response.
+           This parameter is not supported when caching is enabled.
+        :param with_has_children: Include the ``has_children`` attribute in the response,
+           indicating if this element has child elements of its own.
+           This parameter is not supported when caching is enabled.
+        :param with_metadata: Include each element's metadata in the response.
+           This parameter is not supported when caching is enabled.
+        :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: **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.
+        """
+        query_params = {}
+        if folder is not None:
+            assert isinstance(folder, bool), "folder should be of type bool"
+            query_params["folder"] = folder
+        if name:
+            assert isinstance(name, str), "name should be of type str"
+            query_params["name"] = name
+        if top_level is not None:
+            assert isinstance(top_level, bool), "top_level should be of type bool"
+            query_params["top_level"] = top_level
+        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"
+            if isinstance(transcription_worker_version, bool):
+                assert (
+                    transcription_worker_version is False
+                ), "if of type bool, transcription_worker_version can only be set to False"
+            query_params["transcription_worker_version"] = transcription_worker_version
+        if transcription_worker_run is not None:
+            assert isinstance(
+                transcription_worker_run, str | bool
+            ), "transcription_worker_run should be of type str or bool"
+            if isinstance(transcription_worker_run, bool):
+                assert (
+                    transcription_worker_run is False
+                ), "if of type bool, transcription_worker_run can only be set to False"
+            query_params["transcription_worker_run"] = transcription_worker_run
+        if type:
+            assert isinstance(type, str), "type should be of type str"
+            query_params["type"] = type
+        if with_classes is not None:
+            assert isinstance(with_classes, bool), "with_classes should be of type bool"
+            query_params["with_classes"] = with_classes
+        if with_corpus is not None:
+            assert isinstance(with_corpus, bool), "with_corpus should be of type bool"
+            query_params["with_corpus"] = with_corpus
+        if with_has_children is not None:
+            assert isinstance(
+                with_has_children, bool
+            ), "with_has_children should be of type bool"
+            query_params["with_has_children"] = with_has_children
+        if with_metadata is not None:
+            assert isinstance(
+                with_metadata, bool
+            ), "with_metadata should be of type bool"
+            query_params["with_metadata"] = with_metadata
+        if with_zone is not None:
+            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"
+            if isinstance(worker_version, bool):
+                assert (
+                    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 not self.use_cache:
+            return self.api_client.paginate(
+                "ListElements", corpus=self.corpus_id, **query_params
+            )
+
+        # Checking that we only received query_params handled by the cache
+        assert (
+            set(query_params.keys())
+            <= {
+                "type",
+                "worker_version",
+                "worker_run",
+            }
+        ), "When using the local cache, you can only filter by 'type' and/or 'worker_version' and/or 'worker_run'"
+
+        query = CachedElement.select()
+        if type:
+            query = query.where(CachedElement.type == type)
+        if worker_version is not None:
+            # If worker_version=False, filter by manual worker_version e.g. None
+            worker_version_id = worker_version or None
+            if worker_version_id:
+                query = query.where(
+                    CachedElement.worker_version_id == worker_version_id
+                )
+            else:
+                query = query.where(CachedElement.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:
+                query = query.where(CachedElement.worker_run_id == worker_run_id)
+            else:
+                query = query.where(CachedElement.worker_run_id.is_null())
+
+        return query
+
     def list_element_children(
         self,
         element: Element | CachedElement,
@@ -622,45 +794,43 @@ class ElementMixin:
                 ), "if of type bool, worker_run can only be set to False"
             query_params["worker_run"] = worker_run
 
-        if self.use_cache:
-            # Checking that we only received query_params handled by the cache
-            assert (
-                set(query_params.keys())
-                <= {
-                    "type",
-                    "worker_version",
-                    "worker_run",
-                }
-            ), "When using the local cache, you can only filter by 'type' and/or 'worker_version' and/or 'worker_run'"
-
-            query = CachedElement.select().where(CachedElement.parent_id == element.id)
-            if type:
-                query = query.where(CachedElement.type == type)
-            if worker_version is not None:
-                # If worker_version=False, filter by manual worker_version e.g. None
-                worker_version_id = worker_version or None
-                if worker_version_id:
-                    query = query.where(
-                        CachedElement.worker_version_id == worker_version_id
-                    )
-                else:
-                    query = query.where(CachedElement.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:
-                    query = query.where(CachedElement.worker_run_id == worker_run_id)
-                else:
-                    query = query.where(CachedElement.worker_run_id.is_null())
-
-            return query
-        else:
-            children = self.api_client.paginate(
+        if not self.use_cache:
+            return self.api_client.paginate(
                 "ListElementChildren", id=element.id, **query_params
             )
 
-        return children
+        # Checking that we only received query_params handled by the cache
+        assert (
+            set(query_params.keys())
+            <= {
+                "type",
+                "worker_version",
+                "worker_run",
+            }
+        ), "When using the local cache, you can only filter by 'type' and/or 'worker_version' and/or 'worker_run'"
+
+        query = CachedElement.select().where(CachedElement.parent_id == element.id)
+        if type:
+            query = query.where(CachedElement.type == type)
+        if worker_version is not None:
+            # If worker_version=False, filter by manual worker_version e.g. None
+            worker_version_id = worker_version or None
+            if worker_version_id:
+                query = query.where(
+                    CachedElement.worker_version_id == worker_version_id
+                )
+            else:
+                query = query.where(CachedElement.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:
+                query = query.where(CachedElement.worker_run_id == worker_run_id)
+            else:
+                query = query.where(CachedElement.worker_run_id.is_null())
+
+        return query
 
     def list_element_parents(
         self,
@@ -801,45 +971,43 @@ class ElementMixin:
                 ), "if of type bool, worker_run can only be set to False"
             query_params["worker_run"] = worker_run
 
-        if self.use_cache:
-            # Checking that we only received query_params handled by the cache
-            assert (
-                set(query_params.keys())
-                <= {
-                    "type",
-                    "worker_version",
-                    "worker_run",
-                }
-            ), "When using the local cache, you can only filter by 'type' and/or 'worker_version' and/or 'worker_run'"
-
-            parent_ids = CachedElement.select(CachedElement.parent_id).where(
-                CachedElement.id == element.id
-            )
-            query = CachedElement.select().where(CachedElement.id.in_(parent_ids))
-            if type:
-                query = query.where(CachedElement.type == type)
-            if worker_version is not None:
-                # If worker_version=False, filter by manual worker_version e.g. None
-                worker_version_id = worker_version or None
-                if worker_version_id:
-                    query = query.where(
-                        CachedElement.worker_version_id == worker_version_id
-                    )
-                else:
-                    query = query.where(CachedElement.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:
-                    query = query.where(CachedElement.worker_run_id == worker_run_id)
-                else:
-                    query = query.where(CachedElement.worker_run_id.is_null())
-
-            return query
-        else:
-            parents = self.api_client.paginate(
+        if not self.use_cache:
+            return self.api_client.paginate(
                 "ListElementParents", id=element.id, **query_params
             )
 
-        return parents
+        # Checking that we only received query_params handled by the cache
+        assert (
+            set(query_params.keys())
+            <= {
+                "type",
+                "worker_version",
+                "worker_run",
+            }
+        ), "When using the local cache, you can only filter by 'type' and/or 'worker_version' and/or 'worker_run'"
+
+        parent_ids = CachedElement.select(CachedElement.parent_id).where(
+            CachedElement.id == element.id
+        )
+        query = CachedElement.select().where(CachedElement.id.in_(parent_ids))
+        if type:
+            query = query.where(CachedElement.type == type)
+        if worker_version is not None:
+            # If worker_version=False, filter by manual worker_version e.g. None
+            worker_version_id = worker_version or None
+            if worker_version_id:
+                query = query.where(
+                    CachedElement.worker_version_id == worker_version_id
+                )
+            else:
+                query = query.where(CachedElement.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:
+                query = query.where(CachedElement.worker_run_id == worker_run_id)
+            else:
+                query = query.where(CachedElement.worker_run_id.is_null())
+
+        return query