django-lambda-tasks 0.2.1__tar.gz → 0.2.2__tar.gz

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/.kiro/steering/product.md

@@ -15,7 +15,7 @@ View → @lambda_task.execute_on_commit() → SQS → Lambda handler → SQSLamb
 Key modules:
 - `decorators.py` — `@lambda_task` decorator and `LambdaTaskWrapper`
 - `models.py` — `TaskRecord` (Django ORM), `SQSLambdaTaskMessage` (SQS schema + execution), `SQSLambdaTask` (routing + SQS publish)
-- `handler.py` — AWS Lambda entry point with partial-batch failure reporting
+- `handler.py` — AWS Lambda entry point; cold-start init runs on first invocation (not at import time) with partial-batch failure reporting
 - `logging.py` — `task_logger` for invocation-scoped log output
 - `settings.py` — lazy `LambdaTasksSettings` reading from Django settings
 
@@ -135,7 +135,8 @@ class SQSLambdaTaskMessage(BaseModel):
 - Returns `{"batchItemFailures": [...]}` for partial-batch failure reporting
 - Only pre-execution failures (malformed message, import error, misconfiguration) are reported as `batchItemFailures` — task logic failures are caught and recorded as `FAILED` TaskRecords without raising
 - Recommended SQS queue settings: `maxReceiveCount=1` with a DLQ configured; automatic retries are not useful since task failures are not re-driven by design
-- Cold-start sequence: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`
+- Cold-start sequence runs inside the handler on the first invocation (not at module import time) to avoid Lambda init-duration timeouts: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`
+- A module-level `_cold_start_done` sentinel ensures the sequence runs only once; subsequent warm invocations skip it
 - Both loaders run unconditionally (outside the `DJANGO_SETTINGS_MODULE` check) — the environment secret may provide that var, and individual secrets may depend on environment-loaded vars
 
 ## Environment Loader

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/.kiro/steering/structure.md

@@ -40,7 +40,7 @@ django-lambda-tasks/
 
 - `decorators.py` — defines `@lambda_task`; enforces kwargs-only at decoration time
 - `models.py` — `TaskRecord` (Django ORM), `SQSLambdaTaskMessage` (Pydantic, SQS schema + execution logic), `SQSLambdaTask` (Pydantic, holds message + routing; `_execute()` publishes to SQS or executes eagerly; `execute_on_commit()` registers `_execute` with `transaction.on_commit`)
-- `handler.py` — Lambda entry point; calls `resolve_environment()` then `resolve_secrets_into_env()` then conditionally `django.setup()` at cold start; processes SQS records independently; returns `batchItemFailures`
+- `handler.py` — Lambda entry point; cold-start init (`resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`) runs inside the handler on first invocation, guarded by `_cold_start_done` sentinel; processes SQS records independently; returns `batchItemFailures`
 - `environment_loader.py` — loads env vars from a Secrets Manager secret at cold start; validates flat JSON format; idempotent via `_loaded` sentinel
 - `secret_loader.py` — resolves `LAMBDA_TASKS_SECRET_*` env vars from Secrets Manager before Django starts; validates format, detects conflicts, batches API calls; idempotent via `_loaded` sentinel
 - `logging.py` — `task_logger` singleton; `message_id` set/cleared around each task execution

django_lambda_tasks-0.2.1/README.md → django_lambda_tasks-0.2.2/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.4
+Name: django-lambda-tasks
+Version: 0.2.2
+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.
@@ -423,6 +435,8 @@ Point your Lambda function's handler at:
 lambda_tasks.handler.handler
 ```
 
+The handler performs cold-start initialisation on the first invocation (not at module import time) to avoid Lambda init-duration timeouts. The sequence is: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`. A module-level sentinel ensures this runs only once; subsequent warm invocations skip it entirely.
+
 Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and that all task modules are importable (i.e. your application code is on the Python path).
 
 | Environment Variable | Required | Description |
