Deprecate `worker_version` usage and support `worker_run` where it was missing

Closes #186 (closed)

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