diff --git a/docs/index.md b/docs/index.md index 73d7a33e586..69a3ecb1bf2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ description: AWS Lambda Powertools for Python -A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, idempotency, batching, [**and more**](#features). +Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity. ???+ tip Powertools is also available for [Java](https://awslabs.github.io/aws-lambda-powertools-java/){target="_blank"}, [TypeScript](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/){target="_blank"}, and [.NET](https://awslabs.github.io/aws-lambda-powertools-dotnet/){target="_blank"} @@ -24,41 +24,52 @@ A suite of utilities for AWS Lambda functions to ease adopting best practices su ## Install -Powertools is available in the following formats: +You can install Powertools using one of the following options: * **Lambda Layer (x86_64)**: [**arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23**](#){: .copyMe}:clipboard: * **Lambda Layer (arm64)**: [**arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2-Arm64:23**](#){: .copyMe}:clipboard: -* **PyPi**: **`pip install "aws-lambda-powertools"`** +* **Pip**: **[`pip install "aws-lambda-powertools"`](#){: .copyMe}:clipboard:** -???+ info "Some utilities require additional dependencies" - You can stop reading if you're using Lambda Layer. - - [Tracer](./core/tracer.md){target="_blank"}, [Validation](./utilities/validation.md){target="_blank"} and [Parser](./utilities/parser.md){target="_blank"} require additional dependencies. If you prefer to install all of them, use `pip install "aws-lambda-powertools[all]"`. +??? question "Using Pip? You might need to install additional dependencies." + [**Tracer**](./core/tracer.md){target="_blank"}, [**Validation**](./utilities/validation.md){target="_blank"} and [**Parser**](./utilities/parser.md){target="_blank"} require additional dependencies. If you prefer to install all of them, use [**`pip install "aws-lambda-powertools[all]"`**](#){: .copyMe}:clipboard:. For example: - * [Tracer](./core/tracer.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[tracer]"`** - * [Validation](./utilities/validation.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[validation]"`** - * [Parser](./utilities/parser.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[parser]"`** - * [Tracer](./core/tracer.md#install){target="_blank"} and [Parser](./utilities/parser.md#install){target="_blank"}: **`pip install "aws-lambda-powertools[tracer,parser]"`** + * **Tracer**: **[`pip install "aws-lambda-powertools[tracer]"`](#){: .copyMe}:clipboard:** + * **Validation**: **[`pip install "aws-lambda-powertools[validation]"`](#){: .copyMe}:clipboard:** + * **Parser**: **[`pip install "aws-lambda-powertools[parser]"`](#){: .copyMe}:clipboard:** + * **Tracer** and **Parser**: **[`pip install "aws-lambda-powertools[tracer,parser]"`](#){: .copyMe}:clipboard:** ### Local development -Powertools relies on the AWS SDK bundled in the Lambda runtime. This helps us achieve an optimal package size and initialization. +!!! info "Using Powertools via Lambda Layer? Simply add [**`"aws-lambda-powertools[all]"`**](#){: .copyMe}:clipboard: as a development dependency." + +Powertools relies on the [AWS SDK bundled in the Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html){target="_blank"}. This helps us achieve an optimal package size and initialization. However, when developing locally, you need to install AWS SDK as a development dependency (not as a production dependency): + +* **Pip**: [**`pip install "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe}:clipboard: +* **Poetry**: [**`poetry add "aws-lambda-powertools[aws-sdk]" --group dev`**](#){: .copyMe}:clipboard: +* **Pipenv**: [**`pipenv install --dev "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe}:clipboard: + +??? question "Why is that necessary?" + Powertools relies on the AWS SDK being available to use in the target runtime (AWS Lambda). -This means you need to add AWS SDK as a development dependency (not as a production dependency). + As a result, it affects your favorite IDE in terms of code auto-completion, or running your tests suite locally with no Lambda emulation such as [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html){target="_blank"}. -* **Pip**: `pip install "aws-lambda-powertools[aws-sdk]"` -* **Poetry**: `poetry add "aws-lambda-powertools[aws-sdk]" --group dev` -* **Pipenv**: `pipenv install --dev "aws-lambda-powertools[aws-sdk]"` +**A word about dependency resolution** -???+ note "Local emulation" - If you're running your code locally with [AWS SAM CLI](https://github.com/aws/aws-sam-cli){target="_blank"}, and not with your Python/IDE interpreter directly, this is not necessary. SAM CLI already brings the AWS SDK in its emulation image. +In this context, `[aws-sdk]` is an alias to the `boto3` package. Due to dependency resolution, it'll either install: + +* **(A)** the SDK version available in [Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html){target="_blank"} +* **(B)** a more up-to-date version if another package you use also depends on `boto3`, for example [Powertools Tracer](core/tracer.md){target="_blank"} ### Lambda Layer +???+ warning "As of now, Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers." + [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data, or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic. +For our Layers, we compile and optimize [all dependencies](https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/pyproject.toml#L98){target="_blank"}, and [remove duplicate dependencies already available in the Lambda runtime](https://github.com/awslabs/cdk-aws-lambda-powertools-layer/blob/main/layer/Python/Dockerfile#L36){target="_blank"} to achieve the most optimal size. + You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html#invocation-layers-using){target="_blank"}, or your preferred deployment framework. ??? note "Note: Click to expand and copy any regional Lambda Layer ARN" @@ -271,16 +282,6 @@ You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs. ? Do you want to edit the local lambda function now? No ``` - === "Get the Layer .zip contents" - - Change {region} to your AWS region, e.g. `eu-west-1` - - ```bash title="AWS CLI" - aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23 --region {region} - ``` - - The pre-signed URL to download this Lambda Layer will be within `Location` key. - === "arm64" === "SAM" @@ -439,18 +440,14 @@ You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs. ? Do you want to edit the local lambda function now? No ``` - === "Get the Layer .zip contents" - Change {region} to your AWS region, e.g. `eu-west-1` +??? question "Want to inspect the contents of the Layer?" + Change {region} to your AWS region, e.g. `eu-west-1` - ```bash title="AWS CLI" - aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2-Arm64:23 --region {region} - ``` - - The pre-signed URL to download this Lambda Layer will be within `Location` key. - -???+ warning "Warning: Limitations" + ```bash title="AWS CLI" + aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:23 --region {region} + ``` - Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers. + The pre-signed URL to download this Lambda Layer will be within `Location` key. #### SAR