tasktiger 0.26.2__tar.gz → 0.27.0__tar.gz

{tasktiger-0.26.2/tasktiger.egg-info → tasktiger-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktiger
-Version: 0.26.2
+Version: 0.27.0
 Summary: Python task queue
 Home-page: http://github.com/closeio/tasktiger
 License: MIT
@@ -212,6 +212,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.2 → tasktiger-0.27.0}/README.rst

@@ -182,6 +182,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/__init__.py

@@ -12,7 +12,7 @@ from .task import Task
 from .tasktiger import TaskTiger, run_worker
 from .worker import Worker
 
-__version__ = "0.26.2"
+__version__ = "0.27.0"
 __all__ = [
     "TaskTiger",
     "Worker",

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/_internal.py

@@ -15,13 +15,13 @@ from typing import (
     Iterable,
     List,
     Optional,
-    Tuple,
     Type,
     TypedDict,
     Union,
 )
 
 from .exceptions import TaskImportError
+from .types import SerializedRetryStrategy
 
 if TYPE_CHECKING:
     from .task import Task
@@ -134,7 +134,7 @@ def reversed_dotted_parts(s: str) -> Iterable[str]:
         yield s[:idx]
 
 
-def serialize_retry_method(retry_method: Any) -> Tuple[str, Tuple]:
+def serialize_retry_method(retry_method: Any) -> SerializedRetryStrategy:
     if callable(retry_method):
         return (serialize_func_name(retry_method), ())
     else:

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/schedule.py

@@ -1,5 +1,7 @@
 import datetime
-from typing import Callable, Optional, Tuple
+from typing import Optional
+
+from .types import ScheduleStrategy
 
 __all__ = ["periodic", "cron_expr"]
 
@@ -40,7 +42,7 @@ def periodic(
     weeks: int = 0,
     start_date: Optional[datetime.datetime] = None,
     end_date: Optional[datetime.datetime] = None,
-) -> Tuple[Callable[..., Optional[datetime.datetime]], Tuple]:
+) -> ScheduleStrategy:
     """
     Periodic task schedule: Use to schedule a task to run periodically,
     starting from start_date (or None to be active immediately) until end_date
@@ -94,7 +96,7 @@ def cron_expr(
     expr: str,
     start_date: Optional[datetime.datetime] = None,
     end_date: Optional[datetime.datetime] = None,
-) -> Tuple[Callable[..., Optional[datetime.datetime]], Tuple]:
+) -> ScheduleStrategy:
     """
     Periodic task schedule via cron expression: Use to schedule a task to run periodically,
     starting from start_date (or None to be active immediately) until end_date

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/stats.py

@@ -39,6 +39,18 @@ class StatsThread(threading.Thread):
             self._task_running = False
             self._task_start_time = None
 
+    def report_maintenance_start(self) -> None:
+        """Signal the start of scheduled-task promotion and expired-task recovery.
+
+        The default is a no-op and does not alter task statistics.
+        """
+
+    def report_maintenance_end(self) -> None:
+        """Signal the end of scheduled-task promotion and expired-task recovery.
+
+        The default is a no-op and does not alter task statistics.
+        """
+
     def compute_stats(self) -> None:
         now = time.monotonic()
 

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/task.py

@@ -32,7 +32,7 @@ from ._internal import (
 )
 from .exceptions import QueueFullException, TaskImportError, TaskNotFound
 from .runner import BaseRunner, get_runner_class
-from .types import RetryStrategy
+from .types import RetryStrategy, SerializedRetryStrategy
 
 if TYPE_CHECKING:
     from . import TaskTiger
@@ -55,9 +55,7 @@ class Task:
         lock_key: Optional[Collection[str]] = None,
         retry: Optional[bool] = None,
         retry_on: Optional[Collection[Type[BaseException]]] = None,
-        retry_method: Optional[
-            Union[Callable[[int], float], Tuple[Callable[..., float], Tuple]]
-        ] = None,
+        retry_method: Optional[Union[Callable[[int], float], RetryStrategy]] = None,
         max_queue_size: Optional[int] = None,
         max_stored_executions: Optional[int] = None,
         runner_class: Optional[Type["BaseRunner"]] = None,
@@ -237,7 +235,7 @@ class Task:
         return self._data.get("unique_key")
 
     @property
-    def retry_method(self) -> Optional[RetryStrategy]:
+    def retry_method(self) -> Optional[SerializedRetryStrategy]:
         if "retry_method" in self._data:
             retry_func, retry_args = self._data["retry_method"]
             return retry_func, retry_args

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/tasktiger.py

@@ -36,6 +36,7 @@ from .redis_semaphore import Semaphore
 from .retry import fixed
 from .runner import BaseRunner
 from .task import Task
+from .types import RetryStrategy, ScheduleStrategy
 from .worker import LOCK_REDIS_KEY, Worker
 
 __all__ = ["TaskTiger"]
@@ -312,10 +313,13 @@ class TaskTiger:
         lock_key: Optional[Collection[str]] = None,
         retry: Optional[bool] = None,
         retry_on: Optional[Collection[Type[BaseException]]] = None,
