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

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

@@ -62,7 +62,7 @@ def sync_user(*, user_id: int) -> None:
 
 ## retry_on
 
-Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task raises an instance of any of those types (or a subclass), the executor automatically re-enqueues the task via `execute_on_commit` with the same kwargs, and an incremented `_n_retries` counter.
+Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task raises an instance of any of those types (or a subclass), the executor automatically re-enqueues the task with the same kwargs and an incremented `n_retries` counter on the `SQSLambdaTaskMessage`.
 
 - `TaskRecord.status` is set to `RETRYING` and the traceback is recorded
 - The retry is a new invocation — the current record is terminal at `RETRYING`
@@ -125,7 +125,7 @@ class SQSLambdaTaskMessage(BaseModel):
 7. On ignored exception (type matches `ignore_errors`): rolls back task-side writes, commits record as `SUCCESS` with traceback and `end_time`
 8. On retryable exception (type matches `retry_on` or `LockError` for singleton tasks, `n_retries < MAX_RETRIES`): rolls back task-side writes, enqueues retry via `execute_on_commit` with `n_retries + 1`, commits record as `RETRYING` with traceback and `end_time`
 9. On retryable exception with `n_retries >= MAX_RETRIES`: commits record as `FAILED` with traceback, raises `MaxRetriesExceededError`
-10. On any other exception: rolls back atomic block, updates record to `FAILED` with traceback
+10. On any other exception: rolls back atomic block, updates record to `FAILED` with traceback and `end_time`
 
 ## Lambda Handler
 
@@ -135,9 +135,10 @@ 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 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()`
+- Cold-start sequence runs inside the handler on the first invocation (not at module import time) to avoid Lambda init-duration timeouts: a temporary `StreamHandler` is attached to the `lambda_tasks` logger, then `resolve_environment()` → `resolve_secrets_into_env()` (handler removed) → 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
+- A temporary `StreamHandler` is attached to the `lambda_tasks` logger for the duration of the loaders so their log output is visible before Django's `LOGGING` dictConfig has run; it is removed immediately after so that Django's configuration is the sole authority on logging from that point on
 
 ## Environment Loader
 
@@ -205,7 +206,7 @@ Set `LAMBDA_TASKS_EAGER = True` to run tasks synchronously in-process (no SQS).
 
 In eager mode a random UUID4 is generated as the `message_id` passed to `execute_immediately()`.
 
-**Timeouts are not enforced in eager mode.** `TimeoutContext` is skipped entirely — `SIGALRM`-based timeouts require a Lambda worker process, not a Django dev server thread. Timeout values are still validated at decoration time.
+**Timeouts are not enforced in eager mode.** `TimeoutContext` is still entered but becomes a no-op — it checks `LAMBDA_TASKS_EAGER` internally and skips `SIGALRM` setup. `SIGALRM`-based timeouts require a Lambda worker process, not a Django dev server thread. Timeout values are still validated at decoration time.
 
 ## Logging
 

{django_lambda_tasks-0.2.2 → django_lambda_tasks-0.2.4}/.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; 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`
+- `handler.py` — Lambda entry point; cold-start init (temporary log handler → `resolve_environment()` → `resolve_secrets_into_env()` → handler removed → 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.2 → django_lambda_tasks-0.2.4}/.kiro/steering/tech.md

@@ -42,7 +42,7 @@ uv run pytest tests/test_foo.py  # single file
 uv run pytest -x                 # stop on first failure
 ```
 
-- Tests live in `tests/` — one file per source module (`executor.py` → `test_executor.py`)
+- Tests live in `tests/` — one file per source module (`models.py` → `test_models.py`)
 - Django settings for tests are in `tests/settings.py`
 - Use `hypothesis` for property-based tests where correctness properties can be expressed
 

{django_lambda_tasks-0.2.2 → django_lambda_tasks-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-lambda-tasks
-Version: 0.2.2
+Version: 0.2.4
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.10
 Requires-Dist: awslambdaric
@@ -127,13 +127,32 @@ LAMBDA_TASKS_DEFAULT_SOFT_TIMEOUT = 240
 LAMBDA_TASKS_DEFAULT_HARD_TIMEOUT = 270
 ```
 
+### Retry settings
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `LAMBDA_TASKS_MAX_RETRIES` | `int` | `2880` | Maximum retry attempts before `MaxRetriesExceededError` is raised (default is 60 × 24 × 2). |
+
+### Singleton settings
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `LAMBDA_TASKS_SINGLETON_CACHE` | `str` | `"default"` | Django cache backend used for singleton task locks. |
+
+### Environment and secrets
+
+| Setting | Type | Description |
+|---|---|---|
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | env var | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at Lambda cold start. |
+| `LAMBDA_TASKS_SECRET_*` | env var(s) | Secrets Manager references resolved into env vars at Lambda cold start. The unprefixed name becomes the target env var. |
+
+These are environment variables set on the Lambda function, not Django settings. See [Loading environment variables from Secrets Manager](#loading-environment-variables-from-secrets-manager) and [Resolving individual secrets from AWS Secrets Manager](#resolving-individual-secrets-from-aws-secrets-manager) for full details.
+
 ### Eager execution (development / testing)
 
 | Setting | Type | Default | Description |
 |---|---|---|---|
 | `LAMBDA_TASKS_EAGER` | `bool` | `False` | When `True`, tasks run synchronously in-process instead of being sent to SQS. |
-| `LAMBDA_TASKS_MAX_RETRIES` | `int` | `2880` | Maximum retry attempts before `MaxRetriesExceededError` is raised. |
-| `LAMBDA_TASKS_SINGLETON_CACHE` | `str` | `"default"` | Django cache backend used for singleton task locks. |
 
 ```python
 # settings/local.py
@@ -142,7 +161,7 @@ LAMBDA_TASKS_EAGER = True
 
 With eager mode enabled, `.execute_on_commit()` executes the task immediately without touching SQS. Useful for local development and test suites where you don't want to mock AWS infrastructure.
 
-> **Note:** Timeouts are not enforced in eager mode. `soft_timeout` and `hard_timeout` values are accepted and stored but `TimeoutContext` is never entered — the task runs without any time limit. This is intentional: `SIGALRM`-based timeouts require a Lambda/Unix worker process, not a Django dev server thread.
+> **Note:** Timeouts are not enforced in eager mode. `soft_timeout` and `hard_timeout` values are accepted and stored but `TimeoutContext` becomes a no-op — it checks `LAMBDA_TASKS_EAGER` internally and skips `SIGALRM` setup. This is intentional: `SIGALRM`-based timeouts require a Lambda/Unix worker process, not a Django dev server thread.
 
 ---
 
@@ -150,6 +169,7 @@ With eager mode enabled, `.execute_on_commit()` executes the task immediately wi
 
 ```python
 @lambda_task(
+    delay=0,               # seconds — SQS DelaySeconds before message becomes visible
     soft_timeout=60,       # seconds — overrides global default for this task
     hard_timeout=90,       # seconds — overrides global default for this task
     queue="default",       # named queue from LAMBDA_TASKS_QUEUES
@@ -164,6 +184,7 @@ def my_task(*, arg: str) -> None:
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
+| `delay` | `int` | `0` | Seconds to delay the SQS message before it becomes visible to consumers (max 900). |
 | `soft_timeout` | `int \| None` | `None` (uses global default) | Per-task soft timeout in seconds (max 900). |
 | `hard_timeout` | `int \| None` | `None` (uses global default) | Per-task hard timeout in seconds (max 900). |
 | `queue` | `str` | `"default"` | Named queue to route this task to. |
@@ -190,7 +211,7 @@ payload = send_welcome_email.serialize(user_id=42, template="welcome")
 # }
 ```
 
-The returned dict matches the `SQSLambdaTask` schema. To reconstruct and enqueue it later:
+The returned dict matches the `SQSLambdaTask` schema (`message`, `delay`, `queue`). The `delay` value comes from the decorator's `delay` parameter. To reconstruct and enqueue it later:
 
 ```python
 from lambda_tasks.models import SQSLambdaTask
@@ -270,8 +291,10 @@ TaskRecord.objects.get(pk="<uuid>")
 
 | Field | Type | Description |
 |---|---|---|
+| `id` | `UUID` | Primary key — set to the SQS `messageId` for deduplication. |
 | `task_name` | `str` | Fully-qualified function name (e.g. `myapp.tasks.send_welcome_email`). |
 | `kwargs` | `dict` | Serialized task arguments. |
+| `n_retries` | `int` | Number of retries attempted so far (starts at 0). |
 | `status` | `str` | One of `RUNNING`, `SUCCESS`, `FAILED`, `RETRYING`. |
 | `start_time` | `datetime \| None` | When the worker began executing the task. |
 | `end_time` | `datetime \| None` | When the task completed or failed. |
@@ -297,6 +320,8 @@ def send_welcome_email(*, user_id: int, template: str) -> str:
 
 `task_logger` is a `LoggerAdapter` wrapping the `lambda_tasks.task` logger. `SQSLambdaTaskMessage.execute_immediately()` sets the `message_id` before each task runs and clears it afterwards — you don't need to manage it yourself.
 
+The Lambda handler configures the `lambda_tasks` logger hierarchy to `INFO` at cold start so that `task_logger` lines appear in CloudWatch. You can control the level by configuring the `lambda_tasks` logger in your Django `LOGGING` setting (e.g. set it to `DEBUG` or `WARNING`). If your `LOGGING` dictConfig sets a root logger with a handler (as most Django projects do), `lambda_tasks` will inherit from it via propagation.
+
 Using your own `logging.getLogger(__name__)` is fine too; those records just won't carry the `message_id` prefix.
 
 To filter by invocation in CloudWatch Logs Insights:
@@ -435,19 +460,63 @@ 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.
+The handler performs cold-start initialisation on the first invocation (not at module import time) to avoid Lambda init-duration timeouts. The sequence is: temporary log handler attached → `resolve_environment()` → `resolve_secrets_into_env()` → log handler removed → 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 |
 |---|---|---|
 | `DJANGO_SETTINGS_MODULE` | Yes | Django settings module path (e.g. `myapp.settings.production`). |
-| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at cold start. |
-| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into env vars at cold start (see below). |
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at cold start (runs first). |
+| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into individual env vars at cold start (runs second, after environment loading). |
+
+### Loading environment variables from Secrets Manager
+
+The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
+
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
+
+```
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
+```
+
+The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
+
+The secret value must be a flat JSON object where all keys and values are strings:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@host:5432/db",
+  "REDIS_URL": "redis://host:6379/0",
+  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
+}
+```
+
+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)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
+5. Sets each key-value pair in `os.environ` — existing env vars are overridden
+6. Caches the result via a module-level sentinel — subsequent calls are free no-ops
+
+Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
+
+#### Validation errors
+
+The following raise `ValueError` at cold start, preventing the Lambda container from starting:
 
-### Resolving Django settings from AWS Secrets Manager
+- Reference format is invalid (wrong segment count, empty version-stage or version-id)
+- Secret value is not valid JSON
+- JSON is not a flat object (contains non-string values) — error message lists the offending keys
+- JSON contains an empty string key
+
+AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
 
-The Lambda handler supports loading secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
+### Resolving individual secrets from AWS Secrets Manager
+
+The Lambda handler supports loading individual secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
 
 Set any env var with the prefix `LAMBDA_TASKS_SECRET_` to a full Secrets Manager dynamic reference. The unprefixed name becomes the target env var:
 
@@ -455,7 +524,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 (on the first handler invocation), before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
+At cold start (on the first handler invocation), after `resolve_environment()` and before `django.setup()`, 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
@@ -495,50 +564,6 @@ The following all raise `ValueError` at cold start, preventing the Lambda contai
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON
 
-### Loading environment variables from Secrets Manager
-
-The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
-
-Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
-
-```
-LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
-```
-
-The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
-
-The secret value must be a flat JSON object where all keys and values are strings:
-
-```json
-{
-  "DATABASE_URL": "postgres://user:pass@host:5432/db",
-  "REDIS_URL": "redis://host:6379/0",
-  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
-}
-```
-
-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)
-3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
-4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
-5. Sets each key-value pair in `os.environ` — existing env vars are overridden
-6. Caches the result via a module-level sentinel — subsequent calls are free no-ops
-
-Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
-
-#### Validation errors
-
-The following raise `ValueError` at cold start, preventing the Lambda container from starting:
-
-- Reference format is invalid (wrong segment count, empty version-stage or version-id)
-- Secret value is not valid JSON
-- JSON is not a flat object (contains non-string values) — error message lists the offending keys
-- JSON contains an empty string key
-
-AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
-
 ---
 
 ## Built-in tasks
@@ -571,4 +596,4 @@ You can call a decorated task directly like a normal function — useful in test
 result = send_welcome_email(user_id=1, template="welcome")
 ```
 
-This bypasses the queue entirely and runs the function in the current process and transaction.
+This bypasses the queue entirely and runs the function in the current process. No `TaskRecord` is created, no `transaction.atomic()` block is used, and no timeout enforcement applies — it behaves exactly like calling the underlying function directly. Kwargs are still validated against the task's type annotations via Pydantic.

{django_lambda_tasks-0.2.2 → django_lambda_tasks-0.2.4}/README.md

@@ -115,13 +115,32 @@ LAMBDA_TASKS_DEFAULT_SOFT_TIMEOUT = 240
 LAMBDA_TASKS_DEFAULT_HARD_TIMEOUT = 270
 ```
 
+### Retry settings
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `LAMBDA_TASKS_MAX_RETRIES` | `int` | `2880` | Maximum retry attempts before `MaxRetriesExceededError` is raised (default is 60 × 24 × 2). |
+
+### Singleton settings
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `LAMBDA_TASKS_SINGLETON_CACHE` | `str` | `"default"` | Django cache backend used for singleton task locks. |
+
+### Environment and secrets
+
+| Setting | Type | Description |
+|---|---|---|
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | env var | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at Lambda cold start. |
+| `LAMBDA_TASKS_SECRET_*` | env var(s) | Secrets Manager references resolved into env vars at Lambda cold start. The unprefixed name becomes the target env var. |
+
+These are environment variables set on the Lambda function, not Django settings. See [Loading environment variables from Secrets Manager](#loading-environment-variables-from-secrets-manager) and [Resolving individual secrets from AWS Secrets Manager](#resolving-individual-secrets-from-aws-secrets-manager) for full details.
+
 ### Eager execution (development / testing)
 
 | Setting | Type | Default | Description |
 |---|---|---|---|
 | `LAMBDA_TASKS_EAGER` | `bool` | `False` | When `True`, tasks run synchronously in-process instead of being sent to SQS. |
-| `LAMBDA_TASKS_MAX_RETRIES` | `int` | `2880` | Maximum retry attempts before `MaxRetriesExceededError` is raised. |
-| `LAMBDA_TASKS_SINGLETON_CACHE` | `str` | `"default"` | Django cache backend used for singleton task locks. |
 
 ```python
 # settings/local.py
@@ -130,7 +149,7 @@ LAMBDA_TASKS_EAGER = True
 
 With eager mode enabled, `.execute_on_commit()` executes the task immediately without touching SQS. Useful for local development and test suites where you don't want to mock AWS infrastructure.
 
-> **Note:** Timeouts are not enforced in eager mode. `soft_timeout` and `hard_timeout` values are accepted and stored but `TimeoutContext` is never entered — the task runs without any time limit. This is intentional: `SIGALRM`-based timeouts require a Lambda/Unix worker process, not a Django dev server thread.
+> **Note:** Timeouts are not enforced in eager mode. `soft_timeout` and `hard_timeout` values are accepted and stored but `TimeoutContext` becomes a no-op — it checks `LAMBDA_TASKS_EAGER` internally and skips `SIGALRM` setup. This is intentional: `SIGALRM`-based timeouts require a Lambda/Unix worker process, not a Django dev server thread.
 
 ---
 
@@ -138,6 +157,7 @@ With eager mode enabled, `.execute_on_commit()` executes the task immediately wi
 
 ```python
 @lambda_task(
+    delay=0,               # seconds — SQS DelaySeconds before message becomes visible
     soft_timeout=60,       # seconds — overrides global default for this task
     hard_timeout=90,       # seconds — overrides global default for this task
     queue="default",       # named queue from LAMBDA_TASKS_QUEUES
@@ -152,6 +172,7 @@ def my_task(*, arg: str) -> None:
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
+| `delay` | `int` | `0` | Seconds to delay the SQS message before it becomes visible to consumers (max 900). |
 | `soft_timeout` | `int \| None` | `None` (uses global default) | Per-task soft timeout in seconds (max 900). |
 | `hard_timeout` | `int \| None` | `None` (uses global default) | Per-task hard timeout in seconds (max 900). |
 | `queue` | `str` | `"default"` | Named queue to route this task to. |
@@ -178,7 +199,7 @@ payload = send_welcome_email.serialize(user_id=42, template="welcome")
 # }
 ```
 
-The returned dict matches the `SQSLambdaTask` schema. To reconstruct and enqueue it later:
+The returned dict matches the `SQSLambdaTask` schema (`message`, `delay`, `queue`). The `delay` value comes from the decorator's `delay` parameter. To reconstruct and enqueue it later:
 
 ```python
 from lambda_tasks.models import SQSLambdaTask
@@ -258,8 +279,10 @@ TaskRecord.objects.get(pk="<uuid>")
 
 | Field | Type | Description |
 |---|---|---|
+| `id` | `UUID` | Primary key — set to the SQS `messageId` for deduplication. |
 | `task_name` | `str` | Fully-qualified function name (e.g. `myapp.tasks.send_welcome_email`). |
 | `kwargs` | `dict` | Serialized task arguments. |
+| `n_retries` | `int` | Number of retries attempted so far (starts at 0). |
 | `status` | `str` | One of `RUNNING`, `SUCCESS`, `FAILED`, `RETRYING`. |
 | `start_time` | `datetime \| None` | When the worker began executing the task. |
 | `end_time` | `datetime \| None` | When the task completed or failed. |
@@ -285,6 +308,8 @@ def send_welcome_email(*, user_id: int, template: str) -> str:
 
 `task_logger` is a `LoggerAdapter` wrapping the `lambda_tasks.task` logger. `SQSLambdaTaskMessage.execute_immediately()` sets the `message_id` before each task runs and clears it afterwards — you don't need to manage it yourself.
 
+The Lambda handler configures the `lambda_tasks` logger hierarchy to `INFO` at cold start so that `task_logger` lines appear in CloudWatch. You can control the level by configuring the `lambda_tasks` logger in your Django `LOGGING` setting (e.g. set it to `DEBUG` or `WARNING`). If your `LOGGING` dictConfig sets a root logger with a handler (as most Django projects do), `lambda_tasks` will inherit from it via propagation.
+
 Using your own `logging.getLogger(__name__)` is fine too; those records just won't carry the `message_id` prefix.
 
 To filter by invocation in CloudWatch Logs Insights:
@@ -423,19 +448,63 @@ 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.
+The handler performs cold-start initialisation on the first invocation (not at module import time) to avoid Lambda init-duration timeouts. The sequence is: temporary log handler attached → `resolve_environment()` → `resolve_secrets_into_env()` → log handler removed → 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 |
 |---|---|---|
 | `DJANGO_SETTINGS_MODULE` | Yes | Django settings module path (e.g. `myapp.settings.production`). |
-| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at cold start. |
-| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into env vars at cold start (see below). |
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<version-stage>:<version-id>`) to load as environment variables at cold start (runs first). |
+| `LAMBDA_TASKS_SECRET_*` | No | Secrets Manager references resolved into individual env vars at cold start (runs second, after environment loading). |
+
+### Loading environment variables from Secrets Manager
+
+The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
+
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
+
+```
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
+```
+
+The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
+
+The secret value must be a flat JSON object where all keys and values are strings:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@host:5432/db",
+  "REDIS_URL": "redis://host:6379/0",
+  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
+}
+```
+
+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)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
+5. Sets each key-value pair in `os.environ` — existing env vars are overridden
+6. Caches the result via a module-level sentinel — subsequent calls are free no-ops
+
+Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
+
+#### Validation errors
+
+The following raise `ValueError` at cold start, preventing the Lambda container from starting:
 
-### Resolving Django settings from AWS Secrets Manager
+- Reference format is invalid (wrong segment count, empty version-stage or version-id)
+- Secret value is not valid JSON
+- JSON is not a flat object (contains non-string values) — error message lists the offending keys
+- JSON contains an empty string key
+
+AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
 
-The Lambda handler supports loading secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
+### Resolving individual secrets from AWS Secrets Manager
+
+The Lambda handler supports loading individual secret values from AWS Secrets Manager into the environment before Django starts. This lets your Django settings file read from `os.environ` as normal while keeping secrets out of plaintext environment variables.
 
 Set any env var with the prefix `LAMBDA_TASKS_SECRET_` to a full Secrets Manager dynamic reference. The unprefixed name becomes the target env var:
 
@@ -443,7 +512,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 (on the first handler invocation), before `django.setup()` is called, the handler calls `resolve_secrets_into_env()` which:
+At cold start (on the first handler invocation), after `resolve_environment()` and before `django.setup()`, 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
@@ -483,50 +552,6 @@ The following all raise `ValueError` at cold start, preventing the Lambda contai
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON
 
-### Loading environment variables from Secrets Manager
-
-The Lambda handler supports loading environment variables from an AWS Secrets Manager secret at cold start. This lets you manage environment configuration centrally in Secrets Manager without baking values into the Lambda deployment package.
-
-Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version stage and version ID:
-
-```
-LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
-```
-
-The format is `<arn>:<version-stage>:<version-id>` (9 colon-separated segments — the ARN is 7 segments, plus version-stage and version-id). Both suffix fields must be non-empty.
-
-The secret value must be a flat JSON object where all keys and values are strings:
-
-```json
-{
-  "DATABASE_URL": "postgres://user:pass@host:5432/db",
-  "REDIS_URL": "redis://host:6379/0",
-  "DJANGO_SETTINGS_MODULE": "myapp.settings.production"
-}
-```
-
-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)
-3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
-4. Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
-5. Sets each key-value pair in `os.environ` — existing env vars are overridden
-6. Caches the result via a module-level sentinel — subsequent calls are free no-ops
-
-Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_MODULE` itself, and individual secrets loaded by `resolve_secrets_into_env()` can reference environment-loaded values.
-
-#### Validation errors
-
-The following raise `ValueError` at cold start, preventing the Lambda container from starting:
-
-- Reference format is invalid (wrong segment count, empty version-stage or version-id)
-- Secret value is not valid JSON
-- JSON is not a flat object (contains non-string values) — error message lists the offending keys
-- JSON contains an empty string key
-
-AWS errors (secret not found, permission denied) propagate as boto3 exceptions and crash the container at cold start.
-
 ---
 
 ## Built-in tasks
@@ -559,4 +584,4 @@ You can call a decorated task directly like a normal function — useful in test
 result = send_welcome_email(user_id=1, template="welcome")
 ```
 
-This bypasses the queue entirely and runs the function in the current process and transaction.
+This bypasses the queue entirely and runs the function in the current process. No `TaskRecord` is created, no `transaction.atomic()` block is used, and no timeout enforcement applies — it behaves exactly like calling the underlying function directly. Kwargs are still validated against the task's type annotations via Pydantic.

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

@@ -15,6 +15,9 @@ 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
 
@@ -29,21 +32,32 @@ def _perform_cold_start() -> None:
     Both loaders are idempotent and run unconditionally — the environment
     secret may provide DJANGO_SETTINGS_MODULE, and individual secrets may
     depend on environment-loaded vars.
+
+    A temporary StreamHandler is attached to the ``lambda_tasks`` logger for
+    the duration of the loaders so their log output is visible before Django's
+    LOGGING dictConfig has run. It is removed immediately after so that
+    Django's configuration is the sole authority on logging from that point on.
     """
     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()
+    lambda_tasks_logger = logging.getLogger(__package__)
+    boot_handler = logging.StreamHandler()
+    boot_handler.setLevel(logging.DEBUG)
+    lambda_tasks_logger.addHandler(boot_handler)
+    lambda_tasks_logger.setLevel(logging.DEBUG)
+
+    try:
+        resolve_environment()
+        resolve_secrets_into_env()
+    finally:
+        lambda_tasks_logger.removeHandler(boot_handler)
+        lambda_tasks_logger.setLevel(logging.NOTSET)
+
+    if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
+        django.setup()
 
     _cold_start_done = True
 

{django_lambda_tasks-0.2.2 → django_lambda_tasks-0.2.4}/lambda_tasks/logging.py

@@ -21,7 +21,7 @@ class _TaskLogger(logging.LoggerAdapter):
     """LoggerAdapter that prepends [message_id] to every message."""
 
     def __init__(self) -> None:
-        super().__init__(logging.getLogger("lambda_tasks.task"), extra={})
+        super().__init__(logging.getLogger(f"{__package__}.task"), extra={})
         self.message_id: str | None = None
 
     def process(

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

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

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

@@ -16,6 +16,7 @@ Validates: Requirements 4.2, 4.3, 4.5
 
 import inspect
 import json
+import logging
 import uuid
 from unittest.mock import MagicMock, patch
 
@@ -367,3 +368,92 @@ def test_property_4_cold_start_runs_only_once(monkeypatch):
         )
 
     assert call_count["setup"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Cold-start logging tests
+# ---------------------------------------------------------------------------
+
+
+class TestColdStartLogging:
+    def test_loader_logs_are_emitted_during_cold_start(self, monkeypatch, capfd):
+        """Loader log output is visible during cold start before Django setup."""
+        import lambda_tasks.handler as handler_module
+
+        monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
+
+        logged_messages: list[str] = []
+
+        def spy_resolve_environment():
+            logging.getLogger("lambda_tasks.environment_loader").info(
+                "env loader message"
+            )
+
+        def spy_resolve_secrets():
+            logging.getLogger("lambda_tasks.secret_loader").info(
+                "secret loader message"
+            )
+
+        monkeypatch.setattr(
+            "lambda_tasks.handler.resolve_environment", spy_resolve_environment
+        )
+        monkeypatch.setattr(
+            "lambda_tasks.handler.resolve_secrets_into_env", spy_resolve_secrets
+        )
+
+        lambda_tasks_logger = logging.getLogger("lambda_tasks")
+        lambda_tasks_logger.handlers.clear()
+        lambda_tasks_logger.setLevel(logging.NOTSET)
+
+        handler_module._cold_start_done = False
+        handler_module.handler(event={"Records": []}, context=None)
+
+        captured = capfd.readouterr()
+        assert "env loader message" in captured.err
+        assert "secret loader message" in captured.err
+
+    def test_boot_handler_removed_after_loaders(self, monkeypatch):
+        """The temporary handler is removed after the loaders run, leaving
+        the logger clean for Django's LOGGING dictConfig."""
+        import lambda_tasks.handler as handler_module
+
+        monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
+        monkeypatch.setattr("lambda_tasks.handler.resolve_environment", lambda: None)
+        monkeypatch.setattr(
+            "lambda_tasks.handler.resolve_secrets_into_env", lambda: None
+        )
+
+        lambda_tasks_logger = logging.getLogger("lambda_tasks")
+        lambda_tasks_logger.handlers.clear()
+        lambda_tasks_logger.setLevel(logging.NOTSET)
+
+        handler_module._cold_start_done = False
+        handler_module.handler(event={"Records": []}, context=None)
+
+        assert lambda_tasks_logger.handlers == []
+        assert lambda_tasks_logger.level == logging.NOTSET
+
+    def test_boot_handler_removed_even_on_loader_error(self, monkeypatch):
+        """The temporary handler is cleaned up even if a loader raises."""
+        import lambda_tasks.handler as handler_module
+
+        monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
+        monkeypatch.setattr(
+            "lambda_tasks.handler.resolve_environment",
+            lambda: (_ for _ in ()).throw(ValueError("bad ref")),
+        )
+        monkeypatch.setattr(
+            "lambda_tasks.handler.resolve_secrets_into_env", lambda: None
+        )
+
+        lambda_tasks_logger = logging.getLogger("lambda_tasks")
+        lambda_tasks_logger.handlers.clear()
+        lambda_tasks_logger.setLevel(logging.NOTSET)
+
+        handler_module._cold_start_done = False
+
+        with pytest.raises(ValueError, match="bad ref"):
+            handler_module.handler(event={"Records": []}, context=None)
+
+        assert lambda_tasks_logger.handlers == []
+        assert lambda_tasks_logger.level == logging.NOTSET