django-lambda-tasks 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

{django_lambda_tasks-0.2.2.dist-info → django_lambda_tasks-0.2.3.dist-info}/METADATA

@@ -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.dist-info → django_lambda_tasks-0.2.3.dist-info}/RECORD

@@ -3,7 +3,7 @@ lambda_tasks/admin.py,sha256=QEg6urQPIGF74Ef8v3cAMJn5ax-UzhWpfSdBU3YEvZ8,1211
 lambda_tasks/apps.py,sha256=WwIpa2eQQujLgdAq1HXVRSwIppRej14O9oU3NFygN6g,186
 lambda_tasks/decorators.py,sha256=lM4PXu6AnVVQ5yJSoomXi0hCmcq_oLQYxhCefKIUhtQ,15982
 lambda_tasks/environment_loader.py,sha256=9KW7lFWCf20x9DQ80Oqjj3Xnohfy8CnyUuyCFo95CyU,4757
-lambda_tasks/handler.py,sha256=8s7EUlkRNXVyVPuI6obcKD8SiBKcesD1HeME7ontZik,2327
+lambda_tasks/handler.py,sha256=j-tjk8PHU5RgjQKWv-b0d8nUGQgk9ZRnfrkZA-BUqwE,3307
 lambda_tasks/logging.py,sha256=vAFQ4fdKetdZ6GJhMRFd8gZxAfNuBI1mDbGJ_luKs30,1020
 lambda_tasks/models.py,sha256=OKftkn8ykbiINKPzTiTSpIHZdo0CFzS-T4uHeAWvUuo,9809
 lambda_tasks/secret_loader.py,sha256=8OMNMc_C2X6wOwohMkEJakjflNiNxNyQ7fZacFCvMmE,6657
@@ -12,6 +12,6 @@ lambda_tasks/tasks.py,sha256=wFUnreosmK8wuYJCDSlL1ndbw3w4JG1hqoWC4G3lcYo,651
 lambda_tasks/timeouts.py,sha256=vO-0-gmcRPhMbWRmshd2TM5dy_RCdI6oW_WpR50ohNI,2593
 lambda_tasks/migrations/0001_initial.py,sha256=73evCSkciOn3e9h8dPp88m4Y_nhHzYC9cz3Fv0WcuUc,2356
 lambda_tasks/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_lambda_tasks-0.2.2.dist-info/METADATA,sha256=_L8xOTZIxJhVJy8Lur0IpRlGRl8gtJoW29lN5KXT2MU,24963
-django_lambda_tasks-0.2.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-django_lambda_tasks-0.2.2.dist-info/RECORD,,
+django_lambda_tasks-0.2.3.dist-info/METADATA,sha256=OEK_CxPCqcFQpuTv0-kAhqWKYhPjkR_EXwqZodl7aBI,27142
+django_lambda_tasks-0.2.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+django_lambda_tasks-0.2.3.dist-info/RECORD,,

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.