django-lambda-tasks 0.4.10__tar.gz → 0.5.0__tar.gz

{django_lambda_tasks-0.4.10 → django_lambda_tasks-0.5.0}/.kiro/steering/product.md

@@ -24,10 +24,9 @@ Key modules:
 
 ```python
 # Always kwargs-only — positional args raise TypeError at decoration time
-@lambda_task(delay=0, retry_delay=30, soft_timeout=60, hard_timeout=120, queue="default",
-             ignore_errors=(SomeExpectedException,),
+@lambda_task(retry_delay=30, soft_timeout=60, hard_timeout=120, queue="default",
              retry_on=(TransientError,),
-             singleton=True)
+             singleton=True, retry_singleton=True)
 def my_task(*, user_id: int, action: str) -> None:
     ...
 ```
@@ -39,34 +38,14 @@ def my_task(*, user_id: int, action: str) -> None:
 
 ## Enqueuing
 
-`execute_on_commit()` uses the decorator `delay` value by default. Pass `_delay=<seconds>` at call time to override the delay for that specific enqueue:
+`execute_on_commit()` defaults to delay 0. Pass `_delay=<seconds>` at call time to set the SQS delay for that specific enqueue:
 
 ```python
-my_task.execute_on_commit(user_id=1, action="x")            # uses decorator delay
-my_task.execute_on_commit(user_id=1, action="x", _delay=60) # overrides with 60s
+my_task.execute_on_commit(user_id=1, action="x")            # delay 0
+my_task.execute_on_commit(user_id=1, action="x", _delay=60) # 60s delay
 ```
 
-The `_delay` override is validated against the same range `[0, 900]` as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
-
-## ignore_errors
-
-Pass a tuple of exception types to `ignore_errors` on `@lambda_task`. If the task raises an instance of any of those types (or a subclass), the executor treats it as a non-fatal outcome:
-
-- `TaskRecord.status` is set to `SUCCESS`
-- The exception traceback is saved to `TaskRecord.traceback` for observability
-- Task-side ORM writes inside the `transaction.atomic()` block are still rolled back
-- The `TaskRecord` update itself is committed outside the atomic block
-
-Exceptions not listed in `ignore_errors` continue to produce `FAILED` with a rollback. Omitting `ignore_errors` (or passing `()`) preserves the existing behaviour.
-
-```python
-@lambda_task(ignore_errors=(RecordNotFound,))
-def sync_user(*, user_id: int) -> None:
-    # RecordNotFound → SUCCESS + traceback recorded; anything else → FAILED
-    ...
-```
-
-`ignore_errors` is validated at decoration time — passing a non-exception type raises `TypeError` immediately. It is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
+The `_delay` override is validated against the range `[0, 900]`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
 
 ## retry_on
 
@@ -75,8 +54,6 @@ Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task rai
 - `TaskRecord.status` is set to `RETRYING` and the traceback is recorded
 - The retry is a new invocation — the current record is terminal at `RETRYING`
 - Retries continue until `n_retries` reaches `LAMBDA_TASKS_MAX_RETRIES`, at which point `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
-- `ignore_errors` is checked first — a type in both `ignore_errors` and `retry_on` is treated as ignored (SUCCESS), not retried
-- `retry_on` and `ignore_errors` must not overlap (exact match or subclass relationship); overlapping raises `TypeError` at decoration time
 
 ```python
 @lambda_task(retry_on=(RateLimitError, ConnectionError))
@@ -97,7 +74,8 @@ Pass `singleton=True` on `@lambda_task` to prevent concurrent execution of the s
 
 - Lock key format: `lambda_tasks.singleton_lock.{task_name}`
 - The lock is acquired with `blocking_timeout=0` (fail immediately if held) and `timeout=hard_timeout` (auto-expire if the worker crashes)
