diff --git a/docs/media/utilities_typing.png b/docs/media/utilities_typing.png deleted file mode 100644 index 0f293abb6ec..00000000000 Binary files a/docs/media/utilities_typing.png and /dev/null differ diff --git a/docs/media/utilities_typing_1.png b/docs/media/utilities_typing_1.png new file mode 100644 index 00000000000..8476b9f093e Binary files /dev/null and b/docs/media/utilities_typing_1.png differ diff --git a/docs/media/utilities_typing_2.png b/docs/media/utilities_typing_2.png new file mode 100644 index 00000000000..2a045df0a07 Binary files /dev/null and b/docs/media/utilities_typing_2.png differ diff --git a/docs/media/utilities_typing_3.png b/docs/media/utilities_typing_3.png new file mode 100644 index 00000000000..88888f506c3 Binary files /dev/null and b/docs/media/utilities_typing_3.png differ diff --git a/docs/utilities/typing.md b/docs/utilities/typing.md index a23d014afa6..e94f6b49201 100644 --- a/docs/utilities/typing.md +++ b/docs/utilities/typing.md @@ -7,17 +7,40 @@ description: Utility This typing utility provides static typing classes that can be used to ease the development by providing the IDE type hints. -![Utilities Typing](../media/utilities_typing.png) +## Key features + +* Add static typing classes +* Ease the development by leveraging your IDE's type hints +* Avoid common typing mistakes in Python + +![Utilities Typing](../media/utilities_typing_1.png) + +## Getting started + +???+ tip + All examples shared in this documentation are available within the [project repository](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/examples){target="_blank"}. + +We provide static typing for any context methods or properties implemented by [Lambda context object](https://docs.aws.amazon.com/lambda/latest/dg/python-context.html){target="_blank"}. ## LambdaContext The `LambdaContext` typing is typically used in the handler method for the Lambda function. -```python hl_lines="4" title="Annotating Lambda context type" -from typing import Any, Dict -from aws_lambda_powertools.utilities.typing import LambdaContext +=== "getting_started_validator_decorator_function.py" + + ```python hl_lines="1 4" + --8<-- "examples/typing/src/getting_started_typing_function.py" + ``` + +## Working with context methods and properties + +Using `LambdaContext` typing makes it possible to access information and hints of all properties and methods implemented by Lambda context object. + +=== "working_with_context_function.py" + + ```python hl_lines="6 16 25 26" + --8<-- "examples/typing/src/working_with_context_function.py" + ``` -def handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]: - # Insert business logic - return event -``` +![Utilities Typing All](../media/utilities_typing_2.png) +![Utilities Typing Specific](../media/utilities_typing_3.png) diff --git a/examples/typing/src/getting_started_typing_function.py b/examples/typing/src/getting_started_typing_function.py new file mode 100644 index 00000000000..493f0c18b2e --- /dev/null +++ b/examples/typing/src/getting_started_typing_function.py @@ -0,0 +1,6 @@ +from aws_lambda_powertools.utilities.typing import LambdaContext + + +def handler(event: dict, context: LambdaContext) -> dict: + # Insert business logic + return event diff --git a/examples/typing/src/working_with_context_function.py b/examples/typing/src/working_with_context_function.py new file mode 100644 index 00000000000..bfe610efa38 --- /dev/null +++ b/examples/typing/src/working_with_context_function.py @@ -0,0 +1,32 @@ +from time import sleep + +import requests + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.utilities.typing import LambdaContext + +logger = Logger() + + +def lambda_handler(event, context: LambdaContext) -> dict: + + limit_execution: int = 1000 # milliseconds + + # scrape website and exit before lambda timeout + while context.get_remaining_time_in_millis() > limit_execution: + + comments: requests.Response = requests.get("https://jsonplaceholder.typicode.com/comments") + # add logic here and save the results of the request to an S3 bucket, for example. + + logger.info( + { + "operation": "scrape_website", + "request_id": context.aws_request_id, + "remaining_time": context.get_remaining_time_in_millis(), + "comments": comments.json()[:2], + } + ) + + sleep(1) + + return {"message": "Success"}