refactor(batch_processing): mark batch_processor and async_batch_processor as deprecated (#4910)

Deprecating decorators

Author: leandrodamascena

aws_lambda_powertools/utilities/batch/decorators.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
+import warnings
 from typing import Any, Awaitable, Callable, Dict, List
 
+from typing_extensions import deprecated
+
 from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
 from aws_lambda_powertools.utilities.batch import (
     AsyncBatchProcessor,
@@ -11,9 +14,14 @@
 )
 from aws_lambda_powertools.utilities.batch.types import PartialItemFailureResponse
 from aws_lambda_powertools.utilities.typing import LambdaContext
+from aws_lambda_powertools.warnings import PowertoolsDeprecationWarning
 
 
 @lambda_handler_decorator
+@deprecated(
+    "`async_batch_processor` decorator is deprecated; use `async_process_partial_response` function instead.",
+    category=None,
+)
 def async_batch_processor(
     handler: Callable,
     event: Dict,
@@ -61,6 +69,14 @@ def async_batch_processor(
     -----------
     * Sync batch processors. Use `batch_processor` instead.
     """
+
+    warnings.warn(
+        "The `async_batch_processor` decorator is deprecated in V3 "
+        "and will be removed in the next major version. Use `async_process_partial_response` function instead.",
+        category=PowertoolsDeprecationWarning,
+        stacklevel=2,
+    )
+
     records = event["Records"]
 
     with processor(records, record_handler, lambda_context=context):
@@ -70,6 +86,10 @@ def async_batch_processor(
 
 
 @lambda_handler_decorator
+@deprecated(
+    "`batch_processor` decorator is deprecated; use `process_partial_response` function instead.",
+    category=None,
+)
 def batch_processor(
     handler: Callable,
     event: Dict,
@@ -117,6 +137,14 @@ def batch_processor(
     -----------
     * Async batch processors. Use `async_batch_processor` instead.
     """
+
+    warnings.warn(
+        "The `batch_processor` decorator is deprecated in V3 "
+        "and will be removed in the next major version. Use `process_partial_response` function instead.",
+        category=PowertoolsDeprecationWarning,
+        stacklevel=2,
+    )
+
     records = event["Records"]
 
     with processor(records, record_handler, lambda_context=context):

docs/utilities/batch.md

@@ -119,7 +119,7 @@ Processing batches from SQS works in three stages:
     --8<-- "examples/batch_processing/src/getting_started_sqs_context_manager.py"
     ```
 
-=== "As a decorator (legacy)"
+=== "As a decorator (deprecated)"
 
     ```python hl_lines="4-9 12 18 27 29"
     --8<-- "examples/batch_processing/src/getting_started_sqs_decorator.py"
@@ -161,7 +161,7 @@ Enable the `skip_group_on_error` option for seamless processing of messages from
     --8<-- "examples/batch_processing/src/getting_started_sqs_fifo_context_manager.py"
     ```
 
-=== "As a decorator (legacy)"
+=== "As a decorator (deprecated)"
 
     ```python hl_lines="5-6 11 26"
     --8<-- "examples/batch_processing/src/getting_started_sqs_fifo_decorator.py"
@@ -197,7 +197,7 @@ Processing batches from Kinesis works in three stages:
     --8<-- "examples/batch_processing/src/getting_started_kinesis_context_manager.py"
     ```
 
-=== "As a decorator (legacy)"
+=== "As a decorator (deprecated)"
 
     ```python hl_lines="2-9 12 18 26"
     --8<-- "examples/batch_processing/src/getting_started_kinesis_decorator.py"
@@ -241,7 +241,7 @@ Processing batches from DynamoDB Streams works in three stages:
     --8<-- "examples/batch_processing/src/getting_started_dynamodb_context_manager.py"
     ```
 
-=== "As a decorator (legacy)"
+=== "As a decorator (deprecated)"
 
     ```python hl_lines="4-11 14 20 31"
     --8<-- "examples/batch_processing/src/getting_started_dynamodb_decorator.py"
@@ -538,7 +538,7 @@ We can automatically inject the [Lambda context](https://docs.aws.amazon.com/lam
     --8<-- "examples/batch_processing/src/advanced_accessing_lambda_context.py"
     ```
 
-=== "As a decorator (legacy)"
+=== "As a decorator (deprecated)"
 
     ```python hl_lines="18 26"
     --8<-- "examples/batch_processing/src/advanced_accessing_lambda_context_decorator.py"
@@ -673,7 +673,7 @@ Use context manager when you want access to the processed messages or handle `Ba
 
 ### What's the difference between the decorator and process_partial_response functions?
 
-`batch_processor` and `async_batch_processor` decorators are now considered legacy. Historically, they were kept due to backwards compatibility and to minimize code changes between V1 and V2.
+`batch_processor` and `async_batch_processor` decorators are now marked as deprecated. Historically, they were kept due to backwards compatibility and to minimize code changes between V2 and V3. We will remove both in the next major release.
 
 As 2.12.0, `process_partial_response` and `async_process_partial_response` are the recommended instead. It reduces boilerplate, smaller memory/CPU cycles, and it makes it less error prone - e.g., decorators required an additional return.
 

tests/functional/test_utilities_batch.py

@@ -32,6 +32,7 @@
     SqsRecordModel,
 )
 from aws_lambda_powertools.utilities.parser.types import Literal
+from aws_lambda_powertools.warnings import PowertoolsDeprecationWarning
 from tests.functional.batch.sample_models import (
     OrderDynamoDBRecord,
     OrderKinesisRecord,
@@ -857,10 +858,11 @@ def lambda_handler(event, context):
         return processor.response()
 
     # WHEN
-    result = lambda_handler(event, {})
+    with pytest.warns(PowertoolsDeprecationWarning, match="The `async_batch_processor` decorator is deprecated in V3*"):
+        result = lambda_handler(event, {})
 
-    # THEN
-    assert result["batchItemFailures"] == []
+        # THEN
+        assert result["batchItemFailures"] == []
 
 
 def test_async_batch_processor_middleware_with_failure(sqs_event_factory, async_record_handler):
@@ -877,10 +879,11 @@ def lambda_handler(event, context):
         return processor.response()
 
     # WHEN
-    result = lambda_handler(event, {})
+    with pytest.warns(PowertoolsDeprecationWarning, match="The `async_batch_processor` decorator is deprecated in V3*"):
+        result = lambda_handler(event, {})
 
-    # THEN
-    assert len(result["batchItemFailures"]) == 2
+        # THEN
+        assert len(result["batchItemFailures"]) == 2
 
 
 def test_async_batch_processor_context_success_only(sqs_event_factory, async_record_handler):