-- If the lock cannot be acquired (`LockError`), the executor treats it as a retryable exception — same code path as `retry_on`. The `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If the lock cannot be acquired (`LockError`) and `retry_singleton=True` (default), the executor treats it as a retryable exception — same code path as `retry_on`. The `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If `retry_singleton=False`, lock contention is treated as a successful no-op — `TaskRecord` is set to `SUCCESS` with the traceback recorded, and no retry is enqueued
 - If `n_retries` has reached `LAMBDA_TASKS_MAX_RETRIES`, `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
 - The cache backend used for locks is controlled by `LAMBDA_TASKS_SINGLETON_CACHE` (default `"default"`)
 
@@ -106,9 +84,14 @@ Pass `singleton=True` on `@lambda_task` to prevent concurrent execution of the s
 def sync_inventory(*, warehouse_id: int) -> None:
     # Only one instance runs at a time; LockError → RETRYING + re-enqueued
     ...
+
+@lambda_task(singleton=True, retry_singleton=False)
+def sync_inventory(*, warehouse_id: int) -> None:
+    # Only one instance runs at a time; LockError → SUCCESS + traceback (no retry)
+    ...
 ```
 
-`singleton` is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
+`singleton` and `retry_singleton` are stored on `LambdaTaskWrapper` and read by the executor at execution time; they are never serialised into the SQS message.
 
 ## SQS Message Schema (`SQSLambdaTaskMessage`)
 
@@ -130,8 +113,8 @@ class SQSLambdaTaskMessage(BaseModel):
 4. If `wrapper.singleton` is `True`, acquires a Redis lock via `caches[SINGLETON_CACHE].lock(lock_key)` wrapping the atomic block; if `False`, no lock is acquired
 5. Runs task inside `transaction.atomic()` + `TimeoutContext`
 6. On success: updates record to `SUCCESS` with result and `end_time`
-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`
+7. On `LockError` when `singleton=True` and `retry_singleton=False`: 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 with `retry_singleton=True`, `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 and `end_time`
 
@@ -155,12 +138,12 @@ class SQSLambdaTaskMessage(BaseModel):
 
 When the environment variable `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` is set, the loader parses the reference, fetches the named Secrets Manager secret, parses its JSON content as a flat key-value mapping, and sets the resulting pairs as environment variables.
 
-Required format: `<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.
+Required format: `<arn>:<version-id>` (8 colon-separated segments — the ARN is 7 segments, plus the version-id). The version-id must be non-empty.
 
 Behaviour:
 - If `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` is not set, does nothing (no AWS API calls)
 - Validates the reference format before any AWS call — malformed references raise `ValueError` immediately
-- Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionStage=..., VersionId=...)`
+- Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., VersionId=...)`
 - Validates the secret value is a flat JSON object (all values must be strings, no empty keys)
 - Sets each key-value pair in `os.environ` — existing env vars are overridden (no conflict detection)
 - Idempotent via a module-level `_loaded` sentinel — subsequent calls are free no-ops
@@ -172,12 +155,12 @@ Behaviour:
 
 Any env var prefixed `LAMBDA_TASKS_SECRET_` is treated as a Secrets Manager reference. The unprefixed name is the target env var.
 
-Required format: `<arn>:<json-key>:<version-stage>:<version-id>` (10 colon-separated segments, all fields non-empty).
+Required format: `<arn>:<json-key>:<version-stage>:<version-id>` (10 colon-separated segments). The version-stage segment must be empty. The json-key and version-id must be non-empty.
 
 Behaviour:
 - All references are validated before any AWS call — malformed references raise `ValueError` immediately
 - Setting both `LAMBDA_TASKS_SECRET_FOO` and `FOO` is a configuration error and raises `ValueError`
-- Calls are batched by `(ARN, version-stage, version-id)` — one `GetSecretValue` per unique combination
+- Calls are batched by `(ARN, version-id)` — one `GetSecretValue` per unique combination
 - Fetched secrets are cached in-process; warm invocations pay no extra cost
 
 ## Models

{django_lambda_tasks-0.4.10 → django_lambda_tasks-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-lambda-tasks
-Version: 0.4.10
+Version: 0.5.0
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.10
 Requires-Dist: awslambdaric
@@ -74,7 +74,7 @@ def register(request):
 You can override the delay for a specific enqueue by passing `_delay`:
 
 ```python
-# Delay this particular invocation by 60 seconds instead of the decorator default
+# Delay this particular invocation by 60 seconds
 send_welcome_email.execute_on_commit(user_id=user.id, template="welcome", _delay=60)
 ```
 
@@ -150,7 +150,7 @@ LAMBDA_TASKS_DEFAULT_HARD_TIMEOUT = 270
 
 | 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_ENVIRONMENT_SECRETS_MANAGER_ARN` | env var | Secrets Manager reference (`<arn>:<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.
@@ -203,14 +203,13 @@ Key characteristics:
 
 ```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
-    ignore_errors=(),      # exception types treated as non-fatal
     retry_on=(),           # exception types that trigger automatic retry
     retry_delay=0,         # base retry delay in seconds (jitter always added, capped at 900)
     singleton=False,       # prevent concurrent execution via Redis lock
+    retry_singleton=True,  # retry on LockError for singleton tasks (or treat as success if False)
 )
 def my_task(*, arg: str) -> None:
     ...
