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

{django_lambda_tasks-0.2.2 → django_lambda_tasks-0.2.3}/.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: `resolve_environment()` → `resolve_secrets_into_env()` → conditional `django.setup()` → `_configure_logging()`
 - 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
+- `_configure_logging()` sets the `lambda_tasks` logger hierarchy to `INFO` (or the level specified by `LAMBDA_TASKS_LOG_LEVEL` env var) so that `task_logger` output appears in CloudWatch
 
 ## 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.3}/.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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-lambda-tasks
-Version: 0.2.2
+Version: 0.2.3
 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 override the level by setting the `LAMBDA_TASKS_LOG_LEVEL` environment variable on your Lambda function (e.g. `DEBUG`, `WARNING`).
+
 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:
@@ -442,12 +467,57 @@ Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and tha
 | 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_LOG_LEVEL` | No | Log level for the `lambda_tasks` logger hierarchy (default `INFO`). Set to `DEBUG`, `WARNING`, etc. as needed. |
+| `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 +525,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 +565,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 +597,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.3}/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 override the level by setting the `LAMBDA_TASKS_LOG_LEVEL` environment variable on your Lambda function (e.g. `DEBUG`, `WARNING`).
+
 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:
@@ -430,12 +455,57 @@ Ensure the Lambda execution environment has `DJANGO_SETTINGS_MODULE` set and tha
 | 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_LOG_LEVEL` | No | Log level for the `lambda_tasks` logger hierarchy (default `INFO`). Set to `DEBUG`, `WARNING`, etc. as needed. |
+| `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 +513,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 +553,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 +585,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.3}/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
 
@@ -38,16 +41,36 @@ def _perform_cold_start() -> None:
     resolve_environment()
     resolve_secrets_into_env()
 
-    if os.environ.get("DJANGO_SETTINGS_MODULE"):
-        import django
-        from django.apps import apps
+    if os.environ.get("DJANGO_SETTINGS_MODULE") and not apps.ready:
+        django.setup()
 
-        if not apps.ready:
-            django.setup()
+    _configure_logging()
 
     _cold_start_done = True
 
 
+def _configure_logging() -> None:
+    """Ensure the lambda_tasks logger hierarchy emits at INFO so task log lines
+    appear in CloudWatch.
+
+    The AWS Lambda runtime pre-configures the root logger, but child loggers
+    default to WARNING unless explicitly configured. If Django's LOGGING
+    dictConfig has already set a level on the ``lambda_tasks`` logger (i.e. the
+    user explicitly configured it), we leave it alone. Otherwise we default to
+    INFO (or the value of the LAMBDA_TASKS_LOG_LEVEL env var).
+    """
+    lambda_tasks_logger = logging.getLogger("lambda_tasks")
+
+    # level == NOTSET means nobody (neither dictConfig nor user code) has
+    # explicitly configured this logger — safe to apply our default.
+    if lambda_tasks_logger.level != logging.NOTSET:
+        return
+
+    log_level_name = os.environ.get("LAMBDA_TASKS_LOG_LEVEL", "INFO").upper()
+    log_level = getattr(logging, log_level_name, logging.INFO)
+    lambda_tasks_logger.setLevel(log_level)
+
+
 def handler(event: dict, context: object) -> dict:
     """AWS Lambda entry point. Processes a batch of SQS records.
 

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

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.2.2"
+version = "0.2.3"
 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.3}/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
 
@@ -23,7 +24,7 @@ import pytest
 from hypothesis import given, settings
 from hypothesis import strategies as st
 
-from lambda_tasks.handler import handler
+from lambda_tasks.handler import _configure_logging, handler
 
 # ---------------------------------------------------------------------------
 # Signature test
@@ -367,3 +368,48 @@ def test_property_4_cold_start_runs_only_once(monkeypatch):
         )
 
     assert call_count["setup"] == 1
+
+
+# ---------------------------------------------------------------------------
+# _configure_logging tests
+# ---------------------------------------------------------------------------
+
+
+class TestConfigureLogging:
+    def test_sets_lambda_tasks_logger_to_info_by_default(self, monkeypatch):
+        """Without LAMBDA_TASKS_LOG_LEVEL env var, the lambda_tasks logger is set to INFO."""
+        monkeypatch.delenv("LAMBDA_TASKS_LOG_LEVEL", raising=False)
+        logging.getLogger("lambda_tasks").setLevel(logging.NOTSET)
+        _configure_logging()
+        assert logging.getLogger("lambda_tasks").level == logging.INFO
+
+    def test_task_logger_effective_level_is_info(self, monkeypatch):
+        """task_logger (lambda_tasks.task) inherits INFO from the parent."""
+        monkeypatch.delenv("LAMBDA_TASKS_LOG_LEVEL", raising=False)
+        logging.getLogger("lambda_tasks").setLevel(logging.NOTSET)
+        _configure_logging()
+        assert (
+            logging.getLogger("lambda_tasks.task").getEffectiveLevel() == logging.INFO
+        )
+
+    def test_respects_lambda_tasks_log_level_env_var(self, monkeypatch):
+        """LAMBDA_TASKS_LOG_LEVEL env var controls the logger level."""
+        monkeypatch.setenv("LAMBDA_TASKS_LOG_LEVEL", "DEBUG")
+        logging.getLogger("lambda_tasks").setLevel(logging.NOTSET)
+        _configure_logging()
+        assert logging.getLogger("lambda_tasks").level == logging.DEBUG
+
+    def test_invalid_log_level_falls_back_to_info(self, monkeypatch):
+        """An invalid LAMBDA_TASKS_LOG_LEVEL value falls back to INFO."""
+        monkeypatch.setenv("LAMBDA_TASKS_LOG_LEVEL", "NONSENSE")
+        logging.getLogger("lambda_tasks").setLevel(logging.NOTSET)
+        _configure_logging()
+        assert logging.getLogger("lambda_tasks").level == logging.INFO
+
+    def test_does_not_override_explicit_django_logging_config(self, monkeypatch):
+        """If Django's LOGGING dictConfig already set a level, _configure_logging leaves it alone."""
+        monkeypatch.delenv("LAMBDA_TASKS_LOG_LEVEL", raising=False)
+        # Simulate Django dictConfig having set the logger to WARNING
+        logging.getLogger("lambda_tasks").setLevel(logging.WARNING)
+        _configure_logging()
+        assert logging.getLogger("lambda_tasks").level == logging.WARNING