-        retry_method: Optional[
-            Union[Callable[[int], float], Tuple[Callable[..., float], Tuple]]
+        retry_method: Optional[Union[Callable[[int], float], RetryStrategy]] = None,
+        schedule: Optional[
+            Union[
+                Callable[[datetime.datetime], Optional[datetime.datetime]],
+                ScheduleStrategy,
+            ]
         ] = None,
-        schedule: Optional[Callable] = None,
         batch: bool = False,
         max_queue_size: Optional[int] = None,
         max_stored_executions: Optional[int] = None,
@@ -441,9 +445,7 @@ class TaskTiger:
         when: Optional[Union[datetime.datetime, datetime.timedelta]] = None,
         retry: Optional[bool] = None,
         retry_on: Optional[Collection[Type[BaseException]]] = None,
-        retry_method: Optional[
-            Union[Callable[[int], float], Tuple[Callable[..., float], Tuple]]
-        ] = None,
+        retry_method: Optional[Union[Callable[[int], float], RetryStrategy]] = None,
         max_queue_size: Optional[int] = None,
         max_stored_executions: Optional[int] = None,
         runner_class: Optional[Type["BaseRunner"]] = None,

tasktiger-0.27.0/tasktiger/types.py

@@ -0,0 +1,9 @@
+import datetime
+from typing import Any, Callable, Optional, Sequence, Tuple
+
+RetryStrategy = Tuple[Callable[..., float], Tuple[Any, ...]]
+ScheduleStrategy = Tuple[Callable[..., Optional[datetime.datetime]], Tuple[Any, ...]]
+
+# A retry strategy as stored with a task. The function is replaced with its
+# import path, and the arguments come back as a list after a JSON round trip.
+SerializedRetryStrategy = Tuple[str, Sequence[Any]]

{tasktiger-0.26.2 → tasktiger-0.27.0}/tasktiger/worker.py

@@ -867,9 +867,15 @@ class Worker:
             time.time() - self._last_task_check > self.config["SELECT_TIMEOUT"]
             and not self._stop_requested
         ):
-            self._worker_queue_scheduled_tasks()
-            self._worker_queue_expired_tasks()
-            self._last_task_check = time.time()
+            if self.stats_thread:
+                self.stats_thread.report_maintenance_start()
+            try:
+                self._worker_queue_scheduled_tasks()
+                self._worker_queue_expired_tasks()
+                self._last_task_check = time.time()
+            finally:
+                if self.stats_thread:
+                    self.stats_thread.report_maintenance_end()
 
     def _queue_periodic_tasks(self) -> None:
         # Only queue periodic tasks for queues this worker is responsible

{tasktiger-0.26.2 → tasktiger-0.27.0/tasktiger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktiger
-Version: 0.26.2
+Version: 0.27.0
 Summary: Python task queue
 Home-page: http://github.com/closeio/tasktiger
 License: MIT
@@ -212,6 +212,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.2 → tasktiger-0.27.0}/tests/test_workers.py

@@ -3,12 +3,15 @@
 import datetime
 import time
 from multiprocessing import Process
+from unittest import mock
 
+import pytest
 from freezefrog import FreezeTime
 
 from tasktiger import Task, Worker
 from tasktiger._internal import ACTIVE
 from tasktiger.executor import SyncExecutor
+from tasktiger.stats import StatsThread
 from tasktiger.worker import LOCK_REDIS_KEY
 
 from .config import DELAY
@@ -265,3 +268,37 @@ class TestSyncExecutorWorker:
         # handled by the executor, the task is still active until it times out
         # and gets requeued by another worker.
         ensure_queues(active={"default": 1})
+
+
+@pytest.mark.parametrize("failing_operation", [None, "scheduled", "expired"])
+def test_maintenance_stats_callbacks(tiger, monkeypatch, failing_operation):
+    worker = Worker(tiger)
+    worker._queue_set = set()
+    calls = mock.Mock()
+    calls.stats = mock.Mock(spec=StatsThread)
+    worker.stats_thread = calls.stats
+    monkeypatch.setattr(worker, "_worker_queue_scheduled_tasks", calls.scheduled)
+    monkeypatch.setattr(worker, "_worker_queue_expired_tasks", calls.expired)
+
+    if failing_operation:
+        getattr(calls, failing_operation).side_effect = RuntimeError("maintenance")
+        with pytest.raises(RuntimeError, match="maintenance"):
+            worker._worker_run()
+    else:
+        worker._worker_run()
+
+    expected = [mock.call.stats.report_maintenance_start(), mock.call.scheduled()]
+    if failing_operation != "scheduled":
+        expected.append(mock.call.expired())
+    expected.append(mock.call.stats.report_maintenance_end())
+    assert calls.mock_calls == expected
+
+
+def test_maintenance_without_stats(tiger, monkeypatch):
+    worker = Worker(tiger)
+    worker._queue_set = set()
+    calls = mock.Mock()
+    monkeypatch.setattr(worker, "_worker_queue_scheduled_tasks", calls.scheduled)
+    monkeypatch.setattr(worker, "_worker_queue_expired_tasks", calls.expired)
+    worker._worker_run()
+    assert calls.mock_calls == [mock.call.scheduled(), mock.call.expired()]

tasktiger-0.26.2/tasktiger/types.py

@@ -1,3 +0,0 @@
-from typing import Callable, Tuple
-
-RetryStrategy = Tuple[Callable[..., float], Tuple]