docs(api): migrating the batch utility to mkdocstrings (aws-powertool…

…s#6016) * Mkdocstrings - Batch module * Mkdocstrings - Batch module
sinofseven · Feb 13, 2025 · b037568 · b037568
1 parent d8263ad
commit b037568
Show file tree

Hide file tree

Showing 13 changed files with 37 additions and 29 deletions.
diff --git a/aws_lambda_powertools/logging/__init__.py b/aws_lambda_powertools/logging/__init__.py
@@ -1,5 +1,4 @@
-"""Logging utility
-"""
+"""Logging utility"""
 
 from .logger import Logger
 

diff --git a/aws_lambda_powertools/metrics/__init__.py b/aws_lambda_powertools/metrics/__init__.py
@@ -1,5 +1,4 @@
-"""CloudWatch Embedded Metric Format utility
-"""
+"""CloudWatch Embedded Metric Format utility"""
 
 from aws_lambda_powertools.metrics.base import MetricResolution, MetricUnit, single_metric
 from aws_lambda_powertools.metrics.exceptions import (

diff --git a/aws_lambda_powertools/middleware_factory/__init__.py b/aws_lambda_powertools/middleware_factory/__init__.py
@@ -1,4 +1,4 @@
-""" Utilities to enhance middlewares """
+"""Utilities to enhance middlewares"""
 
 from .factory import lambda_handler_decorator
 

diff --git a/aws_lambda_powertools/tracing/__init__.py b/aws_lambda_powertools/tracing/__init__.py
@@ -1,5 +1,4 @@
-"""Tracing utility
-"""
+"""Tracing utility"""
 
 from .extensions import aiohttp_trace_config
 from .tracer import Tracer

diff --git a/aws_lambda_powertools/utilities/batch/base.py b/aws_lambda_powertools/utilities/batch/base.py
@@ -1,5 +1,7 @@
 """
 Batch processing utilities
+!!! abstract "Usage Documentation"
+    [`Batch processing`](../../utilities/batch.md)
 """
 
 from __future__ import annotations

diff --git a/aws_lambda_powertools/utilities/batch/decorators.py b/aws_lambda_powertools/utilities/batch/decorators.py
@@ -51,9 +51,8 @@ def async_batch_processor(
     processor: AsyncBatchProcessor
         Batch Processor to handle partial failure cases
 
-    Examples
+    Example
     --------
-    **Processes Lambda's event with a BasePartialProcessor**
         >>> from aws_lambda_powertools.utilities.batch import async_batch_processor, AsyncBatchProcessor
         >>> from aws_lambda_powertools.utilities.data_classes.sqs_event import SQSRecord
         >>>
@@ -119,7 +118,7 @@ def batch_processor(
     processor: BatchProcessor
         Batch Processor to handle partial failure cases
 
-    Examples
+    Example
     --------
     **Processes Lambda's event with a BatchProcessor**
 
@@ -180,7 +179,7 @@ def process_partial_response(
     result: PartialItemFailureResponse
         Lambda Partial Batch Response
 
-    Examples
+    Example
     --------
     **Processes Lambda's SQS event**
 
@@ -244,7 +243,7 @@ def async_process_partial_response(
     result: PartialItemFailureResponse
         Lambda Partial Batch Response
 
-    Examples
+    Example
     --------
     **Processes Lambda's SQS event**
 

diff --git a/aws_lambda_powertools/utilities/batch/sqs_fifo_partial_processor.py b/aws_lambda_powertools/utilities/batch/sqs_fifo_partial_processor.py
@@ -21,7 +21,7 @@ class SqsFifoPartialProcessor(BatchProcessor):
     Stops processing records when the first record fails. The remaining records are reported as failed items.
 
     Example
-    _______
+    -------
 
     ## Process batch triggered by a FIFO SQS
 

diff --git a/aws_lambda_powertools/utilities/data_masking/provider/kms/aws_encryption_sdk.py b/aws_lambda_powertools/utilities/data_masking/provider/kms/aws_encryption_sdk.py
@@ -142,17 +142,17 @@ def encrypt(self, data: Any, provider_options: dict | None = None, **encryption_
 
         Parameters
         -------
-            data : Any
-                The data to be encrypted.
-            provider_options : dict
-                Additional options for the aws_encryption_sdk.EncryptionSDKClient
-            **encryption_context : str
-                Additional keyword arguments collected into a dictionary.
+        data: Any
+            The data to be encrypted.
+        provider_options: dict
+            Additional options for the aws_encryption_sdk.EncryptionSDKClient
+        **encryption_context: str
+            Additional keyword arguments collected into a dictionary.
 
         Returns
         -------
-            ciphertext : str
-                The encrypted data, as a base64-encoded string.
+        ciphertext: str
+            The encrypted data, as a base64-encoded string.
         """
         provider_options = provider_options or {}
         self._validate_encryption_context(encryption_context)
@@ -179,15 +179,15 @@ def decrypt(self, data: str, provider_options: dict | None = None, **encryption_
 
         Parameters
         -------
-            data : str
-                The encrypted data, as a base64-encoded string
-            provider_options
-                Additional options for the aws_encryption_sdk.EncryptionSDKClient
+        data: str
+            The encrypted data, as a base64-encoded string
+        provider_options
+            Additional options for the aws_encryption_sdk.EncryptionSDKClient
 
         Returns
         -------
-            ciphertext : bytes
-                The decrypted data in bytes
+        ciphertext: bytes
+            The decrypted data in bytes
         """
         provider_options = provider_options or {}
         self._validate_encryption_context(encryption_context)

diff --git a/aws_lambda_powertools/utilities/parser/__init__.py b/aws_lambda_powertools/utilities/parser/__init__.py
@@ -1,5 +1,4 @@
-"""Advanced event_parser utility
-"""
+"""Advanced event_parser utility"""
 
 from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
 

diff --git a/docs/api_doc/batch/base.md b/docs/api_doc/batch/base.md
@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.utilities.batch.base
diff --git a/docs/api_doc/batch/decorators.md b/docs/api_doc/batch/decorators.md
@@ -0,0 +1,3 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.utilities.batch.decorators
+::: aws_lambda_powertools.utilities.batch.sqs_fifo_partial_processor
diff --git a/docs/api_doc/batch/exceptions.md b/docs/api_doc/batch/exceptions.md
@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.utilities.batch.exceptions
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -63,6 +63,10 @@ nav:
           #     - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md
           #     - Customer to advocate: contributing/tracks/customer_advocate.md
   - API Documentation:
+      - Batch Processing:
+          - Base: api_doc/batch/base.md
+          - Decorators: api_doc/batch/decorators.md
+          - Exceptions: api_doc/batch/exceptions.md
       - Event Source Data Classes: api_doc/data_classes.md
       - Data Masking:
           - Base: api_doc/data_masking/base.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -21,7 +21,7 @@ class SqsFifoPartialProcessor(BatchProcessor): @@
         Stops processing records when the first record fails. The remaining records are reported as failed items.
         Example
-        _______
+        -------
         ## Process batch triggered by a FIFO SQS
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		<!-- markdownlint-disable MD043 MD041 -->
		::: aws_lambda_powertools.utilities.batch.base