Metadata-Version: 2.4
Name: cz-powertools
Version: 0.0.4
Summary: CloudZero wrappers around the routing functionality in AWS powertools (https://github.com/aws-powertools/powertools-lambda-python)
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: aws-lambda-powertools
Requires-Dist: cz-common-python>=8.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: flake8-copyright; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-csv; extra == "dev"
Requires-Dist: pytest-env; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: wheel; extra == "dev"

[![Build and Test All Branches](https://github.com/Cloudzero/cz-powertools-lambda-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Cloudzero/cz-powertools-lambda-python/actions/workflows/ci.yml)


## Project Overview

This project is a CloudZero specific wrapper around AWS Powertools for Lambda. It provides routing and event handlers that provide all the important middleware for CZ handlers. Through using these event handlers and routers, you can have a single lambda handler for multiple API routes. This can help with performance and costs by leveraging provisioned concurrency across multiple API routes.

Additionally, the AWS powertools functionality provides additional functionality:
- Validation of all header, path parameters, query parameters, and input body are done using Pydantic.
- OpenAPI and Swagger support


### Web API

For supporting our public APIs for our frontend, use the following classes:

| Class | Location | Description |
| - | - | - |
| `WebApiGatewayRestResolver` | `czpowertools.event_handler.web_api_event_handler` | This is the main event handler that resolves the event to the different route handlers. |
| `WebApiRouter` | `czpowertools.event_handler.router.web_api_router` | This is a sub-router that adds the `/organizations/<organizationId>` portion of the route and can add additional prefixes for routing for a specific resource type (i.e. for the *recommendations* resource `/organizations/<organizationId>/optimize/recommendations`). |

Here is an [example](examples/web_api/web_api.py) using sub-routers with the `WebApiGatewayRestResolver`. You can see them execute using [these unit tests](tests/unit/web_api_example/test_web_api.py).

All routes added using `WebApiGatewayRestResolver` will get the following functionality:
- Logging context with organization ID/user ID tags
- AWS Tracing
- Organization Path Authorization (ensuring the organization the user is logged in with matches the organization ID in the route path parameter `organizationId`)
- Request Validation (headers, path parameters, query parameters, body)
- Exception/Response handling
- Test Key handling

All routes added using `WebApiRouter` will have the `/organizations/<organizationId>` prefix added to all routes. **NOTE**: If you add routes directly with `WebApiGatewayRestResolver` then you must prefix the path with `/organizations/<organizationId>`.

**NOTE**: All routes added using `WebApiRouter` or `WebApiGatewayRestResolver` must expect to have a path parameter `organizationId`.

### Public/Programmatic API

For supporting our public APIs for our customers, use the following classes:

| Class | Location | Description |
| - | - | - |
| `PublicApiGatewayRestResolver` | `czpowertools.event_handler.public_api_event_handler` | This is the main event handler that resolves the event to the different route handlers. |
| `PublicApiRouter` | `czpowertools.event_handler.router.public_api_router` | This is a sub-router that allows adding prefixes for routing for a specific resource type (i.e. for the *recommendations* resource `/optimize/recommendations`). |

Here is an [example](examples/public_api/public_api.py) using sub-routers with the `PublicApiGatewayRestResolver`. You can see them execute using [these unit tests](tests/unit/public_api_example/test_public_api.py).

All routes added using `PublicApiGatewayRestResolver` will get the following functionality:
- Logging context with organization ID/user ID tags
- AWS Tracing
- Organization Authorization (ensuring the authorization contains the `cz_organization_id` field and adds it to the app context.
- Request Validation (headers, path parameters, query parameters, body)
- Exception/Response handling
- Test Key handling
- Idempotency Support
- Cache Control support.

**NOTE**: Unlike the decorators from `cz-common-python`, the `cz_organization_id` is not added as a parameter to the handler calls as this interferes with parameter validation (it assumes it is a query parameter) as well as OpenApi/Swagger support. Both `PublicApiRouter` and `PublicApiGatewayRestResolver` have a `cz_organization_id` property which will contain the organization ID for the current request.
