diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md new file mode 100644 index 00000000000..c1b63e484ad --- /dev/null +++ b/docs/getting-started/install.md @@ -0,0 +1,223 @@ +--- +title: Installation +description: Installing Powertools for AWS Lambda (Python) +--- + + + +## Package manager + +Most features use Python standard library and the AWS SDK _(boto3)_ that are available in the AWS Lambda runtime. + +=== "pip" + + ```bash + pip install "aws-lambda-powertools" + ``` + +=== "poetry" + + ```bash + poetry add "aws-lambda-powertools" + ``` + +=== "pdm" + + ```bash + pdm add "aws-lambda-powertools" + ``` + +=== "uv" + + ```bash + uv add "aws-lambda-powertools" + ``` + +### Extra dependencies + +Some features require additional dependencies. Install them as needed: + +| Feature | Install | Default dependency | +| ------- | ------- | ------------------ | +| [Tracer](../core/tracer.md) | `pip install "aws-lambda-powertools[tracer]"` | `aws-xray-sdk` | +| [Validation](../utilities/validation.md) | `pip install "aws-lambda-powertools[validation]"` | `fastjsonschema` | +| [Parser](../utilities/parser.md) | `pip install "aws-lambda-powertools[parser]"` | `pydantic` | +| [Data Masking](../utilities/data_masking.md) | `pip install "aws-lambda-powertools[datamasking]"` | `aws-encryption-sdk`, `jsonpath-ng` | +| [Datadog Metrics](../core/metrics/datadog.md) | `pip install "aws-lambda-powertools[datadog]"` | `datadog-lambda` | +| [Kafka (Avro)](../utilities/kafka.md) | `pip install "aws-lambda-powertools[kafka-consumer-avro]"` | `avro` | +| [Kafka (Protobuf)](../utilities/kafka.md) | `pip install "aws-lambda-powertools[kafka-consumer-protobuf]"` | `protobuf` | +| Redis | `pip install "aws-lambda-powertools[redis]"` | `redis` | +| Valkey | `pip install "aws-lambda-powertools[valkey]"` | `valkey-glide` | +| All at once | `pip install "aws-lambda-powertools[all]"` | All core extras | + +### Local development + +Powertools for AWS Lambda (Python) relies on the AWS SDK bundled in the Lambda runtime. When developing locally, install the SDK as a dev dependency: + +```bash +pip install "aws-lambda-powertools[aws-sdk]" +``` + +### Alpha releases + +We publish `prerelease` versions to PyPi for early feedback on unstable releases. + +=== "pip" + + ```bash + pip install --pre "aws-lambda-powertools" + ``` + +=== "poetry" + + ```bash + poetry add --allow-prereleases "aws-lambda-powertools" --group dev + ``` + +=== "uv" + + ```bash + uv add --prerelease allow "aws-lambda-powertools" + ``` + +## Lambda Layer + +[Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that contains pre-packaged dependencies. We compile and optimize all dependencies for both x86_64 and ARM architectures. + +Replace `{region}` with your AWS region (e.g., `eu-west-1`) and `{python_version}` without the period (e.g., `python313` for Python 3.13). + +| Architecture | Layer ARN | +| ------------ | --------- | +| x86_64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` | +| ARM64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` | + +### All regional Layer ARNs + +=== "x86_64" + --8<-- "docs/includes/_layer_homepage_x86.md" + +=== "arm64" + --8<-- "docs/includes/_layer_homepage_arm64.md" + +??? tip "Want to inspect the Layer contents?" + ```bash + aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:27 --region eu-west-1 + ``` + The pre-signed URL will be in the `Location` key. + +### Using SSM Parameter Store + +We publish Layer ARNs to SSM Parameter Store for easier automation: + +=== "CloudFormation" + + ```yaml + MyFunction: + Type: AWS::Lambda::Function + Properties: + Layers: + - !Sub "{{resolve:ssm:/aws/service/powertools/python/${Architecture}/${PythonVersion}/latest}}" + ``` + +=== "Terraform" + + ```hcl + data "aws_ssm_parameter" "powertools" { + name = "/aws/service/powertools/python/x86_64/python3.13/latest" + } + + resource "aws_lambda_function" "example" { + layers = [data.aws_ssm_parameter.powertools.value] + } + ``` + +### Infrastructure as Code examples + +=== "SAM" + + ```yaml hl_lines="11" + --8<-- "examples/homepage/install/x86_64/sam.yaml" + ``` + +=== "CDK" + + ```python hl_lines="13 19" + --8<-- "examples/homepage/install/x86_64/cdk_x86.py" + ``` + +=== "Serverless Framework" + + ```yaml hl_lines="13" + --8<-- "examples/homepage/install/x86_64/serverless.yml" + ``` + +=== "Terraform" + + ```terraform hl_lines="9 37" + --8<-- "examples/homepage/install/x86_64/terraform.tf" + ``` + +=== "Pulumi" + + ```python hl_lines="21-27" + --8<-- "examples/homepage/install/x86_64/pulumi_x86.py" + ``` + +### AWS China regions + +| Region | Architecture | Layer ARN | +| ------ | ------------ | --------- | +| cn-north-1 | x86_64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` | +| cn-north-1 | ARM64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` | + +### AWS GovCloud regions + +| Region | Architecture | Layer ARN | +| ------ | ------------ | --------- | +| us-gov-east-1 | x86_64 | `arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` | +| us-gov-east-1 | ARM64 | `arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` | +| us-gov-west-1 | x86_64 | `arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` | +| us-gov-west-1 | ARM64 | `arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` | + +## Serverless Application Repository (SAR) + +SAR deploys a CloudFormation stack with a copy of our Lambda Layer in your account. This allows you to use semantic versioning. + +| Python | Architecture | SAR App | +| ------ | ------------ | ------- | +| 3.10 | x86_64 | [aws-lambda-powertools-python-layer-v3-python310-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-x86-64){target="_blank"} | +| 3.11 | x86_64 | [aws-lambda-powertools-python-layer-v3-python311-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python311-x86-64){target="_blank"} | +| 3.12 | x86_64 | [aws-lambda-powertools-python-layer-v3-python312-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python312-x86-64){target="_blank"} | +| 3.13 | x86_64 | [aws-lambda-powertools-python-layer-v3-python313-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-x86-64){target="_blank"} | +| 3.14 | x86_64 | [aws-lambda-powertools-python-layer-v3-python314-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-x86-64){target="_blank"} | +| 3.10 | ARM64 | [aws-lambda-powertools-python-layer-v3-python310-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-arm64){target="_blank"} | +| 3.11 | ARM64 | [aws-lambda-powertools-python-layer-v3-python311-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python311-arm64){target="_blank"} | +| 3.12 | ARM64 | [aws-lambda-powertools-python-layer-v3-python312-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python312-arm64){target="_blank"} | +| 3.13 | ARM64 | [aws-lambda-powertools-python-layer-v3-python313-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-arm64){target="_blank"} | +| 3.14 | ARM64 | [aws-lambda-powertools-python-layer-v3-python314-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-arm64){target="_blank"} | + +??? note "SAR Infrastructure as Code examples" + + === "SAM" + + ```yaml hl_lines="6 9 10 17-19" + --8<-- "examples/homepage/install/sar/sam.yaml" + ``` + + === "CDK" + + ```python hl_lines="7 16-20 23-27" + --8<-- "examples/homepage/install/sar/cdk_sar.py" + ``` + + === "Terraform" + + ```terraform hl_lines="12-13 15-20 23-25 40" + --8<-- "examples/homepage/install/sar/terraform.tf" + ``` + + ??? question "Need least-privilege IAM permissions?" + + ```yaml hl_lines="21-52" + --8<-- "examples/homepage/install/sar/scoped_down_iam.yaml" + ``` diff --git a/docs/index.md b/docs/index.md index 4f6210235c6..887b35b23fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,476 +7,117 @@ description: Powertools for AWS Lambda (Python) Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity. - +!!! tip "Ready to use Powertools for AWS Lambda? Jump to [Installation](./getting-started/install.md)." +
- :material-battery-charging:{ .lg .middle } __Features__ --- - Adopt one, a few, or all industry practices. **Progressively**. + Adopt one, a few, or all industry practices. __Progressively__. [:octicons-arrow-right-24: All features](#features) -- :heart:{ .lg .middle } __Support this project__ +- :material-download:{ .lg .middle } __Installation__ --- - Become a public reference customer, share your work, contribute, use Lambda Layers, etc. + Install via pip, Lambda Layers, or SAR. - [:octicons-arrow-right-24: Support](#support-powertools-for-aws-lambda-python) + [:octicons-arrow-right-24: Get started](./getting-started/install.md) -- :material-file-code:{ .lg .middle } __Available languages__ +- :heart:{ .lg .middle } __Support this project__ --- - Powertools for AWS Lambda is also available in other languages - - :octicons-arrow-right-24: [Java](https://docs.powertools.aws.dev/lambda/java/){target="_blank"}, [TypeScript](https://docs.powertools.aws.dev/lambda/typescript/latest/){target="_blank" }, and [.NET](https://docs.powertools.aws.dev/lambda/dotnet/){target="_blank"} - -
- -## Install - -You can install Powertools for AWS Lambda (Python) using your favorite dependency management, or Lambda Layers: - -=== "Pip" - - Most features use Python standard library and the AWS SDK _(boto3)_ that are available in the AWS Lambda runtime. - - * **pip**: **`pip install "aws-lambda-powertools"`**{: .copyMe} - * **poetry**: **`poetry add "aws-lambda-powertools"`**{: .copyMe} - * **pdm**: **`pdm add "aws-lambda-powertools"`**{: .copyMe} - * **uv**: **`uv add "aws-lambda-powertools"`**{: .copyMe} - - ### Extra dependencies - - However, you will need additional dependencies if you are using any of the features below: - - | Feature | Install | Default dependency | - | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | - | **[Tracer](./core/tracer.md#install)** | **`pip install "aws-lambda-powertools[tracer]"`**{.copyMe} | `aws-xray-sdk` | - | **[Validation](./utilities/validation.md#install)** | **`pip install "aws-lambda-powertools[validation]"`**{.copyMe} | `fastjsonschema` | - | **[Parser](./utilities/parser.md#install)** | **`pip install "aws-lambda-powertools[parser]"`**{.copyMe} | `pydantic` _(v2)_ | - | **[Data Masking](./utilities/data_masking.md#install)** | **`pip install "aws-lambda-powertools[datamasking]"`**{.copyMe} | `aws-encryption-sdk`, `jsonpath-ng` | - | **All extra dependencies at once** | **`pip install "aws-lambda-powertools[all]"`**{.copyMe} | - | **Two or more extra dependencies only, not all** | **`pip install "aws-lambda-powertools[tracer,parser,datamasking]"`**{.copyMe} | - -=== "Lambda Layer" - - [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. We compile and optimize [all dependencies](#install), and remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/layer_v3/docker/Dockerfile#L34){target="_blank"} to achieve the most optimal size. - - For the latter, make sure to replace `{region}` with your AWS region, e.g., `eu-west-1`, and the `{python_version}` without the period (.), e.g., `python314` for `Python 3.14`. - - | Architecture | Layer ARN | - | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | - | x86_64 | __arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27__{: .copyMe} | - | ARM | __arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27__{: .copyMe} | - - === "AWS Console" - - You can add our layer using the [AWS Lambda Console _(direct link)_](https://console.aws.amazon.com/lambda/home#/add/layer){target="_blank"}: - - * Under Layers, choose `AWS layers` or `Specify an ARN` - * Click to copy the [correct ARN](#lambda-layer) value based on your AWS Lambda function architecture and region - - - === "AWS SSM Parameter Store" - We offer Parameter Store aliases for releases too, allowing you to specify either specific versions or use the latest version on every deploy. To use these you can add these snippets to your AWS CloudFormation or Terraform projects: - - **CloudFormation** - - Sample Placeholders: - - - `{arch}` is either `arm64` (Graviton based functions) or `x86_64` - - `{python_version}` is the Python runtime version, e.g., `python3.14` for `Python 3.14`. - - `{version}` is the semantic version number (e,g. 3.1.0) for a release or `latest` - - ```yaml - MyFunction: - Type: "AWS::Lambda::Function" - Properties: - ... - Layers: - - {{resolve:ssm:/aws/service/powertools/python/{arch}/{python_version}/{version}}} - ``` - - **Terraform** - - Using the [`aws_ssm_parameter`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) data provider from the AWS Terraform provider allows you to lookup the value of parameters to use later in your project. - - ```hcl - data "aws_ssm_parameter" "powertools_version" { - name = "/aws/service/powertools/python/{arch}/{python_version}/{version}" - } - - resource "aws_lambda_function" "test_lambda" { - ... - - runtime = "python3.14" - - layers = [data.aws_ssm_parameter.powertools_version.value] - } - ``` - - === "Infrastructure as Code (IaC)" - - > Are we missing a framework? please create [a documentation request](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&template=documentation_improvements.yml&title=Docs%3A+TITLE){target="_blank" rel="nofollow"}. - - Thanks to the community, we've covered most popular frameworks on how to add a Lambda Layer to an existing function. - - === "x86_64" - - === "SAM" - - ```yaml hl_lines="11" - --8<-- "examples/homepage/install/x86_64/sam.yaml" - ``` - - === "Serverless framework" - - ```yaml hl_lines="13" - --8<-- "examples/homepage/install/x86_64/serverless.yml" - ``` - - === "CDK" - - ```python hl_lines="13 19" - --8<-- "examples/homepage/install/x86_64/cdk_x86.py" - ``` - - === "Terraform" - - ```terraform hl_lines="9 37" - --8<-- "examples/homepage/install/x86_64/terraform.tf" - ``` - - === "Pulumi" - - ```python hl_lines="21-27" - --8<-- "examples/homepage/install/x86_64/pulumi_x86.py" - ``` - - === "Amplify" - - ```zsh hl_lines="9" - --8<-- "examples/homepage/install/x86_64/amplify.txt" - ``` - - === "arm64" - - === "SAM" - - ```yaml hl_lines="12" - --8<-- "examples/homepage/install/arm64/sam.yaml" - ``` - - === "Serverless framework" - - ```yaml hl_lines="13" - --8<-- "examples/homepage/install/arm64/serverless.yml" - ``` - - === "CDK" - - ```python hl_lines="13 19" - --8<-- "examples/homepage/install/arm64/cdk_arm64.py" - ``` - - === "Terraform" - - ```terraform hl_lines="9 37" - --8<-- "examples/homepage/install/arm64/terraform.tf" - ``` - - === "Pulumi" - - ```python hl_lines="21-27" - --8<-- "examples/homepage/install/arm64/pulumi_arm64.py" - ``` - - === "Amplify" - - ```zsh hl_lines="9" - --8<-- "examples/homepage/install/arm64/amplify.txt" - ``` - - === "Inspect Lambda Layer contents" - - You can use AWS CLI to generate a pre-signed URL to download the contents of our Lambda Layer. - - ```bash title="AWS CLI command to download Lambda Layer content" - aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-x86_64:27 --region eu-west-1 - ``` - - You'll find the pre-signed URL under `Location` key as part of the CLI command output. - -=== "Lambda Layer (China)" - - [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. We compile and optimize [all dependencies](#install), and remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/layer_v3/docker/Dockerfile#L34){target="_blank"} to achieve the most optimal size. - - For the latter, make sure to replace `{python_version}` without the period (.), e.g., `python314` for `Python 3.14`. - - **AWS China Beijing (cn-north-1)** - - | Architecture | Layer ARN | - | ------------ | --------------------------------------------------------------------------------------------------------- | - | x86_64 | __arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27__{: .copyMe} | - | ARM | __arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27__{: .copyMe} | - -=== "Lambda Layer (GovCloud)" - - [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. We compile and optimize [all dependencies](#install), and remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/layer_v3/docker/Dockerfile#L34){target="_blank"} to achieve the most optimal size. + Become a public reference, share your work, join the community. - For the latter, make sure to replace `{python_version}` without the period (.), e.g., `python314` for `Python 3.14`. - - **AWS GovCloud (us-gov-east-1)** - - | Architecture | Layer ARN | - | ------------ | --------------------------------------------------------------------------------------------------------- | - | x86_64 | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27__{: .copyMe}:clipboard: | - | ARM | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27__{: .copyMe}:clipboard: | - - **AWS GovCloud (us-gov-west-1)** - - | Architecture | Layer ARN | - | ------------ | --------------------------------------------------------------------------------------------------------- | - | x86_64 | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27__{: .copyMe} | - | ARM | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27__{: .copyMe} | - -=== "Serverless Application Repository (SAR)" - - We provide a SAR App that deploys a CloudFormation stack with a copy of our Lambda Layer in your AWS account and region. - - Compared with the [public Layer ARN](#lambda-layer) option, the advantage is being able to use a semantic version. Make sure to replace `{python_version}` without the period (.), e.g., `python314` for `Python 3.14`. - - | App | ARN | Architecture | - | --- | --- | ------------ | - | aws-lambda-powertools-python-layer-v3-{python_version}-x86-64 | arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-{python_version}-x86-64 | X86_64 | - | aws-lambda-powertools-python-layer-v3-{python_version}-arm64 | arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-{python_version}-arm64 | ARM64 | - - ??? question "Don't have enough permissions? Expand for a least-privilege IAM policy example" - - Credits to [mwarkentin](https://github.com/mwarkentin){target="_blank" rel="nofollow"} for providing the scoped down IAM permissions. - - ```yaml hl_lines="21-52" title="Least-privileged IAM permissions SAM example" - --8<-- "examples/homepage/install/sar/scoped_down_iam.yaml" - ``` - - If you're using Infrastructure as Code, here are some excerpts on how to use SAR: - - === "SAM" - - ```yaml hl_lines="6 9 10 17-19" - --8<-- "examples/homepage/install/sar/sam.yaml" - ``` - - === "Serverless framework" - - ```yaml hl_lines="11 12 19 20" - --8<-- "examples/homepage/install/sar/serverless.yml" - ``` - - === "CDK" - - ```python hl_lines="7 16-20 23-27" - --8<-- "examples/homepage/install/sar/cdk_sar.py" - ``` - - === "Terraform" - - > Credits to [Dani Comnea](https://github.com/DanyC97){target="_blank" rel="nofollow"} for providing the Terraform equivalent. - - ```terraform hl_lines="12-13 15-20 23-25 40" - --8<-- "examples/homepage/install/sar/terraform.tf" - ``` - -=== "Alpha releases" - - We publish `prerelease` versions to PyPi to accelerate customer feedback on **unstable** releases / bugfixes until they become production ready. - - Here's how you can use them: - - - __Pip__: [**`pip install --pre "aws-lambda-powertools"`**](#){: .copyMe} - - __Poetry__: [**`poetry add --allow-prereleases "aws-lambda-powertools" --group dev`**](#){: .copyMe} - - __Pdm__: [**`pdm add -dG --prerelease "aws-lambda-powertools"`**](#){: .copyMe} - - __uv__: [**`uv add --prerelease allow "aws-lambda-powertools"`**](#){: .copyMe} - -### Local development - -!!! info "Using Lambda Layer? Simply add [**`"aws-lambda-powertools[all]"`**](#){: .copyMe} as a development dependency." - -Powertools for AWS Lambda (Python) 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 to support IDE auto-completion and to run your tests locally: - -- __Pip__: [**`pip install "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe} -- __Poetry__: [**`poetry add "aws-lambda-powertools[aws-sdk]" --group dev`**](#){: .copyMe} -- __Pdm__: [**`pdm add -dG "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe} -- __uv__: [**`uv add "aws-lambda-powertools[aws-sdk]"`**](#){: .copyMe} - -__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: - -- __(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 for AWS Lambda (Python) Tracer](core/tracer.md){target="_blank"} - -### Lambda Layer - -[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. We compile and optimize [all dependencies](#install) for Python versions from **3.10 to 3.14**, as well as for both **arm64 and x86_64** architectures, to ensure compatibility. We also remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-layer-cdk/blob/d24716744f7d1f37617b4998c992c4c067e19e64/layer/Python/Dockerfile#L36){target="_blank"} to achieve the most optimal size. - -=== "x86_64" - --8<-- "docs/includes/_layer_homepage_x86.md" - -=== "arm64" - --8<-- "docs/includes/_layer_homepage_arm64.md" - -**Want to inspect the contents of the Layer?** - -The pre-signed URL to download this Lambda Layer will be within `Location` key in the CLI output. The CLI output will also contain the Powertools for AWS Lambda version it contains. - -```bash title="AWS CLI command to download Lambda Layer content" -aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-x86_64:27 --region eu-west-1 -``` - -#### SAR - -Serverless Application Repository (SAR) App deploys a CloudFormation stack with a copy of our Lambda Layer in your AWS account and region. - -Compared with the [public Layer ARN](#lambda-layer) option, SAR allows you to choose a semantic version and deploys a Layer in your target account. - -| App | ARN | Python version | Architecture | -| --- | --- | -------------- | ------------ | -| [aws-lambda-powertools-python-layer-v3-python310-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-x86-64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python310-x86-64](#){: .copyMe} | Python 3.10 | X86_64 | -| [aws-lambda-powertools-python-layer-v3-python311-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python11-x86-64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python311-x86-64](#){: .copyMe} | Python 3.11 | X86_64 | -| [aws-lambda-powertools-python-layer-v3-python312-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python12-x86-64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python312-x86-64](#){: .copyMe} | Python 3.12 | X86_64 | -| [aws-lambda-powertools-python-layer-v3-python313-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-x86-64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python313-x86-64](#){: .copyMe} | Python 3.13 | X86_64 | -| [aws-lambda-powertools-python-layer-v3-python314-x86-64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-x86-64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python314-x86-64](#){: .copyMe} | Python 3.14 | X86_64 | -| [aws-lambda-powertools-python-layer-v3-python310-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python310-arm64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python310-arm64](#){: .copyMe} | Python 3.10 | ARM64 | -| [aws-lambda-powertools-python-layer-v3-python311-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python11-arm64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python311-arm64](#){: .copyMe} | Python 3.11 | ARM64 | -| [aws-lambda-powertools-python-layer-v3-python312-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python12-arm64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python312-arm64](#){: .copyMe} | Python 3.12 | ARM64 | -| [aws-lambda-powertools-python-layer-v3-python313-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python313-arm64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python313-arm64](#){: .copyMe} | Python 3.13 | ARM64 | -| [aws-lambda-powertools-python-layer-v3-python314-arm64](https://serverlessrepo.aws.amazon.com/applications/eu-west-1/057560766410/aws-lambda-powertools-python-layer-v3-python314-arm64){target="_blank"} | [arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer-v3-python314-arm64](#){: .copyMe} | Python 3.14 | ARM64 | - -??? note "Click to expand and copy SAR code snippets for popular frameworks" - - You can create a shared Lambda Layers stack and make this along with other account level layers stack. - - === "SAM" - - ```yaml hl_lines="6 9 10 17-19" - --8<-- "examples/homepage/install/sar/sam.yaml" - ``` - - === "Serverless framework" - - ```yaml hl_lines="11 12 19 20" - --8<-- "examples/homepage/install/sar/serverless.yml" - ``` - - === "CDK" - - ```python hl_lines="8 16-20 23-27" - --8<-- "examples/homepage/install/sar/cdk_sar.py" - ``` + [:octicons-arrow-right-24: Support](#support-powertools-for-aws-lambda-python) - === "Terraform" +- :material-file-code:{ .lg .middle } __Other languages__ - > Credits to [Dani Comnea](https://github.com/DanyC97){target="_blank" rel="nofollow"} for providing the Terraform equivalent. + --- - ```terraform hl_lines="12-13 15-20 23-25 40" - --8<-- "examples/homepage/install/sar/terraform.tf" - ``` + Powertools is also available in other languages. - Credits to [mwarkentin](https://github.com/mwarkentin){target="_blank" rel="nofollow"} for providing the scoped down IAM permissions below. + [:octicons-arrow-right-24: Java](https://docs.powertools.aws.dev/lambda/java/){target="_blank"}, [TypeScript](https://docs.powertools.aws.dev/lambda/typescript/latest/){target="_blank"}, [.NET](https://docs.powertools.aws.dev/lambda/dotnet/){target="_blank"} - ```yaml hl_lines="21-52" title="Least-privileged IAM permissions SAM example" - --8<-- "examples/homepage/install/sar/scoped_down_iam.yaml" - ``` + -## Quick getting started +## Features -```bash title="Hello world example using SAM CLI" -sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.11 --no-tracing +| Utility | Description | +| ------- | ----------- | +| [Tracer](./core/tracer.md) | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions | +| [Logger](./core/logger.md) | Structured logging made easier, and target to enrich structured logging with key Lambda context details | +| [Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) | +| [Event Handler](./core/event_handler/api_gateway.md) | Event handler for API Gateway, ALB, Lambda Function URL, VPC Lattice, AppSync, and Bedrock Agents | +| [Parameters](./utilities/parameters.md) | Retrieve and cache parameter values from Parameter Store, Secrets Manager, AppConfig, or DynamoDB | +| [Parser](./utilities/parser.md) | Data parsing and deep validation using Pydantic | +| [Batch Processing](./utilities/batch.md) | Handle partial failures for SQS, Kinesis Data Streams, and DynamoDB Streams | +| [Idempotency](./utilities/idempotency.md) | Make your Lambda functions idempotent and prevent duplicate execution | +| [Feature Flags](./utilities/feature_flags.md) | A simple rule engine to evaluate when features should be enabled | +| [Validation](./utilities/validation.md) | JSON Schema validator for inbound events and responses | +| [Data Masking](./utilities/data_masking.md) | Protect confidential data with easy removal or encryption | +| [Streaming](./utilities/streaming.md) | Stream datasets larger than available memory | +| [Middleware Factory](./utilities/middleware_factory.md) | Create your own middleware to run logic before and after each Lambda invocation | +| [Typing](./utilities/typing.md) | Static typing classes to speedup development in your IDE | +| [Event Source Data Classes](./utilities/data_classes.md) | Data classes describing the schema of common Lambda event triggers | +| [JMESPath Functions](./utilities/jmespath_functions.md) | Built-in JMESPath functions to deserialize common encoded JSON payloads | +| [Kafka](./utilities/kafka.md) | Deserialize and validate Kafka events with support for Avro, Protocol Buffers, and JSON Schema | + +## Examples + +You can find examples in the [examples directory](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/examples){target="_blank"} and a quick start using SAM CLI: + +```bash +sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.13 --no-tracing ``` -## Features - -Core utilities such as Tracing, Logging, Metrics, and Event Handler will be available across all Powertools for AWS Lambda languages. Additional utilities are subjective to each language ecosystem and customer demand. - -| Utility | Description | -| --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [__Tracing__](./core/tracer.md){target="_blank"} | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions | -| [__Logger__](./core/logger.md){target="_blank"} | Structured logging made easier, and decorator to enrich structured logging with key Lambda context details | -| [__Metrics__](./core/metrics.md){target="_blank"} | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) | -| [__Event handler: AppSync__](./core/event_handler/appsync.md){target="_blank"} | AppSync event handler for Lambda Direct Resolver and Amplify GraphQL Transformer function | -| [__Event handler: API Gateway, ALB and Lambda Function URL__](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/) | Amazon API Gateway REST/HTTP API and ALB event handler for Lambda functions invoked using Proxy integration, and Lambda Function URL | -| [__Middleware factory__](./utilities/middleware_factory.md){target="_blank"} | Decorator factory to create your own middleware to run logic before, and after each Lambda invocation | -| [__Parameters__](./utilities/parameters.md){target="_blank"} | Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time | -| [__Batch processing__](./utilities/batch.md){target="_blank"} | Handle partial failures for AWS SQS batch processing | -| [__Typing__](./utilities/typing.md){target="_blank"} | Static typing classes to speedup development in your IDE | -| [__Validation__](./utilities/validation.md){target="_blank"} | JSON Schema validator for inbound events and responses | -| [__Event source data classes__](./utilities/data_classes.md){target="_blank"} | Data classes describing the schema of common Lambda event triggers | -| [__Parser__](./utilities/parser.md){target="_blank"} | Data parsing and deep validation using Pydantic | -| [__Idempotency__](./utilities/idempotency.md){target="_blank"} | Idempotent Lambda handler | -| [__Data Masking__](./utilities/data_masking.md){target="_blank"} | Protect confidential data with easy removal or encryption | -| [__Feature Flags__](./utilities/feature_flags.md){target="_blank"} | A simple rule engine to evaluate when one or multiple features should be enabled depending on the input | -| [__Streaming__](./utilities/streaming.md){target="_blank"} | Streams datasets larger than the available memory as streaming data. | +For a more complete example, check the [Powertools for AWS workshop](https://catalog.workshops.aws/serverless-powertools){target="_blank"}. ## Environment variables ???+ info - Explicit parameters take precedence over environment variables - -| Environment variable | Description | Utility | Default | -| ----------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------- | -| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"` | -| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics.md){target="_blank"} | `None` | -| **POWERTOOLS_METRICS_FUNCTION_NAME** | Function name used as dimension for the **ColdStart** metric metrics | [Metrics](./core/metrics.md){target="_blank"} | `None` | -| **POWERTOOLS_METRICS_DISABLED** | **Disables** all metrics emitted by Powertools metrics | [Metrics](./core/metrics.md){target="_blank"} | `None` | -| **POWERTOOLS_TRACE_DISABLED** | Explicitly disables tracing | [Tracing](./core/tracer.md){target="_blank"} | `false` | -| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracing](./core/tracer.md){target="_blank"} | `true` | -| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracing](./core/tracer.md){target="_blank"} | `true` | -| **POWERTOOLS_TRACE_MIDDLEWARES** | Creates sub-segment for each custom middleware | [Middleware factory](./utilities/middleware_factory.md){target="_blank"} | `false` | -| **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logging](./core/logger.md){target="_blank"} | `false` | -| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logger.md){target="_blank"} | `0` | -| **POWERTOOLS_LOG_DEDUPLICATION_DISABLED** | Disables log deduplication filter protection to use Pytest Live Log feature | [Logging](./core/logger.md){target="_blank"} | `false` | -| **POWERTOOLS_PARAMETERS_MAX_AGE** | Adjust how long values are kept in cache (in seconds) | [Parameters](./utilities/parameters.md#adjusting-cache-ttl){target="_blank"} | `5` | -| **POWERTOOLS_PARAMETERS_SSM_DECRYPT** | Sets whether to decrypt or not values retrieved from AWS SSM Parameters Store | [Parameters](./utilities/parameters.md#ssmprovider){target="_blank"} | `false` | -| **POWERTOOLS_DEV** | Increases verbosity across utilities | Multiple; see [POWERTOOLS_DEV effect below](#optimizing-for-non-production-environments) | `false` | -| **POWERTOOLS_LOG_LEVEL** | Sets logging level | [Logging](./core/logger.md){target="_blank"} | `INFO` | - -### Optimizing for non-production environments - -!!! info "We will emit a warning when this feature is used to help you detect misuse in production." - -Whether you're prototyping locally or against a non-production environment, you can use `POWERTOOLS_DEV` to increase verbosity across multiple utilities. - -When `POWERTOOLS_DEV` is set to a truthy value (`1`, `true`), it'll have the following effects: - -| Utility | Effect | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| __Logger__ | Increase JSON indentation to 4. This will ease local debugging when running functions locally under emulators or direct calls while not affecting unit tests.

However, Amazon CloudWatch Logs view will degrade as each new line is treated as a new message. | -| __Event Handler__ | Enable full traceback errors in the response, indent request/responses, and CORS in dev mode (`*`). | -| __Tracer__ | Future-proof safety to disables tracing operations in non-Lambda environments. This already happens automatically in the Tracer utility. | -| __Metrics__ | Disables Powertools metrics emission by default.

However, this can be overridden by explicitly setting POWERTOOLS_METRICS_DISABLED=false, which takes precedence over the dev mode setting. | - -## Debug mode - -As a best practice for libraries, Powertools module logging statements are suppressed. - -When necessary, you can use `POWERTOOLS_DEBUG` environment variable to enable debugging. This will provide additional information on every internal operation. + Explicit parameters take precedence over environment variables. + +| Environment variable | Description | Utility | Default | +| -------------------- | ----------- | ------- | ------- | +| `POWERTOOLS_SERVICE_NAME` | Service name for tracing, metrics, and logging | All | `service_undefined` | +| `POWERTOOLS_LOG_LEVEL` | Sets logging level | [Logger](./core/logger.md) | `INFO` | +| `POWERTOOLS_LOGGER_LOG_EVENT` | Logs incoming event | [Logger](./core/logger.md) | `false` | +| `POWERTOOLS_LOGGER_SAMPLE_RATE` | Debug log sampling | [Logger](./core/logger.md) | `0` | +| `POWERTOOLS_METRICS_NAMESPACE` | Namespace for metrics | [Metrics](./core/metrics.md) | `None` | +| `POWERTOOLS_METRICS_DISABLED` | Disables metrics emission | [Metrics](./core/metrics.md) | `false` | +| `POWERTOOLS_TRACE_DISABLED` | Disables tracing | [Tracer](./core/tracer.md) | `false` | +| `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | Captures return as metadata | [Tracer](./core/tracer.md) | `true` | +| `POWERTOOLS_TRACER_CAPTURE_ERROR` | Captures exception as metadata | [Tracer](./core/tracer.md) | `true` | +| `POWERTOOLS_PARAMETERS_MAX_AGE` | Cache TTL in seconds | [Parameters](./utilities/parameters.md) | `5` | +| `POWERTOOLS_PARAMETERS_SSM_DECRYPT` | Decrypt SSM parameters | [Parameters](./utilities/parameters.md) | `false` | +| `POWERTOOLS_DEV` | Increases verbosity for development | Multiple | `false` | +| `POWERTOOLS_DEBUG` | Enables debug logging for Powertools | All | `false` | + +### Development mode + +When `POWERTOOLS_DEV` is set to `true`, it enables development-friendly settings: + +| Utility | Effect | +| ------- | ------ | +| Logger | Increases JSON indentation to 4 for readability | +| Event Handler | Enables full traceback errors and CORS in dev mode | +| Tracer | Disables tracing in non-Lambda environments | +| Metrics | Disables metrics emission (can be overridden) | ## Support Powertools for AWS Lambda (Python) -There are many ways you can help us gain future investments to improve everyone's experience: -
- :heart:{ .lg .middle } __Become a public reference__ --- - Add your company name and logo on our [landing page](https://powertools.aws.dev). + Add your company name and logo on our [landing page](https://powertools.aws.dev){target="_blank"}. [:octicons-arrow-right-24: GitHub Issue template](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E){target="_blank"} @@ -484,7 +125,7 @@ There are many ways you can help us gain future investments to improve everyone' --- - Blog posts, video, and sample projects about Powertools for AWS Lambda. + Blog posts, videos, and sample projects about Powertools. [:octicons-arrow-right-24: GitHub Issue template](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=community-content&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E){target="_blank"} @@ -494,27 +135,17 @@ There are many ways you can help us gain future investments to improve everyone' Connect, ask questions, and share what features you use. - [:octicons-arrow-right-24: Discord invite](https://discord.gg/B8zZKbbyET){target="blank"} + [:octicons-arrow-right-24: Discord invite](https://discord.gg/B8zZKbbyET){target="_blank"}
-### Using Lambda Layers - -!!! note "Layers help us understand who uses Powertools for AWS Lambda (Python) in a non-intrusive way." - - - -When [using Layers](#lambda-layer), you can add Powertools for AWS Lambda (Python) as a dev dependency to not impact the development process. For Layers, we pre-package all dependencies, compile and optimize for storage and both x86_64 and ARM architecture. - - - ## Tenets These are our core principles to guide our decision making. -- __AWS Lambda only__. We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported. +- __AWS Lambda only__. We optimize for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported. - __Eases the adoption of best practices__. The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional. - __Keep it lean__. Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time. - __We strive for backwards compatibility__. New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined. -- __We work backwards from the community__. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs) -- __Progressive__. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community’s common practices. +- __We work backwards from the community__. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs). +- __Progressive__. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community's common practices. diff --git a/mkdocs.yml b/mkdocs.yml index 33393fc01b1..db49e9e45f7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,7 @@ site_url: https://docs.powertools.aws.dev/lambda/python/latest/ nav: - Homepage: - index.md + - Installation: getting-started/install.md - Changelog: changelog.md - Tutorial: tutorial/index.md - Workshop 🆕: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank