django-lambda-tasks 0.4.3__tar.gz → 0.4.5__tar.gz

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/.kiro/steering/product.md

@@ -39,7 +39,14 @@ def my_task(*, user_id: int, action: str) -> None:
 
 ## Enqueuing
 
-`execute_on_commit()` uses the decorator `delay` value. There are no per-call overrides.
+`execute_on_commit()` uses the decorator `delay` value by default. Pass `_delay=<seconds>` at call time to override the delay for that specific enqueue:
+
+```python
+my_task.execute_on_commit(user_id=1, action="x")            # uses decorator delay
+my_task.execute_on_commit(user_id=1, action="x", _delay=60) # overrides with 60s
+```
+
+The `_delay` override is validated against the same range `[0, 900]` as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
 
 ## ignore_errors
 

django_lambda_tasks-0.4.3/README.md → django_lambda_tasks-0.4.5/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.4
+Name: django-lambda-tasks
+Version: 0.4.5
+Summary: Run async tasks in a lambda function
+Requires-Python: >=3.10
+Requires-Dist: awslambdaric
+Requires-Dist: boto3
+Requires-Dist: django
+Requires-Dist: pydantic
+Requires-Dist: redis
+Description-Content-Type: text/markdown
+
 # Django Lambda Tasks
 
 A Django library for offloading work to AWS Lambda outside of the request-response cycle. Tasks are defined with a decorator, enqueued to SQS on transaction commit, and executed by a Lambda handler that AWS invokes with SQS message batches. Task results, status, and metadata are persisted in the Django database.
@@ -59,6 +71,13 @@ def register(request):
     return HttpResponse("Registered")
 ```
 
+You can override the delay for a specific enqueue by passing `_delay`:
+
+```python
+# Delay this particular invocation by 60 seconds instead of the decorator default
+send_welcome_email.execute_on_commit(user_id=user.id, template="welcome", _delay=60)
+```
+
 ### 3. Configure AWS
 
 See [AWS Lambda and SQS setup](#aws-lambda-and-sqs-setup) for queue and Lambda configuration.
@@ -208,6 +227,24 @@ def my_task(*, arg: str) -> None:
 | `retry_delay` | `int` | `0` | Base delay in seconds when enqueuing a retry. Jitter (1–5s) is always added; result capped at 900. Requires `retry_on` to be non-empty. |
 | `singleton` | `bool` | `False` | Prevent concurrent execution via a Redis lock (see [Singleton tasks](#singleton-tasks)). |
 
+### Per-call delay override
+
+The `delay` decorator parameter sets the default SQS `DelaySeconds` for all invocations of a task. To override it for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
+
+```python
+@lambda_task(delay=0)
+def notify_user(*, user_id: int) -> None:
+    ...
+
+# Uses the decorator default (0 seconds)
+notify_user.execute_on_commit(user_id=1)
+
+# Override: delay this specific invocation by 120 seconds
+notify_user.execute_on_commit(user_id=1, _delay=120)
+```
+
+`_delay` is validated against the same `[0, 900]` range as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
+
 ---
 
 ## Serializing a task invocation

django_lambda_tasks-0.4.3/PKG-INFO → django_lambda_tasks-0.4.5/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: django-lambda-tasks
-Version: 0.4.3
-Summary: Run async tasks in a lambda function
-Requires-Python: >=3.10
-Requires-Dist: awslambdaric
-Requires-Dist: boto3
-Requires-Dist: django
-Requires-Dist: pydantic
-Requires-Dist: redis
-Description-Content-Type: text/markdown
-
 # Django Lambda Tasks
 
 A Django library for offloading work to AWS Lambda outside of the request-response cycle. Tasks are defined with a decorator, enqueued to SQS on transaction commit, and executed by a Lambda handler that AWS invokes with SQS message batches. Task results, status, and metadata are persisted in the Django database.
@@ -71,6 +59,13 @@ def register(request):
     return HttpResponse("Registered")
 ```
 
