Skip to content

docs(homepage): revamp install UX & share how we build Lambda Layer #1978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 6, 2023
Merged

docs(homepage): revamp install UX & share how we build Lambda Layer #1978

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d10c5ec
docs(homepage): use new powertools description
heitorlessa Mar 3, 2023
d8b9369
docs(install): revamp UX for install and local development
heitorlessa Mar 3, 2023
299e091
docs(install): make all deps in bold
heitorlessa Mar 3, 2023
233e65b
docs(install): explain how we build our layers along with links
heitorlessa Mar 3, 2023
4ec6738
docs(layer): make aws cli layer command to be more visible
heitorlessa Mar 3, 2023
cf5f71b
docs: shorten local development wording, new banner for those new to …
heitorlessa Mar 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 26 additions & 22 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: AWS Lambda Powertools for Python

<!-- markdownlint-disable MD043 MD013 -->

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"}
Expand All @@ -24,41 +24,49 @@ 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 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):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't we just simply say "However, when developing locally, you need to install AWS SDK as a development dependency (not as a production dependency)"?

I cannot think of any general scenario where developing locally without AWS SDK makes sense. Or maybe you were just enumerating scenarios where having the AWS SDK locally helps, which makes sense too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The latter :) We have a few customers that aren't professional developers, so we try to raise awareness of why doing X could be helpful for the uninitiated.

That said, I'm gonna try another less verbose way to do that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shorten the first part as you suggested, and added a long form under a banner that is folded by default to be less distracting. For anyone wanting to learn more, they can simply click to collapse to know the theory behind it.

image


* **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

???+ 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"
Expand Down Expand Up @@ -448,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.
Expand Down