@@ -218,32 +217,31 @@ 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. |
-| `ignore_errors` | `tuple[type[BaseException], ...]` | `()` | Exception types to treat as non-fatal (see [Ignored exceptions](#ignored-exceptions)). |
 | `retry_on` | `tuple[type[BaseException], ...]` | `()` | Exception types that trigger an automatic retry (see [Automatic retries](#automatic-retries)). |
 | `retry_delay` | `int` | `0` | Base delay in seconds when enqueuing a retry. Jitter (1–5s) is always added; result capped at 900. Requires `retry_on` to be non-empty. |
 | `singleton` | `bool` | `False` | Prevent concurrent execution via a Redis lock (see [Singleton tasks](#singleton-tasks)). |
+| `retry_singleton` | `bool` | `True` | When `True`, `LockError` on a singleton task triggers a retry. When `False`, lock contention is treated as a successful no-op (traceback recorded). |
 
 ### Per-call delay override
 
-The `delay` decorator parameter sets the default SQS `DelaySeconds` for all invocations of a task. To override it for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
+By default, `execute_on_commit()` uses a delay of 0 seconds. To set the SQS `DelaySeconds` for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
 
 ```python
-@lambda_task(delay=0)
+@lambda_task
 def notify_user(*, user_id: int) -> None:
     ...
 
-# Uses the decorator default (0 seconds)
+# Default (0 seconds delay)
 notify_user.execute_on_commit(user_id=1)
 
-# Override: delay this specific invocation by 120 seconds
+# Delay this specific invocation by 120 seconds
 notify_user.execute_on_commit(user_id=1, _delay=120)
 ```
 
-`_delay` is validated against the same `[0, 900]` range as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
+`_delay` is validated against the range `[0, 900]`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
 
 ---
 
@@ -386,35 +384,6 @@ fields @timestamp, @message
 
 ---
 
-## Ignored exceptions
-
-Pass a tuple of exception types to `ignore_errors` on `@lambda_task`. If the task raises an instance of any listed type (or a subclass), the executor treats it as a non-fatal outcome:
-
-- `TaskRecord.status` is set to `SUCCESS`
-- The exception traceback is saved to `TaskRecord.traceback` for observability
-- Task-side ORM writes inside the `transaction.atomic()` block are still rolled back
-- The `TaskRecord` update is committed outside the atomic block
-
-Exceptions not in `ignore_errors` continue to produce `FAILED` with a rollback. The default (`()`) preserves existing behaviour.
-
-```python
-from lambda_tasks.decorators import lambda_task
-
-class RecordNotFound(Exception):
-    pass
-
-@lambda_task(ignore_errors=(RecordNotFound,))
-def sync_user(*, user_id: int) -> None:
-    user = fetch_user(user_id)   # raises RecordNotFound if already deleted
-    update_profile(user)
-```
-
-If `sync_user` raises `RecordNotFound`, the `TaskRecord` will have `status=SUCCESS` and the traceback recorded in `traceback`. Any ORM writes made before the exception are rolled back.
-
-`ignore_errors` is validated at decoration time — passing a non-exception type raises `TypeError` immediately. It is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
-
----
-
 ## Automatic retries
 
 Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task raises an instance of any listed type (or a subclass), the executor re-enqueues the task with an incremented retry counter:
@@ -422,8 +391,6 @@ Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task rai
 - `TaskRecord.status` is set to `RETRYING` and the traceback is recorded
 - The retry is a new invocation — the current record is terminal at `RETRYING`
 - Retries continue until `n_retries` reaches `LAMBDA_TASKS_MAX_RETRIES` (default `2880`), at which point `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
-- `ignore_errors` is checked first — a type in both `ignore_errors` and `retry_on` is treated as ignored (SUCCESS), not retried
-- `retry_on` and `ignore_errors` must not overlap; overlapping raises `TypeError` at decoration time
 
 ```python
 from lambda_tasks.decorators import lambda_task
@@ -450,19 +417,27 @@ from lambda_tasks.decorators import lambda_task
 
 @lambda_task(singleton=True)
 def sync_inventory(*, warehouse_id: int) -> None:
-    # Only one instance runs at a time
+    # Only one instance runs at a time; LockError → RETRYING + re-enqueued
     ...
 ```
 
 - Lock key format: `lambda_tasks.singleton_lock.{task_name}`
 - The lock is acquired with `blocking_timeout=0` (fail immediately if held) and `timeout=hard_timeout` (auto-expire if the worker crashes)
-- If the lock cannot be acquired (`LockError`), the task is retried via the existing retry mechanism — `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If the lock cannot be acquired (`LockError`) and `retry_singleton=True` (the default), the task is retried — `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If `retry_singleton=False`, lock contention is treated as a successful no-op — `TaskRecord` is set to `SUCCESS` with the traceback recorded, and no retry is enqueued
 - If `n_retries` reaches `LAMBDA_TASKS_MAX_RETRIES`, `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
 - The cache backend used for locks is controlled by `LAMBDA_TASKS_SINGLETON_CACHE` (default `"default"`)
 
-`LockError` is retried automatically for singleton tasks — do not include it in `retry_on` (doing so raises `TypeError` at decoration time). You may include `LockError` in `ignore_errors` if you want lock contention to be treated as a non-fatal outcome instead of triggering a retry.
+`LockError` is handled automatically for singleton tasks — do not include it in `retry_on` (doing so raises `TypeError` at decoration time).
+
+`singleton` and `retry_singleton` are stored on `LambdaTaskWrapper` and read by the executor at execution time; they are never serialised into the SQS message.
 
-`singleton` is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
+```python
+@lambda_task(singleton=True, retry_singleton=False)
+def sync_inventory(*, warehouse_id: int) -> None:
+    # Lock contention → SUCCESS with traceback (no retry)
+    ...
+```
 
 ---
 
@@ -470,8 +445,6 @@ def sync_inventory(*, warehouse_id: int) -> None:
 
 Each task runs inside a `django.db.transaction.atomic` block. If the task raises an unhandled exception, all ORM writes made inside the task are rolled back. The `TaskRecord` failure update is always written outside the atomic block so it survives the rollback.
 
-When an exception matches `ignore_errors`, the same rollback applies to task-side writes — the atomic block still exits via exception. Only the `TaskRecord` update (written outside the block) is committed, recording the `SUCCESS` outcome and traceback.
-
 ---
 
 ## Error handling
@@ -519,20 +492,20 @@ 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 (runs first). |
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<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:
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version ID:
 
 ```
-LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment: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 format is `<arn>:<version-id>` (8 colon-separated segments — the ARN is 7 segments, plus the version-id). The version-id must be non-empty.
 
 The secret value must be a flat JSON object where all keys and values are strings:
 
@@ -547,8 +520,8 @@ The secret value must be a flat JSON object where all keys and values are string
 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=...)`
+2. Parses and validates the reference format (8 segments, non-empty version-id)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., 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
@@ -559,7 +532,7 @@ Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_
 
 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)
+- Reference format is invalid (wrong segment count, empty 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
@@ -573,14 +546,14 @@ The Lambda handler supports loading individual secret values from AWS Secrets Ma
 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:
 
 ```
-LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
+LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL::v1
 ```
 
 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
-3. Groups references by `(ARN, version-stage, version-id)` and makes one `GetSecretValue` call per unique combination
+3. Groups references by `(ARN, version-id)` and makes one `GetSecretValue` call per unique combination
 4. Extracts the named JSON key from the secret and writes it into `os.environ`
 5. Caches fetched secrets in-process — warm invocations pay no extra cost
 
@@ -592,18 +565,18 @@ Every value must follow the full dynamic reference syntax:
 <arn>:<json-key>:<version-stage>:<version-id>
 ```
 
-All four fields are required and must be non-empty. The secret value must be a JSON object; `json-key` names the field to extract.
+The version-stage segment must be empty. The json-key and version-id fields are required and must be non-empty. The secret value must be a JSON object; `json-key` names the field to extract.
 
 ```
-# arn (7 segments) : json-key : version-stage : version-id
-arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
+# arn (7 segments) : json-key : version-stage (empty) : version-id
+arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL::v1
 ```
 
-Multiple env vars can reference different keys from the same secret — only one `GetSecretValue` call is made for that `(ARN, version-stage, version-id)` combination:
+Multiple env vars can reference different keys from the same secret — only one `GetSecretValue` call is made for that `(ARN, version-id)` combination:
 
 ```
-LAMBDA_TASKS_SECRET_DATABASE_URL=arn:...:myapp/prod:DATABASE_URL:AWSCURRENT:v1
-LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY:AWSCURRENT:v1
+LAMBDA_TASKS_SECRET_DATABASE_URL=arn:...:myapp/prod:DATABASE_URL::v1
+LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY::v1
 ```
 
 #### Validation errors
@@ -611,7 +584,8 @@ LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY:AWSCURRENT:v1
 The following all raise `ValueError` at cold start, preventing the Lambda container from starting with a misconfigured environment:
 
 - Wrong number of colon-separated segments (must be exactly 10)
-- Empty `json-key`, `version-stage`, or `version-id`
+- Empty `json-key` or `version-id`
+- Non-empty `version-stage` (version-stage is not supported)
 - Both `LAMBDA_TASKS_SECRET_FOO` and `FOO` are set — use one or the other
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON

{django_lambda_tasks-0.4.10 → django_lambda_tasks-0.5.0}/README.md

@@ -62,7 +62,7 @@ def register(request):
 You can override the delay for a specific enqueue by passing `_delay`:
 
 ```python
-# Delay this particular invocation by 60 seconds instead of the decorator default
+# Delay this particular invocation by 60 seconds
 send_welcome_email.execute_on_commit(user_id=user.id, template="welcome", _delay=60)
 ```
 
@@ -138,7 +138,7 @@ LAMBDA_TASKS_DEFAULT_HARD_TIMEOUT = 270
 
 | 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_ENVIRONMENT_SECRETS_MANAGER_ARN` | env var | Secrets Manager reference (`<arn>:<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.
@@ -191,14 +191,13 @@ Key characteristics:
 
 ```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
-    ignore_errors=(),      # exception types treated as non-fatal
     retry_on=(),           # exception types that trigger automatic retry
     retry_delay=0,         # base retry delay in seconds (jitter always added, capped at 900)
     singleton=False,       # prevent concurrent execution via Redis lock
+    retry_singleton=True,  # retry on LockError for singleton tasks (or treat as success if False)
 )
 def my_task(*, arg: str) -> None:
     ...
@@ -206,32 +205,31 @@ 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. |
-| `ignore_errors` | `tuple[type[BaseException], ...]` | `()` | Exception types to treat as non-fatal (see [Ignored exceptions](#ignored-exceptions)). |
 | `retry_on` | `tuple[type[BaseException], ...]` | `()` | Exception types that trigger an automatic retry (see [Automatic retries](#automatic-retries)). |
 | `retry_delay` | `int` | `0` | Base delay in seconds when enqueuing a retry. Jitter (1–5s) is always added; result capped at 900. Requires `retry_on` to be non-empty. |
 | `singleton` | `bool` | `False` | Prevent concurrent execution via a Redis lock (see [Singleton tasks](#singleton-tasks)). |
+| `retry_singleton` | `bool` | `True` | When `True`, `LockError` on a singleton task triggers a retry. When `False`, lock contention is treated as a successful no-op (traceback recorded). |
 
 ### Per-call delay override
 
-The `delay` decorator parameter sets the default SQS `DelaySeconds` for all invocations of a task. To override it for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
+By default, `execute_on_commit()` uses a delay of 0 seconds. To set the SQS `DelaySeconds` for a specific call, pass `_delay` to `execute_on_commit()` or `serialize()`:
 
 ```python
-@lambda_task(delay=0)
+@lambda_task
 def notify_user(*, user_id: int) -> None:
     ...
 
-# Uses the decorator default (0 seconds)
+# Default (0 seconds delay)
 notify_user.execute_on_commit(user_id=1)
 
-# Override: delay this specific invocation by 120 seconds
+# Delay this specific invocation by 120 seconds
 notify_user.execute_on_commit(user_id=1, _delay=120)
 ```
 
-`_delay` is validated against the same `[0, 900]` range as the decorator `delay`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
+`_delay` is validated against the range `[0, 900]`. It only affects the SQS `DelaySeconds` — it has no effect in eager or async-local mode.
 
 ---
 
@@ -374,35 +372,6 @@ fields @timestamp, @message
 
 ---
 
-## Ignored exceptions
-
-Pass a tuple of exception types to `ignore_errors` on `@lambda_task`. If the task raises an instance of any listed type (or a subclass), the executor treats it as a non-fatal outcome:
-
-- `TaskRecord.status` is set to `SUCCESS`
-- The exception traceback is saved to `TaskRecord.traceback` for observability
-- Task-side ORM writes inside the `transaction.atomic()` block are still rolled back
-- The `TaskRecord` update is committed outside the atomic block
-
-Exceptions not in `ignore_errors` continue to produce `FAILED` with a rollback. The default (`()`) preserves existing behaviour.
-
-```python
-from lambda_tasks.decorators import lambda_task
-
-class RecordNotFound(Exception):
-    pass
-
-@lambda_task(ignore_errors=(RecordNotFound,))
-def sync_user(*, user_id: int) -> None:
-    user = fetch_user(user_id)   # raises RecordNotFound if already deleted
-    update_profile(user)
-```
-
-If `sync_user` raises `RecordNotFound`, the `TaskRecord` will have `status=SUCCESS` and the traceback recorded in `traceback`. Any ORM writes made before the exception are rolled back.
-
-`ignore_errors` is validated at decoration time — passing a non-exception type raises `TypeError` immediately. It is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
-
----
-
 ## Automatic retries
 
 Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task raises an instance of any listed type (or a subclass), the executor re-enqueues the task with an incremented retry counter:
@@ -410,8 +379,6 @@ Pass a tuple of exception types to `retry_on` on `@lambda_task`. If the task rai
 - `TaskRecord.status` is set to `RETRYING` and the traceback is recorded
 - The retry is a new invocation — the current record is terminal at `RETRYING`
 - Retries continue until `n_retries` reaches `LAMBDA_TASKS_MAX_RETRIES` (default `2880`), at which point `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
-- `ignore_errors` is checked first — a type in both `ignore_errors` and `retry_on` is treated as ignored (SUCCESS), not retried
-- `retry_on` and `ignore_errors` must not overlap; overlapping raises `TypeError` at decoration time
 
 ```python
 from lambda_tasks.decorators import lambda_task
@@ -438,19 +405,27 @@ from lambda_tasks.decorators import lambda_task
 
 @lambda_task(singleton=True)
 def sync_inventory(*, warehouse_id: int) -> None:
-    # Only one instance runs at a time
+    # Only one instance runs at a time; LockError → RETRYING + re-enqueued
     ...
 ```
 
 - Lock key format: `lambda_tasks.singleton_lock.{task_name}`
 - The lock is acquired with `blocking_timeout=0` (fail immediately if held) and `timeout=hard_timeout` (auto-expire if the worker crashes)
-- If the lock cannot be acquired (`LockError`), the task is retried via the existing retry mechanism — `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If the lock cannot be acquired (`LockError`) and `retry_singleton=True` (the default), the task is retried — `TaskRecord` is set to `RETRYING`, the traceback is recorded, and the task is re-enqueued with `n_retries + 1`
+- If `retry_singleton=False`, lock contention is treated as a successful no-op — `TaskRecord` is set to `SUCCESS` with the traceback recorded, and no retry is enqueued
 - If `n_retries` reaches `LAMBDA_TASKS_MAX_RETRIES`, `MaxRetriesExceededError` is raised and the record is saved as `FAILED`
 - The cache backend used for locks is controlled by `LAMBDA_TASKS_SINGLETON_CACHE` (default `"default"`)
 
-`LockError` is retried automatically for singleton tasks — do not include it in `retry_on` (doing so raises `TypeError` at decoration time). You may include `LockError` in `ignore_errors` if you want lock contention to be treated as a non-fatal outcome instead of triggering a retry.
+`LockError` is handled automatically for singleton tasks — do not include it in `retry_on` (doing so raises `TypeError` at decoration time).
+
+`singleton` and `retry_singleton` are stored on `LambdaTaskWrapper` and read by the executor at execution time; they are never serialised into the SQS message.
 
-`singleton` is stored on `LambdaTaskWrapper` and read by the executor at execution time; it is never serialised into the SQS message.
+```python
+@lambda_task(singleton=True, retry_singleton=False)
+def sync_inventory(*, warehouse_id: int) -> None:
+    # Lock contention → SUCCESS with traceback (no retry)
+    ...
+```
 
 ---
 
@@ -458,8 +433,6 @@ def sync_inventory(*, warehouse_id: int) -> None:
 
 Each task runs inside a `django.db.transaction.atomic` block. If the task raises an unhandled exception, all ORM writes made inside the task are rolled back. The `TaskRecord` failure update is always written outside the atomic block so it survives the rollback.
 
-When an exception matches `ignore_errors`, the same rollback applies to task-side writes — the atomic block still exits via exception. Only the `TaskRecord` update (written outside the block) is committed, recording the `SUCCESS` outcome and traceback.
-
 ---
 
 ## Error handling
@@ -507,20 +480,20 @@ 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 (runs first). |
+| `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` | No | Secrets Manager reference (`<arn>:<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:
+Set the `LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN` environment variable to a full reference including version ID:
 
 ```
-LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment:AWSCURRENT:v1
+LAMBDA_TASKS_ENVIRONMENT_SECRETS_MANAGER_ARN=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod/environment: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 format is `<arn>:<version-id>` (8 colon-separated segments — the ARN is 7 segments, plus the version-id). The version-id must be non-empty.
 
 The secret value must be a flat JSON object where all keys and values are strings:
 
@@ -535,8 +508,8 @@ The secret value must be a flat JSON object where all keys and values are string
 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=...)`
+2. Parses and validates the reference format (8 segments, non-empty version-id)
+3. Fetches the secret via `secretsmanager.get_secret_value(SecretId=..., 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
@@ -547,7 +520,7 @@ Because environment loading runs first, the secret can provide `DJANGO_SETTINGS_
 
 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)
+- Reference format is invalid (wrong segment count, empty 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
@@ -561,14 +534,14 @@ The Lambda handler supports loading individual secret values from AWS Secrets Ma
 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:
 
 ```
-LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
+LAMBDA_TASKS_SECRET_DATABASE_URL=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL::v1
 ```
 
 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
-3. Groups references by `(ARN, version-stage, version-id)` and makes one `GetSecretValue` call per unique combination
+3. Groups references by `(ARN, version-id)` and makes one `GetSecretValue` call per unique combination
 4. Extracts the named JSON key from the secret and writes it into `os.environ`
 5. Caches fetched secrets in-process — warm invocations pay no extra cost
 
@@ -580,18 +553,18 @@ Every value must follow the full dynamic reference syntax:
 <arn>:<json-key>:<version-stage>:<version-id>
 ```
 
-All four fields are required and must be non-empty. The secret value must be a JSON object; `json-key` names the field to extract.
+The version-stage segment must be empty. The json-key and version-id fields are required and must be non-empty. The secret value must be a JSON object; `json-key` names the field to extract.
 
 ```
-# arn (7 segments) : json-key : version-stage : version-id
-arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL:AWSCURRENT:v1
+# arn (7 segments) : json-key : version-stage (empty) : version-id
+arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/prod:DATABASE_URL::v1
 ```
 
-Multiple env vars can reference different keys from the same secret — only one `GetSecretValue` call is made for that `(ARN, version-stage, version-id)` combination:
+Multiple env vars can reference different keys from the same secret — only one `GetSecretValue` call is made for that `(ARN, version-id)` combination:
 
 ```
-LAMBDA_TASKS_SECRET_DATABASE_URL=arn:...:myapp/prod:DATABASE_URL:AWSCURRENT:v1
-LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY:AWSCURRENT:v1
+LAMBDA_TASKS_SECRET_DATABASE_URL=arn:...:myapp/prod:DATABASE_URL::v1
+LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY::v1
 ```
 
 #### Validation errors
@@ -599,7 +572,8 @@ LAMBDA_TASKS_SECRET_SECRET_KEY=arn:...:myapp/prod:SECRET_KEY:AWSCURRENT:v1
 The following all raise `ValueError` at cold start, preventing the Lambda container from starting with a misconfigured environment:
 
 - Wrong number of colon-separated segments (must be exactly 10)
-- Empty `json-key`, `version-stage`, or `version-id`
+- Empty `json-key` or `version-id`
+- Non-empty `version-stage` (version-stage is not supported)
 - Both `LAMBDA_TASKS_SECRET_FOO` and `FOO` are set — use one or the other
 - The named JSON key does not exist in the fetched secret
 - The secret value is not valid JSON