@@ -441,7 +455,7 @@ Set any env var with the prefix `LAMBDA_TASKS_SECRET_` to a full Secrets Manager
 LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
 ```
 
-At cold start, before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
+At cold start (on the first handler invocation), before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
 
 1. Scans all env vars for the `LAMBDA_TASKS_SECRET_` prefix
 2. Validates every reference — malformed references raise immediately so the container fails to start rather than misconfiguring Django silently
@@ -503,7 +517,7 @@ The secret value must be a flat JSON object where all keys and values are string
 }
 ```
 
-At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_environment()` which:
+At cold start (on the first handler invocation), before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_environment()` which:
 
 1. Checks for the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` env var — if not set, does nothing
 2. Parses and validates the reference format (9 segments, non-empty version-stage and version-id)

django_lambda_tasks-0.2.1/PKG-INFO → django_lambda_tasks-0.2.2/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: django-lambda-tasks
-Version: 0.2.1
-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.
@@ -435,6 +423,8 @@ Point your Lambda function's handler at:
 lambda_tasks.handler.handler
 ```
 
+The handler performs cold-start initialisation on the first invocation (not at module import time) to avoid Lambda init-duration timeouts. The sequence is: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()`. A module-level sentinel ensures this runs only once; subsequent warm invocations skip it entirely.
+
 Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and that all task modules are importable (i.e. your application code is on the Python path).
 
 | Environment Variable | Required | Description |
@@ -453,7 +443,7 @@ Set any env var with the prefix `LAMBDA_TASKS_SECRET_` to a full Secrets Manager
 LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
 ```
 
-At cold start, before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
+At cold start (on the first handler invocation), before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
 
 1. Scans all env vars for the `LAMBDA_TASKS_SECRET_` prefix
 2. Validates every reference — malformed references raise immediately so the container fails to start rather than misconfiguring Django silently
