lambda-api-decorators-cdk 0.2.3__tar.gz → 0.4.1__tar.gz

lambda_api_decorators_cdk-0.4.1/.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --editable . pytest tomli
+
+      - name: Verify package import
+        run: python -c "import lambda_api_decorators_cdk"
+
+      - name: Run tests
+        run: pytest -q

lambda_api_decorators_cdk-0.4.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: lambda-api-decorators-cdk
+Version: 0.4.1
+Summary: AWS CDK integration for Lambda API Decorators. Generate AWS Lambda and API Gateway infrastructure from decorated Python handlers.
+Author: Mateo Marcos, Emanuel Arguinarena, Lucas Picchi
+License: MIT License
+        
+        Copyright (c) 2024 Lambda API Decorators CDK
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/lambda-api-decorators/lambda-api-decorators-cdk
+Project-URL: Repository, https://github.com/lambda-api-decorators/lambda-api-decorators-cdk
+Project-URL: Bug Reports, https://github.com/lambda-api-decorators/lambda-api-decorators-cdk
+Keywords: cdk,lambda,aws,api gateway,ast
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: AWS CDK :: 2
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aws-cdk.aws-lambda-python-alpha
+Dynamic: license-file
+
+# Lambda API Decorators CDK
+
+AWS CDK integration for [Lambda API Decorators](https://github.com/infrastructure-as-decorator/lambda-api-decorators). Define API routes with Python decorators and let CDK create the Lambda functions, integrations, routes, and related configuration.
+
+The complete cross-package guides and architecture documentation are available at [lambda-api-decorators.github.io](https://infrastructure-as-decorator.github.io/).
+
+## Installation
+
+```bash
+pip install lambda-api-decorators-cdk
+```
+
+The package requires Python 3.10 or newer and AWS CDK v2. The `lambda-api-decorators` package provides the decorators used by the Lambda source files.
+
+## Quick start
+
+`LambdaApi` is the recommended high-level construct. It creates a REST API by default and discovers decorated handlers below `lambda_path`.
+
+```python
+from aws_cdk import Stack
+from constructs import Construct
+
+from lambda_api_decorators_cdk import LambdaApi
+
+
+class ExampleStack(Stack):
+    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
+        super().__init__(scope, construct_id, **kwargs)
+
+        LambdaApi(self, "ExampleApi", lambda_path="lambdas")
+```
+
+A handler must include an HTTP method decorator from `lambda-api-decorators`:
+
+```python
+from lambda_api_decorators import GET
+
+
+@GET("/hello")
+def hello(event, context):
+    return {"statusCode": 200, "body": "Hello, world!"}
+```
+
+`lambda_path` is resolved from the directory where CDK is run. Files without a supported route decorator are ignored.
+
+## API types and imported APIs
+
+REST is the default. Select an HTTP API with `ApiType.HTTP`, or provide an existing supported API and let the construct infer its type.
+
+```python
+from aws_cdk import aws_apigateway as apigateway
+from lambda_api_decorators_cdk import ApiType, LambdaApi
+
+
+LambdaApi(self, "HttpApi", lambda_path="lambdas", api_type=ApiType.HTTP)
+
+existing_rest_api = apigateway.RestApi(self, "ExistingRestApi")
+LambdaApi(self, "ExistingApiRoutes", lambda_path="lambdas", api=existing_rest_api)
+```
+
+Created and imported REST APIs are supported. Concrete `aws_apigatewayv2.HttpApi` instances are supported for HTTP APIs.
+
+## Reusable configuration
+
+Use `LambdaApiConfig` for defaults and named resources shared by one or more `LambdaApi` constructs. Configuration must be complete before constructing the API.
+
+```python
+from aws_cdk import Duration, aws_lambda as lambda_
+from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig
+
+
+config = LambdaApiConfig(
+    runtime=lambda_.Runtime.PYTHON_3_12,
+    timeout=Duration.seconds(30),
+    memory_size=512,
+    environment={"ENVIRONMENT": "production"},
+)
+config.add_custom_environment("PAYMENTS_URL", "https://payments.example.com")
+
+LambdaApi(self, "ConfiguredApi", lambda_path="lambdas", config=config)
+```
+
+`LambdaApiConfig` supports default and custom runtimes, roles, VPCs, subnets, layers, security groups, and environment variables. It also supports registries for DynamoDB tables, S3 buckets, and REST or HTTP authorizers. A reused configuration creates an isolated builder snapshot for each API.
+
+## Source layout and layers
+
+By default, each handler is packaged relative to the source root. For a service-oriented layout, use `SourceLayout.SERVICE`:
+
+```python
+from lambda_api_decorators_cdk import LambdaApi, SourceLayout
+
+
+LambdaApi(
+    self,
+    "ServiceApi",
+    lambda_path="services",
+    source_layout=SourceLayout.SERVICE,
+    layers_path="layers",
+)
+```
+
+When `layers_path` is provided, each visible child directory is treated as a discoverable layer source. Explicit layer configuration remains available through `LambdaApiConfig`.
+
+## Authorization and permissions
+
+Register authorizers with a logical key and select the default authorizer for routes. A handler can override the default with `@authorizer("key")` or make itself public with `@public`.
+
+```python
+from aws_cdk import aws_apigateway as apigateway
+from lambda_api_decorators_cdk import LambdaApiConfig
+
+
+authorizer = apigateway.TokenAuthorizer(self, "UsersAuthorizer", handler=authorizer_fn)
+config = LambdaApiConfig(authorizers={"users": authorizer}, default_authorizer="users")
+```
+
+The resource registries also allow decorated handlers to request least-privilege grants for registered DynamoDB tables and S3 buckets. See the [complete documentation](https://lambda-api-decorators.github.io/) for decorator syntax and supported access levels.
+
+## Low-level builder
+
+`ResourceBuilder` remains a supported lower-level API for callers that need direct control over the API root or build lifecycle:
+
+```python
+from aws_cdk import Duration
+from lambda_api_decorators_cdk import ResourceBuilder
+
+
+builder = ResourceBuilder()
+builder.set_default_timeout(Duration.seconds(30))
+builder.add_common_environment("ENVIRONMENT", "production")
+builder.build(self, rest_api.root, "lambdas")
+```
+
+Prefer `LambdaApi` for new code. It owns API creation or reuse and delegates option resolution to isolated `ResourceBuilder` snapshots.
+
+## Releases
+
+The Git tag is the single source of truth for this package's version. For example, `v0.3.0` produces Python package version `0.3.0`. This repository is versioned independently from `lambda-api-decorators`.
+
+To release from `main`, push a semantic version tag:
+
+```bash
+git checkout main
+git pull
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+Pushing the tag triggers the release workflow, which tests, builds, verifies the version, and publishes to PyPI using trusted publishing. The PyPI project must have a trusted publisher configured for this repository, the `release.yml` workflow, and the `pypi` GitHub environment.

lambda_api_decorators_cdk-0.4.1/README.md

@@ -0,0 +1,149 @@
+# Lambda API Decorators CDK
+
+AWS CDK integration for [Lambda API Decorators](https://github.com/infrastructure-as-decorator/lambda-api-decorators). Define API routes with Python decorators and let CDK create the Lambda functions, integrations, routes, and related configuration.
+
+The complete cross-package guides and architecture documentation are available at [lambda-api-decorators.github.io](https://infrastructure-as-decorator.github.io/).
+
+## Installation
+
+```bash
+pip install lambda-api-decorators-cdk
+```
+
+The package requires Python 3.10 or newer and AWS CDK v2. The `lambda-api-decorators` package provides the decorators used by the Lambda source files.
+
+## Quick start
+
+`LambdaApi` is the recommended high-level construct. It creates a REST API by default and discovers decorated handlers below `lambda_path`.
+
+```python
+from aws_cdk import Stack
+from constructs import Construct
+
+from lambda_api_decorators_cdk import LambdaApi
+
+
+class ExampleStack(Stack):
+    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
+        super().__init__(scope, construct_id, **kwargs)
+
+        LambdaApi(self, "ExampleApi", lambda_path="lambdas")
+```
+
+A handler must include an HTTP method decorator from `lambda-api-decorators`:
+
+```python
+from lambda_api_decorators import GET
+
+
+@GET("/hello")
+def hello(event, context):
+    return {"statusCode": 200, "body": "Hello, world!"}
+```
+
+`lambda_path` is resolved from the directory where CDK is run. Files without a supported route decorator are ignored.
+
+## API types and imported APIs
+
+REST is the default. Select an HTTP API with `ApiType.HTTP`, or provide an existing supported API and let the construct infer its type.
+
+```python
+from aws_cdk import aws_apigateway as apigateway
+from lambda_api_decorators_cdk import ApiType, LambdaApi
+
+
+LambdaApi(self, "HttpApi", lambda_path="lambdas", api_type=ApiType.HTTP)
+
+existing_rest_api = apigateway.RestApi(self, "ExistingRestApi")
+LambdaApi(self, "ExistingApiRoutes", lambda_path="lambdas", api=existing_rest_api)
+```
+
+Created and imported REST APIs are supported. Concrete `aws_apigatewayv2.HttpApi` instances are supported for HTTP APIs.
+
+## Reusable configuration
+
+Use `LambdaApiConfig` for defaults and named resources shared by one or more `LambdaApi` constructs. Configuration must be complete before constructing the API.
+
+```python
+from aws_cdk import Duration, aws_lambda as lambda_
+from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig
+
+
+config = LambdaApiConfig(
+    runtime=lambda_.Runtime.PYTHON_3_12,
+    timeout=Duration.seconds(30),
+    memory_size=512,
+    environment={"ENVIRONMENT": "production"},
+)
+config.add_custom_environment("PAYMENTS_URL", "https://payments.example.com")
+
+LambdaApi(self, "ConfiguredApi", lambda_path="lambdas", config=config)
+```
+
+`LambdaApiConfig` supports default and custom runtimes, roles, VPCs, subnets, layers, security groups, and environment variables. It also supports registries for DynamoDB tables, S3 buckets, and REST or HTTP authorizers. A reused configuration creates an isolated builder snapshot for each API.
+
+## Source layout and layers
+
+By default, each handler is packaged relative to the source root. For a service-oriented layout, use `SourceLayout.SERVICE`:
+
+```python
+from lambda_api_decorators_cdk import LambdaApi, SourceLayout
+
+
+LambdaApi(
+    self,
+    "ServiceApi",
+    lambda_path="services",
+    source_layout=SourceLayout.SERVICE,
+    layers_path="layers",
+)
+```
+
+When `layers_path` is provided, each visible child directory is treated as a discoverable layer source. Explicit layer configuration remains available through `LambdaApiConfig`.
+
+## Authorization and permissions
+
+Register authorizers with a logical key and select the default authorizer for routes. A handler can override the default with `@authorizer("key")` or make itself public with `@public`.
+
+```python
+from aws_cdk import aws_apigateway as apigateway
+from lambda_api_decorators_cdk import LambdaApiConfig
+
+
+authorizer = apigateway.TokenAuthorizer(self, "UsersAuthorizer", handler=authorizer_fn)
+config = LambdaApiConfig(authorizers={"users": authorizer}, default_authorizer="users")
+```
+
+The resource registries also allow decorated handlers to request least-privilege grants for registered DynamoDB tables and S3 buckets. See the [complete documentation](https://lambda-api-decorators.github.io/) for decorator syntax and supported access levels.
+
+## Low-level builder
+
+`ResourceBuilder` remains a supported lower-level API for callers that need direct control over the API root or build lifecycle:
+
+```python
+from aws_cdk import Duration
+from lambda_api_decorators_cdk import ResourceBuilder
+
+
+builder = ResourceBuilder()
+builder.set_default_timeout(Duration.seconds(30))
+builder.add_common_environment("ENVIRONMENT", "production")
+builder.build(self, rest_api.root, "lambdas")
+```
+
+Prefer `LambdaApi` for new code. It owns API creation or reuse and delegates option resolution to isolated `ResourceBuilder` snapshots.
+
+## Releases
+
+The Git tag is the single source of truth for this package's version. For example, `v0.3.0` produces Python package version `0.3.0`. This repository is versioned independently from `lambda-api-decorators`.
+
+To release from `main`, push a semantic version tag:
+
+```bash
+git checkout main
+git pull
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+Pushing the tag triggers the release workflow, which tests, builds, verifies the version, and publishes to PyPI using trusted publishing. The PyPI project must have a trusted publisher configured for this repository, the `release.yml` workflow, and the `pypi` GitHub environment.

{lambda_api_decorators_cdk-0.2.3 → lambda_api_decorators_cdk-0.4.1}/pyproject.toml

@@ -27,7 +27,7 @@ description = "AWS CDK integration for Lambda API Decorators. Generate AWS Lambd
 readme = "README.md"
 
 # https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 
 
 # https://packaging.python.org/en/latest/specifications/core-metadata/#license
@@ -54,10 +54,11 @@ classifiers = [
   'Topic :: Software Development :: Libraries :: Python Modules',
   'Topic :: Software Development :: Build Tools',
   'License :: OSI Approved :: MIT License',
-  'Programming Language :: Python :: 3.9',
   'Programming Language :: Python :: 3.10',
   'Programming Language :: Python :: 3.11',
-  'Programming Language :: Python :: 3.12'
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: 3.14'
 ]
 
 # For an analysis of this field vs pip's requirements files see:

{lambda_api_decorators_cdk-0.2.3 → lambda_api_decorators_cdk-0.4.1}/src/lambda_api_decorators_cdk/ast_helper.py

@@ -256,6 +256,8 @@ def _validate_permission(invocation):
 
 
 def _parse_invocation(decorator):
+    if isinstance(decorator, ast.Name) and decorator.id == "public":
+        return DecoratorInvocation(name="public", args=(), kwargs=())
     if not isinstance(decorator, ast.Call) or not isinstance(decorator.func, ast.Name):
         return None
     name = decorator.func.id
@@ -275,6 +277,12 @@ def _parse_invocation(decorator):
         _validate_grant(invocation, "bucket_name")
     elif name == "permission":
         invocation = _validate_permission(invocation)
+    elif name == "authorizer":
+        if len(invocation.args) != 1 or invocation.kwargs:
+            raise ValueError("authorizer requires exactly one positional key")
+        _require_non_empty_string(invocation.args[0], name, "key")
+    elif name == "public":
+        raise ValueError("public must be used as a bare decorator")
     return invocation
 
 
@@ -301,6 +309,19 @@ def get_file_nodes(parsed_tree, id, directory):
                     is_lambda_http = True
                     paths.append((path, invocation.name))
 
+            auth_invocations = [
+                invocation for invocation in decorator_invocations
+                if invocation.name in ("authorizer", "public")
+            ]
+            if len(auth_invocations) > 1:
+                raise ValueError(
+                    "Conflicting or repeated authentication decorators are not allowed"
+                )
+            if len(paths) > 1 and auth_invocations:
+                raise ValueError(
+                    "Authentication on a handler with multiple routes is ambiguous"
+                )
+
             #ast.FunctionDef ends. If the Function had an HTTP Decorator it means it's a lambda function
             if is_lambda_http: 
                 for key,value in paths:

{lambda_api_decorators_cdk-0.2.3 → lambda_api_decorators_cdk-0.4.1}/src/lambda_api_decorators_cdk/lambda_api_config.py

@@ -27,6 +27,8 @@ class LambdaApiConfig:
         environment: Optional[Mapping[str, str]] = None,
         dynamodb_tables: Optional[Mapping[str, dynamodb.ITable]] = None,
         s3_buckets: Optional[Mapping[str, s3.IBucket]] = None,
+        authorizers: Optional[Mapping[str, object]] = None,
+        default_authorizer: Optional[str] = None,
     ) -> None:
         self._default_runtime = runtime
         self._default_timeout = timeout
@@ -49,10 +51,15 @@ class LambdaApiConfig:
 
         self._dynamodb_tables = {}
         self._s3_buckets = {}
+        self._authorizers = {}
         for key, table in (dynamodb_tables or {}).items():
             self.add_dynamodb_table(key, table)
         for key, bucket in (s3_buckets or {}).items():
             self.add_s3_bucket(key, bucket)
+        for key, authorizer in (authorizers or {}).items():
+            self.add_authorizer(key, authorizer)
+        self._default_authorizer = None
+        self.set_default_authorizer(default_authorizer)
 
     def set_default_runtime(self, runtime: Optional[lambda_.Runtime]) -> None:
         self._default_runtime = runtime
@@ -117,6 +124,35 @@ class LambdaApiConfig:
     def add_s3_bucket(self, key: str, bucket: s3.IBucket) -> None:
         self._add_resource(key, bucket, self._s3_buckets, "S3 bucket")
 
+    def add_authorizer(self, key: str, authorizer: object) -> None:
+        if not isinstance(key, str):
+            raise TypeError("Authorizer registry keys must be strings")
+        if not key.strip():
+            raise ValueError("Authorizer registry keys must not be empty or whitespace")
+        interfaces = getattr(authorizer, "__jsii_ifaces__", ()) if authorizer is not None else ()
+        supported = {
+            "aws_cdk.aws_apigateway.IAuthorizer",
+            "aws_cdk.aws_apigatewayv2.IHttpRouteAuthorizer",
+        }
+        if not any(f"{interface.__module__}.{interface.__name__}" in supported
+                   for interface in interfaces):
+            raise TypeError("Authorizer must be a CDK authorizer object")
+        if key in self._authorizers:
+            raise ValueError(f"Authorizer key {key!r} is already registered")
+        self._authorizers[key] = authorizer
+
+    def set_default_authorizer(self, key: Optional[str]) -> None:
+        if key is None:
+            self._default_authorizer = None
+            return
+        if not isinstance(key, str):
+            raise TypeError("Default authorizer key must be a string or None")
+        if not key.strip():
+            raise ValueError("Default authorizer key must not be empty or whitespace")
+        if key not in self._authorizers:
+            raise KeyError(f"Authorizer key {key!r} is not registered")
+        self._default_authorizer = key
+
     @staticmethod
     def _add_resource(key: str, resource, registry: dict, resource_type: str) -> None:
         if not isinstance(key, str):
@@ -148,4 +184,6 @@ class LambdaApiConfig:
             custom_vpcs=dict(self._custom_vpcs),
             dynamodb_tables=dict(self._dynamodb_tables),
             s3_buckets=dict(self._s3_buckets),
+            authorizers=dict(self._authorizers),
+            default_authorizer=self._default_authorizer,
         )