+You can override the delay for a specific enqueue by passing `_delay`:
+
+```python
+# Delay this particular invocation by 60 seconds instead of the decorator default
+send_welcome_email.execute_on_commit(user_id=user.id, template="welcome", _delay=60)
+```
+
 ### 3. Configure AWS
 
 See [AWS Lambda and SQS setup](#aws-lambda-and-sqs-setup) for queue and Lambda configuration.
@@ -220,6 +215,24 @@ def my_task(*, arg: str) -> None:
 | `retry_delay` | `int` | `0` | Base delay in seconds when enqueuing a retry. Jitter (1–5s) is always added; result capped at 900. Requires `retry_on` to be non-empty. |
 | `singleton` | `bool` | `False` | Prevent concurrent execution via a Redis lock (see [Singleton tasks](#singleton-tasks)). |
 
+### Per-call delay override
+
+The `delay` decorator parameter sets the default SQS `DelaySeconds` for all invocations of a task. To override it for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
+
+```python
+@lambda_task(delay=0)
+def notify_user(*, user_id: int) -> None:
+    ...
+
+# Uses the decorator default (0 seconds)
+notify_user.execute_on_commit(user_id=1)
+
+# Override: delay this specific invocation by 120 seconds
+notify_user.execute_on_commit(user_id=1, _delay=120)
+```
+
+`_delay` is validated against the same `[0, 900]` range as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
+
 ---
 
 ## Serializing a task invocation

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/lambda_tasks/decorators.py

@@ -19,7 +19,7 @@ import pydantic
 from redis.exceptions import LockError
 
 from lambda_tasks.models import SQSLambdaTask, SQSLambdaTaskMessage
-from lambda_tasks.settings import MAX_TIMEOUT, LambdaTasksSettings
+from lambda_tasks.settings import MAX_DELAY, MAX_TIMEOUT, LambdaTasksSettings
 
 
 def _build_kwargs_model(func: types.FunctionType) -> type[pydantic.BaseModel]:
@@ -154,13 +154,17 @@ class LambdaTaskWrapper:
     def _build_task(self, *, kwargs: dict[str, Any]) -> SQSLambdaTask:
         """Pop overrides, validate kwargs, and build a SQSLambdaTask.
 
-        Mutates *kwargs* in-place (pops ``_n_retries``).
+        Mutates *kwargs* in-place (pops ``_n_retries``, ``_delay``).
         Returns ``SQSLambdaTask``.
 
         Raises:
             pydantic.ValidationError: if the remaining kwargs fail type validation.
+            ValueError: if ``_delay`` is outside the allowed range [0, 900].
         """
         n_retries = kwargs.pop("_n_retries", 0)
+        delay = kwargs.pop("_delay", self._delay)
+
+        self._validate_delay(delay=delay)
 
         self._kwargs_model.model_validate(kwargs)
 
@@ -172,7 +176,7 @@ class LambdaTaskWrapper:
 
         return SQSLambdaTask(
             message=message,
-            delay=self._delay,
+            delay=delay,
             queue=self._queue,
         )
 
@@ -253,9 +257,9 @@ class LambdaTaskWrapper:
 
     @staticmethod
     def _validate_delay(*, delay: int) -> None:
-        """Raise ValueError if delay is outside the allowed range [0, 900]."""
-        if delay < 0 or delay > 900:
-            raise ValueError(f"delay ({delay}) must be in the range [0, 900].")
+        """Raise ValueError if delay is outside the allowed range [0, MAX_DELAY]."""
+        if delay < 0 or delay > MAX_DELAY:
+            raise ValueError(f"delay ({delay}) must be in the range [0, {MAX_DELAY}].")
 
     @staticmethod
     def _validate_retry_delay(
@@ -263,10 +267,10 @@ class LambdaTaskWrapper:
         retry_delay: int,
         retry_on: tuple[type[BaseException], ...],
     ) -> None:
-        """Raise ValueError if retry_delay is outside [0, 900], or TypeError if retry_delay != 0 and retry_on is empty."""
-        if retry_delay < 0 or retry_delay > 900:
+        """Raise ValueError if retry_delay is outside [0, MAX_DELAY], or TypeError if retry_delay != 0 and retry_on is empty."""
+        if retry_delay < 0 or retry_delay > MAX_DELAY:
             raise ValueError(
-                f"retry_delay ({retry_delay}) must be in the range [0, 900]."
+                f"retry_delay ({retry_delay}) must be in the range [0, {MAX_DELAY}]."
             )
 
         if retry_delay != 0 and not retry_on:

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/lambda_tasks/settings.py

@@ -1,7 +1,10 @@
+from typing import Final
+
 from django.conf import settings as django_settings
 from django.core.exceptions import ImproperlyConfigured
 
-MAX_TIMEOUT = 900
+MAX_DELAY: Final = 900
+MAX_TIMEOUT: Final = 900
 
 
 class LambdaTasksSettings:

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.4.3"
+version = "0.4.5"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
 requires-python = ">=3.10"

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/tests/test_decorator.py

@@ -82,13 +82,23 @@ class TestLambdaTaskWrapperOnCommit:
 
     def test_on_commit_accepts_delay_override(self):
         wrapper = LambdaTaskWrapper(sample_task)
-        with pytest.raises(pydantic.ValidationError):
+        captured: list = []
+        with patch(
+            "lambda_tasks.models.transaction.on_commit",
+            side_effect=lambda cb: captured.append(cb),
+        ):
             wrapper.execute_on_commit(x=1, _delay=10)
+        assert captured[0].__self__.delay == 10
 
     def test_on_commit_accepts_delay_and_task_kwargs(self):
         wrapper = LambdaTaskWrapper(sample_task)
-        with pytest.raises(pydantic.ValidationError):
+        captured: list = []
+        with patch(
+            "lambda_tasks.models.transaction.on_commit",
+            side_effect=lambda cb: captured.append(cb),
+        ):
             wrapper.execute_on_commit(x=1, y="test", _delay=5)
+        assert captured[0].__self__.delay == 5
 
 
 # ---------------------------------------------------------------------------

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/tests/test_decorators.py

@@ -251,21 +251,30 @@ def test_queue_property_defaults_to_default():
 # ---------------------------------------------------------------------------
 
 
-def test_passing_delay_kwarg_to_execute_on_commit_raises_validation_error():
-    """Passing _delay to execute_on_commit raises pydantic.ValidationError. Requirement 4.1, 4.2"""
+def test_passing_delay_kwarg_to_execute_on_commit_overrides_decorator_delay():
+    """Passing _delay to _build_task overrides the decorator delay. Requirement 4.1, 4.2"""
     wrapper = LambdaTaskWrapper(_make_func(), delay=10)
-    with pytest.raises(pydantic.ValidationError):
-        wrapper._build_task(kwargs={"x": 1, "_delay": 5})
+    task = wrapper._build_task(kwargs={"x": 1, "_delay": 5})
+    assert task.delay == 5
 
 
 def test_build_task_uses_decorator_delay_not_call_time_override():
-    """_build_task uses the decorator delay, not a call-time override. Requirement 4.3"""
+    """_build_task uses the decorator delay when no _delay override is given. Requirement 4.3"""
     decorator_delay = 42
     wrapper = LambdaTaskWrapper(_make_func(), delay=decorator_delay)
     task = wrapper._build_task(kwargs={"x": 1})
     assert task.delay == decorator_delay
 
 
+def test_build_task_delay_override_validates_range():
+    """_delay outside [0, 900] raises ValueError."""
+    wrapper = LambdaTaskWrapper(_make_func(), delay=10)
+    with pytest.raises(ValueError):
+        wrapper._build_task(kwargs={"x": 1, "_delay": -1})
+    with pytest.raises(ValueError):
+        wrapper._build_task(kwargs={"x": 1, "_delay": 901})
+
+
 # ---------------------------------------------------------------------------
 # Unit tests: lambda_task forwarding retry_delay (Requirements 1.1, 1.2)
 # ---------------------------------------------------------------------------

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/tests/test_deferred_enqueue.py

@@ -44,9 +44,9 @@ def test_to_json_uses_decorator_defaults_for_delay_and_queue():
 
 
 def test_to_json_uses_call_site_override_for_delay():
-    """_delay at call site is no longer supported — it raises pydantic.ValidationError."""
-    with pytest.raises(ValidationError):
-        _wrapper.serialize(x=1, _delay=30)
+    """_delay at call site overrides the decorator default."""
+    result = _wrapper.serialize(x=1, _delay=30)
+    assert result["delay"] == 30
 
 
 def test_to_json_task_name_matches_module_qualname():

{django_lambda_tasks-0.4.3 → django_lambda_tasks-0.4.5}/tests/test_models.py

@@ -1649,17 +1649,22 @@ def test_normal_execute_on_commit_uses_decorator_delay(settings, decorator_delay
     assert mock_client.send_message.call_args.kwargs["DelaySeconds"] == decorator_delay
 
 
-def test_passing_delay_to_execute_on_commit_raises_validation_error():
-    """Passing _delay to execute_on_commit raises ValidationError (extra='forbid' on kwargs model).
+def test_passing_delay_to_execute_on_commit_overrides_decorator_delay():
+    """Passing _delay to execute_on_commit overrides the decorator delay.
     Validates: Requirements 4.1, 4.2"""
-    from pydantic import ValidationError
+    from unittest.mock import patch
 
-    @lambda_task
+    @lambda_task(delay=10)
     def _task_simple(*, x: int) -> None:
         pass
 
-    with pytest.raises(ValidationError):
+    captured: list = []
+    with patch(
+        "lambda_tasks.models.transaction.on_commit",
+        side_effect=lambda cb: captured.append(cb),
+    ):
         _task_simple.execute_on_commit(x=1, _delay=5)
+    assert captured[0].__self__.delay == 5
 
 
 # ---------------------------------------------------------------------------