@@ -515,7 +505,7 @@ The secret value must be a flat JSON object where all keys and values are string
 }
 ```
 
-At cold start, before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_environment()` which:
+At cold start (on the first handler invocation), before `resolve_secrets_into_env()` and `django.setup()`, the handler calls `resolve_environment()` which:
 
 1. Checks for the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` env var — if not set, does nothing
 2. Parses and validates the reference format (9 segments, non-empty version-stage and version-id)

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/lambda_tasks/environment_loader.py

@@ -13,9 +13,10 @@ Required value format::
 That is: ``<arn>:<version-stage>:<version-id>`` (9 colon-separated segments).
 The ARN is 7 segments, plus version-stage and version-id.
 
-This runs at Lambda cold start — before ``resolve_secrets_into_env()`` and
-before ``django.setup()`` — so that environment variables loaded from the
-secret are available to both the secret loader and Django configuration.
+This is called by the handler on the first invocation (cold start) — before
+``resolve_secrets_into_env()`` and before ``django.setup()`` — so that
+environment variables loaded from the secret are available to both the
+secret loader and Django configuration.
 
 The result is cached at module level via a ``_loaded`` sentinel so that
 subsequent calls (warm invocations) are free no-ops.

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/lambda_tasks/handler.py

@@ -4,28 +4,48 @@ AWS Lambda handler for lambda_tasks.
 Processes a batch of SQS records using partial-batch failure reporting.
 Each record is processed independently — a failure in one record does not
 prevent processing of other records.
+
+Cold-start initialisation (environment loading, secret resolution, Django
+setup) runs inside the handler on the first invocation rather than at module
+import time. This keeps the Lambda init phase fast and avoids init-duration
+timeouts. The sequence is guarded by a module-level sentinel so subsequent
+warm invocations skip it.
 """
 
 import logging
 import os
 
-import django
-from django.apps import apps
-
 from lambda_tasks.environment_loader import resolve_environment
 from lambda_tasks.secret_loader import resolve_secrets_into_env
 
-# Both loaders are idempotent and run unconditionally before the
-# DJANGO_SETTINGS_MODULE check — the environment secret may provide
-# that var, and individual secrets may depend on environment-loaded vars.
-resolve_environment()
-resolve_secrets_into_env()
+logger = logging.getLogger(__name__)
+
+_cold_start_done: bool = False
 
-if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
-    django.setup()
 
+def _perform_cold_start() -> None:
+    """Run one-time initialisation: env loading, secrets, Django setup.
 
-logger = logging.getLogger(__name__)
+    Both loaders are idempotent and run unconditionally — the environment
+    secret may provide DJANGO_SETTINGS_MODULE, and individual secrets may
+    depend on environment-loaded vars.
+    """
+    global _cold_start_done
+
+    if _cold_start_done:
+        return
+
+    resolve_environment()
+    resolve_secrets_into_env()
+
+    if os.environ.get("DJANGO_SETTINGS_MODULE"):
+        import django
+        from django.apps import apps
+
+        if not apps.ready:
+            django.setup()
+
+    _cold_start_done = True
 
 
 def handler(event: dict, context: object) -> dict:
@@ -34,6 +54,8 @@ def handler(event: dict, context: object) -> dict:
     Returns a partial-batch failure report so AWS only re-drives failed records.
     Signature is fixed by AWS and uses two args only.
     """
+    _perform_cold_start()
+
     # Local import due to AppRegistryNotReady
     from lambda_tasks.models import SQSLambdaTaskMessage
 

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/pyproject.toml

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

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/tests/test_environment_loader.py

@@ -551,34 +551,42 @@ class TestPropertyIdempotentExecution:
 
 
 class TestHandlerColdStartOrdering:
-    """Verify handler.py cold-start calls environment loader, then secrets, then conditionally Django."""
+    """Verify handler cold-start runs environment loader, then secrets, then conditionally Django."""
+
+    def _invoke_handler(self) -> None:
+        """Invoke the handler with a minimal valid event to trigger cold-start."""
+        import json
+
+        from lambda_tasks.handler import handler
+
+        body = json.dumps({"task_name": "some.task", "kwargs": {}})
+        event = {"Records": [{"messageId": "msg-1", "body": body}]}
+        handler(event=event, context=None)
 
     def test_resolve_environment_called_before_resolve_secrets_into_env(
         self,
         monkeypatch,
     ) -> None:
         """resolve_environment() runs before resolve_secrets_into_env()."""
-        import sys
+        import lambda_tasks.handler as handler_module
 
         call_order: list[str] = []
 
         monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
 
-        with (
-            patch(
-                "lambda_tasks.environment_loader.resolve_environment",
-                side_effect=lambda: call_order.append("resolve_environment"),
-            ),
-            patch(
-                "lambda_tasks.secret_loader.resolve_secrets_into_env",
-                side_effect=lambda: call_order.append("resolve_secrets_into_env"),
-            ),
-            patch("django.setup"),
-            patch("django.apps.apps.ready", new=False),
-        ):
-            # Remove cached handler module so reload triggers cold-start code
-            sys.modules.pop("lambda_tasks.handler", None)
-            import lambda_tasks.handler  # noqa: F401
+        monkeypatch.setattr(
+            handler_module,
+            "resolve_environment",
+            lambda: call_order.append("resolve_environment"),
+        )
+        monkeypatch.setattr(
+            handler_module,
+            "resolve_secrets_into_env",
+            lambda: call_order.append("resolve_secrets_into_env"),
+        )
+
+        handler_module._cold_start_done = False
+        self._invoke_handler()
 
         assert call_order.index("resolve_environment") < call_order.index(
             "resolve_secrets_into_env"
@@ -592,27 +600,27 @@ class TestHandlerColdStartOrdering:
         monkeypatch,
     ) -> None:
         """Both loaders run even when DJANGO_SETTINGS_MODULE is unset."""
-        import sys
+        import lambda_tasks.handler as handler_module
 
         call_order: list[str] = []
 
-        # Ensure DJANGO_SETTINGS_MODULE is NOT set — loaders must still run
         monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
 
-        with (
-            patch(
-                "lambda_tasks.environment_loader.resolve_environment",
-                side_effect=lambda: call_order.append("resolve_environment"),
-            ),
-            patch(
-                "lambda_tasks.secret_loader.resolve_secrets_into_env",
-                side_effect=lambda: call_order.append("resolve_secrets_into_env"),
-            ),
-            patch("django.setup") as mock_django_setup,
-            patch("django.apps.apps.ready", new=False),
-        ):
-            sys.modules.pop("lambda_tasks.handler", None)
-            import lambda_tasks.handler  # noqa: F401
+        monkeypatch.setattr(
+            handler_module,
+            "resolve_environment",
+            lambda: call_order.append("resolve_environment"),
+        )
+        monkeypatch.setattr(
+            handler_module,
+            "resolve_secrets_into_env",
+            lambda: call_order.append("resolve_secrets_into_env"),
+        )
+
+        handler_module._cold_start_done = False
+
+        with patch("django.setup") as mock_django_setup:
+            self._invoke_handler()
 
         assert (
             "resolve_environment" in call_order
@@ -620,7 +628,6 @@ class TestHandlerColdStartOrdering:
         assert (
             "resolve_secrets_into_env" in call_order
         ), "resolve_secrets_into_env was not called when DJANGO_SETTINGS_MODULE is unset"
-        # django.setup() should NOT have been called since DJANGO_SETTINGS_MODULE is unset
         mock_django_setup.assert_not_called()
 
     def test_django_setup_called_when_settings_module_set_and_apps_not_ready(
@@ -628,22 +635,19 @@ class TestHandlerColdStartOrdering:
         monkeypatch,
     ) -> None:
         """django.setup() called when DJANGO_SETTINGS_MODULE is set and apps.ready is False."""
-        import sys
+        import lambda_tasks.handler as handler_module
 
         monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+        monkeypatch.setattr(handler_module, "resolve_environment", lambda: None)
+        monkeypatch.setattr(handler_module, "resolve_secrets_into_env", lambda: None)
+
+        handler_module._cold_start_done = False
 
         with (
-            patch(
-                "lambda_tasks.environment_loader.resolve_environment",
-            ),
-            patch(
-                "lambda_tasks.secret_loader.resolve_secrets_into_env",
-            ),
             patch("django.setup") as mock_django_setup,
             patch("django.apps.apps.ready", new=False),
         ):
-            sys.modules.pop("lambda_tasks.handler", None)
-            import lambda_tasks.handler  # noqa: F401
+            self._invoke_handler()
 
         mock_django_setup.assert_called_once()
 
@@ -652,22 +656,19 @@ class TestHandlerColdStartOrdering:
         monkeypatch,
     ) -> None:
         """django.setup() is NOT called when apps.ready is True."""
-        import sys
+        import lambda_tasks.handler as handler_module
 
         monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+        monkeypatch.setattr(handler_module, "resolve_environment", lambda: None)
+        monkeypatch.setattr(handler_module, "resolve_secrets_into_env", lambda: None)
+
+        handler_module._cold_start_done = False
 
         with (
-            patch(
-                "lambda_tasks.environment_loader.resolve_environment",
-            ),
-            patch(
-                "lambda_tasks.secret_loader.resolve_secrets_into_env",
-            ),
             patch("django.setup") as mock_django_setup,
             patch("django.apps.apps.ready", new=True),
         ):
-            sys.modules.pop("lambda_tasks.handler", None)
-            import lambda_tasks.handler  # noqa: F401
+            self._invoke_handler()
 
         mock_django_setup.assert_not_called()
 
@@ -676,21 +677,15 @@ class TestHandlerColdStartOrdering:
         monkeypatch,
     ) -> None:
         """django.setup() is NOT called when DJANGO_SETTINGS_MODULE is unset."""
-        import sys
+        import lambda_tasks.handler as handler_module
 
         monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
+        monkeypatch.setattr(handler_module, "resolve_environment", lambda: None)
+        monkeypatch.setattr(handler_module, "resolve_secrets_into_env", lambda: None)
 
-        with (
-            patch(
-                "lambda_tasks.environment_loader.resolve_environment",
-            ),
-            patch(
-                "lambda_tasks.secret_loader.resolve_secrets_into_env",
-            ),
-            patch("django.setup") as mock_django_setup,
-            patch("django.apps.apps.ready", new=False),
-        ):
-            sys.modules.pop("lambda_tasks.handler", None)
-            import lambda_tasks.handler  # noqa: F401
+        handler_module._cold_start_done = False
+
+        with patch("django.setup") as mock_django_setup:
+            self._invoke_handler()
 
         mock_django_setup.assert_not_called()

{django_lambda_tasks-0.2.1 → django_lambda_tasks-0.2.2}/tests/test_handler.py

@@ -271,33 +271,44 @@ def test_property_11_batch_records_processed_independently(flags):
 
 
 def test_property_4_django_setup_before_execute_task(monkeypatch):
+    """Cold-start init (resolve_environment, resolve_secrets, django.setup) runs
+    inside the handler on first invocation, not at module import time."""
     import importlib
 
     import django.apps
 
     import lambda_tasks.handler as handler_module
 
-    call_order = []
+    call_order: list[str] = []
 
     monkeypatch.setattr(django.apps.apps, "ready", False)
     monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
 
+    def spy_resolve_environment():
+        call_order.append("resolve_environment")
+
+    def spy_resolve_secrets():
+        call_order.append("resolve_secrets_into_env")
+
     def spy_setup(*args, **kwargs):
         call_order.append("django.setup")
 
-    monkeypatch.setattr(django, "setup", spy_setup)
-
     def spy_model_validate(body):
         call_order.append("execute_task")
         return MagicMock()
 
+    monkeypatch.setattr(
+        "lambda_tasks.handler.resolve_environment", spy_resolve_environment
+    )
+    monkeypatch.setattr(
+        "lambda_tasks.handler.resolve_secrets_into_env", spy_resolve_secrets
+    )
+    monkeypatch.setattr(django, "setup", spy_setup)
     monkeypatch.setattr(
         "lambda_tasks.models.SQSLambdaTaskMessage.model_validate_json",
         spy_model_validate,
     )
 
-    importlib.reload(handler_module)
-
     body = json.dumps(
         {
             "task_name": "some.task",
@@ -305,17 +316,54 @@ def test_property_4_django_setup_before_execute_task(monkeypatch):
         }
     )
     event = {"Records": [{"messageId": "msg-1", "body": body}]}
+
+    # Reset the handler's cold-start guard so it runs init again
+    handler_module._cold_start_done = False
     handler_module.handler(event=event, context=None)
 
-    assert (
-        "django.setup" in call_order
-    ), f"django.setup was never called; call_order={call_order}"
-    setup_idx = call_order.index("django.setup")
-    execute_idx = (
-        call_order.index("execute_task")
-        if "execute_task" in call_order
-        else len(call_order)
+    assert call_order == [
+        "resolve_environment",
+        "resolve_secrets_into_env",
+        "django.setup",
+        "execute_task",
+    ], f"Unexpected call order: {call_order}"
+
+
+def test_property_4_cold_start_runs_only_once(monkeypatch):
+    """The cold-start init sequence runs only on the first invocation."""
+    import django.apps
+
+    import lambda_tasks.handler as handler_module
+
+    call_count = {"setup": 0}
+
+    monkeypatch.setattr(django.apps.apps, "ready", False)
+    monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+
+    def spy_resolve_environment():
+        pass
+
+    def spy_resolve_secrets():
+        pass
+
+    def spy_setup(*args, **kwargs):
+        call_count["setup"] += 1
+
+    monkeypatch.setattr(
+        "lambda_tasks.handler.resolve_environment", spy_resolve_environment
     )
-    assert (
-        setup_idx < execute_idx
-    ), f"Expected django.setup before execute_task, got order: {call_order}"
+    monkeypatch.setattr(
+        "lambda_tasks.handler.resolve_secrets_into_env", spy_resolve_secrets
+    )
+    monkeypatch.setattr(django, "setup", spy_setup)
+
+    with _patch_model_validate(side_effect=lambda body: MagicMock()):
+        handler_module._cold_start_done = False
+        handler_module.handler(
+            event={"Records": [_make_record("m1", _valid_body())]}, context=None
+        )
+        handler_module.handler(
+            event={"Records": [_make_record("m2", _valid_body())]}, context=None
+        )
+
+    assert call_count["setup"] == 1