From d10c5ec073db02bf70ae5d8f484080131dd8a2ea Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Fri, 3 Mar 2023 15:09:51 +0100 Subject: [PATCH 1/6] docs(homepage): use new powertools description --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 73d7a33e586..09884c40338 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"} From d8b93693c3a595b7b5315dd83141ee68955011b9 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Fri, 3 Mar 2023 17:16:45 +0100 Subject: [PATCH 2/6] docs(install): revamp UX for install and local development --- docs/index.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/index.md b/docs/index.md index 09884c40338..f3c878f66c5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,36 +24,40 @@ Powertools is a developer toolkit to implement Serverless best practices and inc ## 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 might want to have IDE autocompletion, or run your tests suite locally without any emulation like [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html){target="_blank"}. For this to work, 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: -This means you need to add AWS SDK as a development dependency (not as a production dependency). +!!! note "A word about dependency resolution" -* **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]"` +In this context, `[aws-sdk]` is an alias to the `boto3` package. Due to dependency resolution, it'll either install: -???+ 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. +* **(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 From 299e0916e68417a19135ca406513fe90e27bbd58 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Fri, 3 Mar 2023 17:17:37 +0100 Subject: [PATCH 3/6] docs(install): make all deps in bold --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index f3c878f66c5..ed2d9388bd2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,7 +31,7 @@ You can install Powertools using one of the following options: * **Pip**: **[`pip install "aws-lambda-powertools"`](#){: .copyMe}:clipboard:** ??? 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:. + [**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: From 233e65b0ede44aa776921e341a982332fa32c5bd Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Fri, 3 Mar 2023 17:47:38 +0100 Subject: [PATCH 4/6] docs(install): explain how we build our layers along with links --- docs/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index ed2d9388bd2..5fa01e1b31e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -61,8 +61,12 @@ In this context, `[aws-sdk]` is an alias to the `boto3` package. Due to dependen ### 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" @@ -452,10 +456,6 @@ You can include Powertools Lambda Layer using [AWS Lambda Console](https://docs. The pre-signed URL to download this Lambda Layer will be within `Location` key. -???+ warning "Warning: Limitations" - - Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers. - #### SAR Serverless Application Repository (SAR) App deploys a CloudFormation stack with a copy of our Lambda Layer in your AWS account and region. From 4ec67387e936f8bb6c6f38efbb88bc02d1820d26 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Fri, 3 Mar 2023 18:37:29 +0100 Subject: [PATCH 5/6] docs(layer): make aws cli layer command to be more visible --- docs/index.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5fa01e1b31e..8fc07c26625 100644 --- a/docs/index.md +++ b/docs/index.md @@ -279,16 +279,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" @@ -447,14 +437,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} - ``` + ```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. + The pre-signed URL to download this Lambda Layer will be within `Location` key. #### SAR From cf5f71bdaab02bb9bcadacf4256a6496563229c9 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 6 Mar 2023 16:47:15 +0100 Subject: [PATCH 6/6] docs: shorten local development wording, new banner for those new to dev deps --- docs/index.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8fc07c26625..69a3ecb1bf2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,15 +44,18 @@ You can install Powertools using one of the following options: !!! 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 might want to have IDE autocompletion, or run your tests suite locally without any emulation like [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html){target="_blank"}. For this to work, you need to install AWS SDK as a development dependency (not as a production 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: -!!! note "A word about dependency resolution" +??? question "Why is that necessary?" + Powertools relies on the AWS SDK being available to use in the target runtime (AWS Lambda). + + 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"}. + +**A word about dependency resolution** In this context, `[aws-sdk]` is an alias to the `boto3` package. Due to dependency resolution, it'll either install: