From 6029bd40a0260bba94f2f18926ad179069a69423 Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Sun, 15 Nov 2026 14:07:10 +0000 Subject: [PATCH 1/2] feat(auth): graduate the Auth utility from auth_alpha to auth --- .../references/auth-jwt-oauth2.md | 42 ++++++------- .../references/idempotency.md | 4 ++ .../utilities/auth/__init__.py | 32 ++++++++++ .../_internal/__init__.py | 0 .../_internal/deadline.py | 2 +- .../{auth_alpha => auth}/_internal/errors.py | 2 +- .../{auth_alpha => auth}/_internal/http.py | 4 +- .../{auth_alpha => auth}/_internal/scopes.py | 2 +- .../_internal/transport.py | 4 +- .../_internal/validation.py | 0 .../{auth_alpha => auth}/exceptions.py | 0 .../{auth_alpha => auth}/jwt/__init__.py | 6 +- .../jwt/_internal/__init__.py | 0 .../jwt/_internal/authorization.py | 4 +- .../jwt/_internal/base.py | 12 ++-- .../utilities/auth/jwt/_internal/errors.py | 3 + .../jwt/_internal/jwks.py | 8 +-- .../{auth_alpha => auth}/jwt/exceptions.py | 2 +- .../jwt/integrations/__init__.py | 0 .../jwt/integrations/api_gateway.py | 8 +-- .../jwt/integrations/event_handler.py | 6 +- .../{auth_alpha => auth}/jwt/testing.py | 2 +- .../{auth_alpha => auth}/jwt/verifier.py | 12 ++-- .../{auth_alpha => auth}/oauth2/__init__.py | 2 +- .../{auth_alpha => auth}/oauth2/client.py | 12 ++-- .../{auth_alpha => auth}/oauth2/exceptions.py | 2 +- .../utilities/auth_alpha/__init__.py | 60 ++++++++++++------- .../auth_alpha/jwt/_internal/errors.py | 3 - docs/api_doc/auth.md | 9 +++ docs/api_doc/auth_alpha.md | 9 --- docs/utilities/auth.md | 28 ++++----- docs/utilities/oauth2.md | 17 +++--- .../jwt/src/authorizer/authorizer.py | 4 +- .../jwt/src/authorizer/requirements.txt | 0 .../jwt/src/backend/backend.py | 0 .../jwt/src/backend/requirements.txt | 0 .../{auth_alpha => auth}/jwt/src/basic.py | 2 +- .../{auth_alpha => auth}/jwt/src/cognito.py | 2 +- .../jwt/src/custom_authorization.py | 2 +- .../{auth_alpha => auth}/jwt/src/direct.py | 4 +- .../jwt/src/middleware.py | 2 +- .../{auth_alpha => auth}/jwt/src/prefetch.py | 2 +- .../jwt/templates/sam.yaml | 0 .../jwt/tests/test_middleware.py | 2 +- .../oauth2/src/client_credentials.py | 2 +- .../oauth2/src/client_secret_post.py | 2 +- .../oauth2/src/diagnostics.py | 4 +- .../oauth2/src/headers.py | 2 +- .../oauth2/tests/test_client_credentials.py | 0 .../oauth2/tests/test_client_secret_post.py | 0 .../tests/test_documented_configuration.py | 4 +- .../oauth2/tests/test_headers.py | 2 +- mkdocs.yml | 2 +- noxfile.py | 4 +- .../{auth_alpha => auth}/__init__.py | 0 .../{auth_alpha => auth}/conftest.py | 0 .../{auth_alpha => auth}/jwt/__init__.py | 0 .../{auth_alpha => auth}/jwt/conftest.py | 2 +- .../jwt/imports/__init__.py | 0 .../jwt/imports/_auth_import_probe.py | 12 ++-- .../jwt/imports/test_imports.py | 0 .../jwt/integrations/__init__.py | 0 .../jwt/integrations/test_authorizer.py | 4 +- .../integrations/test_failure_visibility.py | 4 +- .../jwt/integrations/test_middleware.py | 2 +- .../{auth_alpha => auth}/jwt/test_errors.py | 4 +- .../jwt/test_jwks_cache.py | 4 +- .../{auth_alpha => auth}/jwt/test_profiles.py | 4 +- .../{auth_alpha => auth}/jwt/test_testing.py | 6 +- .../jwt/test_token_profile.py | 4 +- .../{auth_alpha => auth}/jwt/test_verifier.py | 4 +- .../{auth_alpha => auth}/oauth2/__init__.py | 0 .../oauth2/test_auth_methods.py | 4 +- .../oauth2/test_client.py | 4 +- .../oauth2/test_errors.py | 10 ++-- .../oauth2/test_imports.py | 4 +- .../functional/auth/test_auth_alpha_alias.py | 35 +++++++++++ .../{auth_alpha => auth}/conftest.py | 0 .../{auth_alpha => auth}/jwt/test_https.py | 4 +- .../{auth_alpha => auth}/oauth2/__init__.py | 0 .../{auth_alpha => auth}/oauth2/test_https.py | 4 +- .../oauth2/test_provider_contracts.py | 4 +- 82 files changed, 271 insertions(+), 187 deletions(-) create mode 100644 aws_lambda_powertools/utilities/auth/__init__.py rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/__init__.py (100%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/deadline.py (88%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/errors.py (91%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/http.py (96%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/scopes.py (84%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/transport.py (94%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/_internal/validation.py (100%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/exceptions.py (100%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/__init__.py (71%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/_internal/__init__.py (100%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/_internal/authorization.py (93%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/_internal/base.py (89%) create mode 100644 aws_lambda_powertools/utilities/auth/jwt/_internal/errors.py rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/_internal/jwks.py (93%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/exceptions.py (92%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/integrations/__init__.py (100%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/integrations/api_gateway.py (93%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/integrations/event_handler.py (93%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/testing.py (91%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/jwt/verifier.py (96%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/oauth2/__init__.py (84%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/oauth2/client.py (96%) rename aws_lambda_powertools/utilities/{auth_alpha => auth}/oauth2/exceptions.py (91%) delete mode 100644 aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/errors.py create mode 100644 docs/api_doc/auth.md delete mode 100644 docs/api_doc/auth_alpha.md rename examples/{auth_alpha => auth}/jwt/src/authorizer/authorizer.py (87%) rename examples/{auth_alpha => auth}/jwt/src/authorizer/requirements.txt (100%) rename examples/{auth_alpha => auth}/jwt/src/backend/backend.py (100%) rename examples/{auth_alpha => auth}/jwt/src/backend/requirements.txt (100%) rename examples/{auth_alpha => auth}/jwt/src/basic.py (88%) rename examples/{auth_alpha => auth}/jwt/src/cognito.py (90%) rename examples/{auth_alpha => auth}/jwt/src/custom_authorization.py (93%) rename examples/{auth_alpha => auth}/jwt/src/direct.py (86%) rename examples/{auth_alpha => auth}/jwt/src/middleware.py (91%) rename examples/{auth_alpha => auth}/jwt/src/prefetch.py (88%) rename examples/{auth_alpha => auth}/jwt/templates/sam.yaml (100%) rename examples/{auth_alpha => auth}/jwt/tests/test_middleware.py (91%) rename examples/{auth_alpha => auth}/oauth2/src/client_credentials.py (94%) rename examples/{auth_alpha => auth}/oauth2/src/client_secret_post.py (92%) rename examples/{auth_alpha => auth}/oauth2/src/diagnostics.py (86%) rename examples/{auth_alpha => auth}/oauth2/src/headers.py (94%) rename examples/{auth_alpha => auth}/oauth2/tests/test_client_credentials.py (100%) rename examples/{auth_alpha => auth}/oauth2/tests/test_client_secret_post.py (100%) rename examples/{auth_alpha => auth}/oauth2/tests/test_documented_configuration.py (96%) rename examples/{auth_alpha => auth}/oauth2/tests/test_headers.py (97%) rename tests/functional/{auth_alpha => auth}/__init__.py (100%) rename tests/functional/{auth_alpha => auth}/conftest.py (100%) rename tests/functional/{auth_alpha => auth}/jwt/__init__.py (100%) rename tests/functional/{auth_alpha => auth}/jwt/conftest.py (93%) rename tests/functional/{auth_alpha => auth}/jwt/imports/__init__.py (100%) rename tests/functional/{auth_alpha => auth}/jwt/imports/_auth_import_probe.py (88%) rename tests/functional/{auth_alpha => auth}/jwt/imports/test_imports.py (100%) rename tests/functional/{auth_alpha => auth}/jwt/integrations/__init__.py (100%) rename tests/functional/{auth_alpha => auth}/jwt/integrations/test_authorizer.py (98%) rename tests/functional/{auth_alpha => auth}/jwt/integrations/test_failure_visibility.py (96%) rename tests/functional/{auth_alpha => auth}/jwt/integrations/test_middleware.py (99%) rename tests/functional/{auth_alpha => auth}/jwt/test_errors.py (96%) rename tests/functional/{auth_alpha => auth}/jwt/test_jwks_cache.py (98%) rename tests/functional/{auth_alpha => auth}/jwt/test_profiles.py (97%) rename tests/functional/{auth_alpha => auth}/jwt/test_testing.py (81%) rename tests/functional/{auth_alpha => auth}/jwt/test_token_profile.py (96%) rename tests/functional/{auth_alpha => auth}/jwt/test_verifier.py (98%) rename tests/functional/{auth_alpha => auth}/oauth2/__init__.py (100%) rename tests/functional/{auth_alpha => auth}/oauth2/test_auth_methods.py (96%) rename tests/functional/{auth_alpha => auth}/oauth2/test_client.py (99%) rename tests/functional/{auth_alpha => auth}/oauth2/test_errors.py (89%) rename tests/functional/{auth_alpha => auth}/oauth2/test_imports.py (91%) create mode 100644 tests/functional/auth/test_auth_alpha_alias.py rename tests/integration/{auth_alpha => auth}/conftest.py (100%) rename tests/integration/{auth_alpha => auth}/jwt/test_https.py (95%) rename tests/integration/{auth_alpha => auth}/oauth2/__init__.py (100%) rename tests/integration/{auth_alpha => auth}/oauth2/test_https.py (98%) rename tests/integration/{auth_alpha => auth}/oauth2/test_provider_contracts.py (98%) diff --git a/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md b/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md index 827ec213a38..8503ad61907 100644 --- a/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md +++ b/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md @@ -3,13 +3,13 @@ Source of truth: https://docs.powertools.aws.dev/lambda/python/latest/utilities/auth/, https://docs.powertools.aws.dev/lambda/python/latest/utilities/oauth2/ -> **Warning: Alpha / experimental** +Auth verifies JWT access tokens in any Lambda workload. Use `verify()` directly, create Event Handler middleware with `require()`, or build a Lambda authorizer response with `authorize()`. -This utility ships under the `auth_alpha` namespace while we collect feedback. Its public API may change before GA. Pin your Powertools version before using it in production. +For client-credentials tokens used to call a downstream API, see [OAuth2 client](oauth2.md). -Auth verifies JWT access tokens in any Lambda workload. Use `verify()` directly, create Event Handler middleware with `require()`, or build a Lambda authorizer response with `authorize()`. +> **Note: Coming from `auth_alpha`?** -For client-credentials tokens used to call a downstream API, see [OAuth2 client (alpha)](oauth2.md). +Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0. That import path still works and emits a `PowertoolsDeprecationWarning`; it goes away in v4. Change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. ```mermaid flowchart LR @@ -63,7 +63,7 @@ Create the verifier outside the Lambda handler so warm invocations reuse its sig ```python title="basic.py" import os -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext verifier = JWTVerifier( @@ -109,7 +109,7 @@ Static `jwks` avoids network access, but your application must rotate those keys import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() @@ -155,8 +155,8 @@ Without middleware, pass the complete `Authorization` header to `verify_authoriz import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidTokenError, JWKSFetchError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidTokenError, JWKSFetchError from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() @@ -202,7 +202,7 @@ import os from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response -from aws_lambda_powertools.utilities.auth_alpha import AuthErrorContext, JWTVerifier +from aws_lambda_powertools.utilities.auth import AuthErrorContext, JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() @@ -269,7 +269,7 @@ Call `prefetch()` after constructing the verifier to retrieve keys during Lambda ```python title="prefetch.py" import os -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext verifier = JWTVerifier( @@ -299,7 +299,7 @@ Use the Cognito profile for resource-bound Cognito access tokens: import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() @@ -329,8 +329,8 @@ Use `authorize()` when API Gateway invokes a dedicated Lambda authorizer: import os from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError from aws_lambda_powertools.utilities.typing import LambdaContext logger = Logger() @@ -482,10 +482,6 @@ Keep it disabled when every request must respect token expiration. Gateway cachi Log `reason.value` and `retryable`, not exception messages, tokens, claims, or request headers. `retryable=true` means a later attempt might succeed after provider recovery. -> **Warning: Alpha / experimental** - -This utility ships under the `auth_alpha` namespace while we collect feedback. Its public API may change before GA. Pin your Powertools version before using it in production. - `OAuth2Client` obtains bearer tokens for a Lambda function calling an API on its own behalf. It uses the client-credentials grant with `client_secret_basic` (default) or explicit `client_secret_post` authentication. @@ -554,7 +550,7 @@ from urllib.parse import quote from botocore.config import Config from aws_lambda_powertools.utilities import parameters -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext secrets = parameters.SecretsProvider( @@ -630,7 +626,7 @@ This example uses `CLIENT_SECRET` instead of `CLIENT_SECRET_NAME` and calls `INV ```python title="client_secret_post.py" import os -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext # Create outside the handler so warm invocations can reuse the token cache. @@ -704,7 +700,7 @@ from urllib.parse import quote, urlsplit import urllib3 -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext INVENTORY_URL = os.environ["INVENTORY_URL"] @@ -809,7 +805,7 @@ Use configured, trusted URLs, never caller-controlled destinations. `request()` ### Errors and diagnostics -OAuth errors inherit from `AuthError` in `auth_alpha.exceptions`. +OAuth errors inherit from `AuthError` in `auth.exceptions`. | Exception | Reason | Retryable | | --------- | ------ | --------- | @@ -827,8 +823,8 @@ import os from urllib.parse import quote from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError from aws_lambda_powertools.utilities.typing import LambdaContext logger = Logger() diff --git a/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md b/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md index a6f47911eb9..b540d0e55db 100644 --- a/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md +++ b/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md @@ -1939,6 +1939,10 @@ You can override and further extend idempotency behavior via **`IdempotencyConfi | **hash_function** | `md5` | Function to use for calculating hashes, as provided by [hashlib](https://docs.python.org/3/library/hashlib.html) in the standard library. | | **response_hook** | `None` | Function to use for processing the stored Idempotent response. This function hook is called when an existing idempotent response is found. See [Manipulating The Idempotent Response](idempotency.md#manipulating-the-idempotent-response) | +> **Warning: Use one persistence layer instance per `IdempotencyConfig`** + +A persistence layer applies the settings of the first `IdempotencyConfig` it is used with. If functions with different configs share the same persistence layer instance, the later ones use the first config's settings, and we emit a `PowertoolsUserWarning`. + ### Handling concurrent executions with the same payload This utility will raise an **`IdempotencyAlreadyInProgressError`** exception if you receive **multiple invocations with the same payload while the first invocation hasn't completed yet**. diff --git a/aws_lambda_powertools/utilities/auth/__init__.py b/aws_lambda_powertools/utilities/auth/__init__.py new file mode 100644 index 00000000000..decde3bff17 --- /dev/null +++ b/aws_lambda_powertools/utilities/auth/__init__.py @@ -0,0 +1,32 @@ +"""Authentication and authorization utilities for AWS Lambda.""" + +from __future__ import annotations + +import importlib +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from aws_lambda_powertools.utilities.auth.exceptions import AuthFailureReason as AuthFailureReason + from aws_lambda_powertools.utilities.auth.jwt import AuthErrorContext as AuthErrorContext + from aws_lambda_powertools.utilities.auth.jwt import JWTVerifier as JWTVerifier + from aws_lambda_powertools.utilities.auth.oauth2 import OAuth2Client as OAuth2Client + +__all__ = ["AuthErrorContext", "AuthFailureReason", "JWTVerifier", "OAuth2Client"] + + +def __getattr__(name: str) -> object: + modules = { + "AuthErrorContext": "jwt", + "AuthFailureReason": "exceptions", + "JWTVerifier": "jwt", + "OAuth2Client": "oauth2", + } + if name in modules: + value = getattr(importlib.import_module(f"{__name__}.{modules[name]}"), name) + globals()[name] = value + return value + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + +def __dir__() -> list[str]: + return sorted(set(globals()) | set(__all__)) diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/__init__.py b/aws_lambda_powertools/utilities/auth/_internal/__init__.py similarity index 100% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/__init__.py rename to aws_lambda_powertools/utilities/auth/_internal/__init__.py diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/deadline.py b/aws_lambda_powertools/utilities/auth/_internal/deadline.py similarity index 88% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/deadline.py rename to aws_lambda_powertools/utilities/auth/_internal/deadline.py index 80422adcd7a..1db19e6dea7 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/_internal/deadline.py +++ b/aws_lambda_powertools/utilities/auth/_internal/deadline.py @@ -2,7 +2,7 @@ import time -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import finite_seconds +from aws_lambda_powertools.utilities.auth._internal.validation import finite_seconds class RequestError(Exception): diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/errors.py b/aws_lambda_powertools/utilities/auth/_internal/errors.py similarity index 91% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/errors.py rename to aws_lambda_powertools/utilities/auth/_internal/errors.py index 89e0f2de078..9bbcacb75c7 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/_internal/errors.py +++ b/aws_lambda_powertools/utilities/auth/_internal/errors.py @@ -3,7 +3,7 @@ from functools import wraps from typing import TYPE_CHECKING, ParamSpec, TypeVar -from aws_lambda_powertools.utilities.auth_alpha.exceptions import AuthError +from aws_lambda_powertools.utilities.auth.exceptions import AuthError if TYPE_CHECKING: from collections.abc import Callable diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/http.py b/aws_lambda_powertools/utilities/auth/_internal/http.py similarity index 96% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/http.py rename to aws_lambda_powertools/utilities/auth/_internal/http.py index b7577d24ed1..1b1d0a8f997 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/_internal/http.py +++ b/aws_lambda_powertools/utilities/auth/_internal/http.py @@ -7,8 +7,8 @@ import urllib3 from urllib3.poolmanager import pool_classes_by_scheme -from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import Deadline, RequestError -from aws_lambda_powertools.utilities.auth_alpha._internal.transport import ( +from aws_lambda_powertools.utilities.auth._internal.deadline import Deadline, RequestError +from aws_lambda_powertools.utilities.auth._internal.transport import ( DeadlineHTTPSConnectionPool, response_deadline, ) diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/scopes.py b/aws_lambda_powertools/utilities/auth/_internal/scopes.py similarity index 84% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/scopes.py rename to aws_lambda_powertools/utilities/auth/_internal/scopes.py index d80e0901f29..ff7f0dc20ca 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/_internal/scopes.py +++ b/aws_lambda_powertools/utilities/auth/_internal/scopes.py @@ -1,6 +1,6 @@ from __future__ import annotations -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import string_list +from aws_lambda_powertools.utilities.auth._internal.validation import string_list def valid_scope(value: str) -> bool: diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/transport.py b/aws_lambda_powertools/utilities/auth/_internal/transport.py similarity index 94% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/transport.py rename to aws_lambda_powertools/utilities/auth/_internal/transport.py index 6620025eb62..710d52d956e 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/_internal/transport.py +++ b/aws_lambda_powertools/utilities/auth/_internal/transport.py @@ -11,7 +11,7 @@ from urllib3.exceptions import HeaderParsingError from urllib3.util.response import assert_header_parsing -from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import RequestError +from aws_lambda_powertools.utilities.auth._internal.deadline import RequestError if TYPE_CHECKING: from collections.abc import Iterator @@ -20,7 +20,7 @@ from typing_extensions import Buffer - from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import Deadline + from aws_lambda_powertools.utilities.auth._internal.deadline import Deadline class _ResponseStream(Protocol): def readinto1(self, buffer: Buffer, /) -> int: ... diff --git a/aws_lambda_powertools/utilities/auth_alpha/_internal/validation.py b/aws_lambda_powertools/utilities/auth/_internal/validation.py similarity index 100% rename from aws_lambda_powertools/utilities/auth_alpha/_internal/validation.py rename to aws_lambda_powertools/utilities/auth/_internal/validation.py diff --git a/aws_lambda_powertools/utilities/auth_alpha/exceptions.py b/aws_lambda_powertools/utilities/auth/exceptions.py similarity index 100% rename from aws_lambda_powertools/utilities/auth_alpha/exceptions.py rename to aws_lambda_powertools/utilities/auth/exceptions.py diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/__init__.py b/aws_lambda_powertools/utilities/auth/jwt/__init__.py similarity index 71% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/__init__.py rename to aws_lambda_powertools/utilities/auth/jwt/__init__.py index c870ae1cf19..a1ddeef67d2 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/__init__.py +++ b/aws_lambda_powertools/utilities/auth/jwt/__init__.py @@ -6,11 +6,11 @@ from typing import TYPE_CHECKING if TYPE_CHECKING: - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthFailureReason as AuthFailureReason - from aws_lambda_powertools.utilities.auth_alpha.jwt.integrations.event_handler import ( + from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthFailureReason as AuthFailureReason + from aws_lambda_powertools.utilities.auth.jwt.integrations.event_handler import ( AuthErrorContext as AuthErrorContext, ) - from aws_lambda_powertools.utilities.auth_alpha.jwt.verifier import JWTVerifier as JWTVerifier + from aws_lambda_powertools.utilities.auth.jwt.verifier import JWTVerifier as JWTVerifier __all__ = ["AuthErrorContext", "AuthFailureReason", "JWTVerifier"] diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/__init__.py b/aws_lambda_powertools/utilities/auth/jwt/_internal/__init__.py similarity index 100% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/__init__.py rename to aws_lambda_powertools/utilities/auth/jwt/_internal/__init__.py diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/authorization.py b/aws_lambda_powertools/utilities/auth/jwt/_internal/authorization.py similarity index 93% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/authorization.py rename to aws_lambda_powertools/utilities/auth/jwt/_internal/authorization.py index 6732104425e..5dee3e8dedf 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/authorization.py +++ b/aws_lambda_powertools/utilities/auth/jwt/_internal/authorization.py @@ -3,8 +3,8 @@ from collections.abc import Mapping from typing import Any -from aws_lambda_powertools.utilities.auth_alpha._internal.scopes import required_scopes, valid_scope -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import ( +from aws_lambda_powertools.utilities.auth._internal.scopes import required_scopes, valid_scope +from aws_lambda_powertools.utilities.auth.jwt.exceptions import ( AuthError, AuthFailureReason, InvalidClaimsError, diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/base.py b/aws_lambda_powertools/utilities/auth/jwt/_internal/base.py similarity index 89% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/base.py rename to aws_lambda_powertools/utilities/auth/jwt/_internal/base.py index 799220119e2..260019e5754 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/base.py +++ b/aws_lambda_powertools/utilities/auth/jwt/_internal/base.py @@ -3,14 +3,14 @@ from abc import ABC, abstractmethod from typing import TYPE_CHECKING, Any, Literal -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.errors import sanitize_errors +from aws_lambda_powertools.utilities.auth.jwt._internal.errors import sanitize_errors if TYPE_CHECKING: from collections.abc import Callable from aws_lambda_powertools.event_handler import Response - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError - from aws_lambda_powertools.utilities.auth_alpha.jwt.integrations.event_handler import ( + from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError + from aws_lambda_powertools.utilities.auth.jwt.integrations.event_handler import ( AuthErrorContext, AuthMiddleware, ) @@ -55,7 +55,7 @@ def verify_authorization_header(self, value: str | None) -> dict[str, Any]: claims = verifier.verify_authorization_header(authorization) ``` """ - from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.authorization import bearer_token + from aws_lambda_powertools.utilities.auth.jwt._internal.authorization import bearer_token return self.verify(bearer_token(value)) @@ -97,7 +97,7 @@ def orders(): return {"subject": app.context["claims"]["sub"]} ``` """ - from aws_lambda_powertools.utilities.auth_alpha.jwt.integrations.event_handler import AuthMiddleware + from aws_lambda_powertools.utilities.auth.jwt.integrations.event_handler import AuthMiddleware return AuthMiddleware(self, scopes, authorize, on_error) @@ -142,6 +142,6 @@ def authorize( ) ``` """ - from aws_lambda_powertools.utilities.auth_alpha.jwt.integrations.api_gateway import authorize_event + from aws_lambda_powertools.utilities.auth.jwt.integrations.api_gateway import authorize_event return authorize_event(self, event, scopes, response_format, context_claims, on_error) diff --git a/aws_lambda_powertools/utilities/auth/jwt/_internal/errors.py b/aws_lambda_powertools/utilities/auth/jwt/_internal/errors.py new file mode 100644 index 00000000000..6717c1d7640 --- /dev/null +++ b/aws_lambda_powertools/utilities/auth/jwt/_internal/errors.py @@ -0,0 +1,3 @@ +from aws_lambda_powertools.utilities.auth._internal.errors import sanitize_errors + +__all__ = ["sanitize_errors"] diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/jwks.py b/aws_lambda_powertools/utilities/auth/jwt/_internal/jwks.py similarity index 93% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/jwks.py rename to aws_lambda_powertools/utilities/auth/jwt/_internal/jwks.py index 9171c354ac4..c544f4dc66d 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/jwks.py +++ b/aws_lambda_powertools/utilities/auth/jwt/_internal/jwks.py @@ -8,9 +8,9 @@ import jwt -from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import Deadline, RequestError -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import https_url -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidTokenError, JWKSFetchError +from aws_lambda_powertools.utilities.auth._internal.deadline import Deadline, RequestError +from aws_lambda_powertools.utilities.auth._internal.validation import https_url +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidTokenError, JWKSFetchError def copy_key_set(value: dict[str, Any]) -> dict[str, Any]: @@ -46,7 +46,7 @@ class JWKSCache: """A key-set snapshot whose maximum age is independent of miss throttling.""" def __init__(self, issuer: str, uri: str | None, max_age: float, cooldown: float) -> None: - from aws_lambda_powertools.utilities.auth_alpha._internal.http import HTTPClient + from aws_lambda_powertools.utilities.auth._internal.http import HTTPClient self._issuer = issuer self._uri = uri diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/exceptions.py b/aws_lambda_powertools/utilities/auth/jwt/exceptions.py similarity index 92% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/exceptions.py rename to aws_lambda_powertools/utilities/auth/jwt/exceptions.py index 03f2044f302..e7fb8c4f1b1 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/exceptions.py +++ b/aws_lambda_powertools/utilities/auth/jwt/exceptions.py @@ -1,6 +1,6 @@ """Credential-free errors raised by JWT verification.""" -from aws_lambda_powertools.utilities.auth_alpha.exceptions import AuthError, AuthFailureReason +from aws_lambda_powertools.utilities.auth.exceptions import AuthError, AuthFailureReason __all__ = [ "AuthError", diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/__init__.py b/aws_lambda_powertools/utilities/auth/jwt/integrations/__init__.py similarity index 100% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/__init__.py rename to aws_lambda_powertools/utilities/auth/jwt/integrations/__init__.py diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/api_gateway.py b/aws_lambda_powertools/utilities/auth/jwt/integrations/api_gateway.py similarity index 93% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/api_gateway.py rename to aws_lambda_powertools/utilities/auth/jwt/integrations/api_gateway.py index 39a03730931..25fb3edf31c 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/api_gateway.py +++ b/aws_lambda_powertools/utilities/auth/jwt/integrations/api_gateway.py @@ -4,22 +4,22 @@ import re from typing import TYPE_CHECKING, Any, Literal -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import string_list -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.authorization import ( +from aws_lambda_powertools.utilities.auth._internal.validation import string_list +from aws_lambda_powertools.utilities.auth.jwt._internal.authorization import ( ForbiddenError, bearer_token, enforce_scopes, header_token, required_scopes, ) -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError, InvalidClaimsError, InvalidTokenError +from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError, InvalidClaimsError, InvalidTokenError from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import APIGatewayAuthorizerResponseV2 from aws_lambda_powertools.utilities.data_classes.common import DictWrapper if TYPE_CHECKING: from collections.abc import Callable - from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.base import Verifier + from aws_lambda_powertools.utilities.auth.jwt._internal.base import Verifier _ARN = re.compile(r"arn:[a-z0-9-]+:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+/[^/]+/[A-Z]+/.*") diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/event_handler.py b/aws_lambda_powertools/utilities/auth/jwt/integrations/event_handler.py similarity index 93% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/event_handler.py rename to aws_lambda_powertools/utilities/auth/jwt/integrations/event_handler.py index 01c74137681..4c7391c16e6 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/integrations/event_handler.py +++ b/aws_lambda_powertools/utilities/auth/jwt/integrations/event_handler.py @@ -5,7 +5,7 @@ from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.authorization import ( +from aws_lambda_powertools.utilities.auth.jwt._internal.authorization import ( ForbiddenError, InsufficientScopeError, MissingTokenError, @@ -13,14 +13,14 @@ header_token, required_scopes, ) -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError, AuthFailureReason, InvalidTokenError +from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError, AuthFailureReason, InvalidTokenError if TYPE_CHECKING: from collections.abc import Callable from typing import Any from aws_lambda_powertools.event_handler.middlewares import NextMiddleware - from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.base import Verifier + from aws_lambda_powertools.utilities.auth.jwt._internal.base import Verifier @dataclass(frozen=True) diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/testing.py b/aws_lambda_powertools/utilities/auth/jwt/testing.py similarity index 91% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/testing.py rename to aws_lambda_powertools/utilities/auth/jwt/testing.py index 2b70c878e2c..455fd58eb10 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/testing.py +++ b/aws_lambda_powertools/utilities/auth/jwt/testing.py @@ -10,7 +10,7 @@ if TYPE_CHECKING: from collections.abc import Iterator - from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.base import Verifier + from aws_lambda_powertools.utilities.auth.jwt._internal.base import Verifier @contextmanager diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/verifier.py b/aws_lambda_powertools/utilities/auth/jwt/verifier.py similarity index 96% rename from aws_lambda_powertools/utilities/auth_alpha/jwt/verifier.py rename to aws_lambda_powertools/utilities/auth/jwt/verifier.py index 65b3baf2395..1b4dd6817e0 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/verifier.py +++ b/aws_lambda_powertools/utilities/auth/jwt/verifier.py @@ -7,18 +7,18 @@ import jwt -from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import Deadline -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import ( +from aws_lambda_powertools.utilities.auth._internal.deadline import Deadline +from aws_lambda_powertools.utilities.auth._internal.validation import ( finite_seconds, https_url, is_nonempty_string, string_list, string_mapping, ) -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.base import Verifier -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.errors import sanitize_errors -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal.jwks import copy_key_set, shared_cache, signing_key -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import ( +from aws_lambda_powertools.utilities.auth.jwt._internal.base import Verifier +from aws_lambda_powertools.utilities.auth.jwt._internal.errors import sanitize_errors +from aws_lambda_powertools.utilities.auth.jwt._internal.jwks import copy_key_set, shared_cache, signing_key +from aws_lambda_powertools.utilities.auth.jwt.exceptions import ( InvalidClaimsError, InvalidSignatureError, InvalidTokenError, diff --git a/aws_lambda_powertools/utilities/auth_alpha/oauth2/__init__.py b/aws_lambda_powertools/utilities/auth/oauth2/__init__.py similarity index 84% rename from aws_lambda_powertools/utilities/auth_alpha/oauth2/__init__.py rename to aws_lambda_powertools/utilities/auth/oauth2/__init__.py index 51c2bfea71e..067dc036000 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/oauth2/__init__.py +++ b/aws_lambda_powertools/utilities/auth/oauth2/__init__.py @@ -6,7 +6,7 @@ from typing import TYPE_CHECKING if TYPE_CHECKING: - from aws_lambda_powertools.utilities.auth_alpha.oauth2.client import OAuth2Client as OAuth2Client + from aws_lambda_powertools.utilities.auth.oauth2.client import OAuth2Client as OAuth2Client __all__ = ["OAuth2Client"] diff --git a/aws_lambda_powertools/utilities/auth_alpha/oauth2/client.py b/aws_lambda_powertools/utilities/auth/oauth2/client.py similarity index 96% rename from aws_lambda_powertools/utilities/auth_alpha/oauth2/client.py rename to aws_lambda_powertools/utilities/auth/oauth2/client.py index acb49b8a8bc..d058864507e 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/oauth2/client.py +++ b/aws_lambda_powertools/utilities/auth/oauth2/client.py @@ -12,16 +12,16 @@ import urllib3 -from aws_lambda_powertools.utilities.auth_alpha._internal.deadline import Deadline, RequestError -from aws_lambda_powertools.utilities.auth_alpha._internal.errors import sanitize_errors -from aws_lambda_powertools.utilities.auth_alpha._internal.http import HTTPClient -from aws_lambda_powertools.utilities.auth_alpha._internal.scopes import required_scopes -from aws_lambda_powertools.utilities.auth_alpha._internal.validation import ( +from aws_lambda_powertools.utilities.auth._internal.deadline import Deadline, RequestError +from aws_lambda_powertools.utilities.auth._internal.errors import sanitize_errors +from aws_lambda_powertools.utilities.auth._internal.http import HTTPClient +from aws_lambda_powertools.utilities.auth._internal.scopes import required_scopes +from aws_lambda_powertools.utilities.auth._internal.validation import ( finite_seconds, https_url, is_nonempty_string, ) -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError if TYPE_CHECKING: from collections.abc import Callable diff --git a/aws_lambda_powertools/utilities/auth_alpha/oauth2/exceptions.py b/aws_lambda_powertools/utilities/auth/oauth2/exceptions.py similarity index 91% rename from aws_lambda_powertools/utilities/auth_alpha/oauth2/exceptions.py rename to aws_lambda_powertools/utilities/auth/oauth2/exceptions.py index f4cdd7f060e..742f8a2938b 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/oauth2/exceptions.py +++ b/aws_lambda_powertools/utilities/auth/oauth2/exceptions.py @@ -1,6 +1,6 @@ """Credential-free errors raised by outbound OAuth requests.""" -from aws_lambda_powertools.utilities.auth_alpha.exceptions import AuthError, AuthFailureReason +from aws_lambda_powertools.utilities.auth.exceptions import AuthError, AuthFailureReason __all__ = ["AuthError", "AuthFailureReason", "TokenExchangeError", "DownstreamRequestError"] diff --git a/aws_lambda_powertools/utilities/auth_alpha/__init__.py b/aws_lambda_powertools/utilities/auth_alpha/__init__.py index 2090e16bd89..c6044652522 100644 --- a/aws_lambda_powertools/utilities/auth_alpha/__init__.py +++ b/aws_lambda_powertools/utilities/auth_alpha/__init__.py @@ -1,32 +1,52 @@ -"""Alpha authentication and authorization utilities for AWS Lambda.""" +"""Deprecated import path. Auth graduated to ``aws_lambda_powertools.utilities.auth``; this alias goes away in v4.""" from __future__ import annotations import importlib -from typing import TYPE_CHECKING +import importlib.abc +import importlib.util +import sys +import warnings +from typing import TYPE_CHECKING, Any + +from aws_lambda_powertools.warnings import PowertoolsDeprecationWarning if TYPE_CHECKING: - from aws_lambda_powertools.utilities.auth_alpha.exceptions import AuthFailureReason as AuthFailureReason - from aws_lambda_powertools.utilities.auth_alpha.jwt import AuthErrorContext as AuthErrorContext - from aws_lambda_powertools.utilities.auth_alpha.jwt import JWTVerifier as JWTVerifier - from aws_lambda_powertools.utilities.auth_alpha.oauth2 import OAuth2Client as OAuth2Client + from importlib.machinery import ModuleSpec + from types import ModuleType + +_OLD = __name__ +_NEW = "aws_lambda_powertools.utilities.auth" + +warnings.warn( + f"{_OLD} is deprecated and will be removed in v4. Import from {_NEW} instead; the API is the same.", + category=PowertoolsDeprecationWarning, + stacklevel=2, +) + + +class _AliasFinder(importlib.abc.MetaPathFinder, importlib.abc.Loader): + """Serve ``auth_alpha.`` with the very same module object as ``auth.``.""" + + def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> ModuleSpec | None: + if fullname.startswith(f"{_OLD}."): + return importlib.util.spec_from_loader(fullname, self) + return None + + def create_module(self, spec: ModuleSpec) -> ModuleType: + return importlib.import_module(f"{_NEW}{spec.name[len(_OLD) :]}") + + def exec_module(self, module: ModuleType) -> None: + return None + -__all__ = ["AuthErrorContext", "AuthFailureReason", "JWTVerifier", "OAuth2Client"] +if not any(isinstance(finder, _AliasFinder) for finder in sys.meta_path): + sys.meta_path.insert(0, _AliasFinder()) -def __getattr__(name: str) -> object: - modules = { - "AuthErrorContext": "jwt", - "AuthFailureReason": "exceptions", - "JWTVerifier": "jwt", - "OAuth2Client": "oauth2", - } - if name in modules: - value = getattr(importlib.import_module(f"{__name__}.{modules[name]}"), name) - globals()[name] = value - return value - raise AttributeError(f"module {__name__!r} has no attribute {name!r}") +def __getattr__(name: str) -> Any: + return getattr(importlib.import_module(_NEW), name) def __dir__() -> list[str]: - return sorted(set(globals()) | set(__all__)) + return dir(importlib.import_module(_NEW)) diff --git a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/errors.py b/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/errors.py deleted file mode 100644 index 0ac7598fe60..00000000000 --- a/aws_lambda_powertools/utilities/auth_alpha/jwt/_internal/errors.py +++ /dev/null @@ -1,3 +0,0 @@ -from aws_lambda_powertools.utilities.auth_alpha._internal.errors import sanitize_errors - -__all__ = ["sanitize_errors"] diff --git a/docs/api_doc/auth.md b/docs/api_doc/auth.md new file mode 100644 index 00000000000..9b89ff0e962 --- /dev/null +++ b/docs/api_doc/auth.md @@ -0,0 +1,9 @@ + +::: aws_lambda_powertools.utilities.auth.jwt.verifier + options: + inherited_members: true +::: aws_lambda_powertools.utilities.auth.AuthErrorContext +::: aws_lambda_powertools.utilities.auth.jwt.exceptions +::: aws_lambda_powertools.utilities.auth.jwt.testing +::: aws_lambda_powertools.utilities.auth.oauth2.client +::: aws_lambda_powertools.utilities.auth.oauth2.exceptions diff --git a/docs/api_doc/auth_alpha.md b/docs/api_doc/auth_alpha.md deleted file mode 100644 index 30854875ab5..00000000000 --- a/docs/api_doc/auth_alpha.md +++ /dev/null @@ -1,9 +0,0 @@ - -::: aws_lambda_powertools.utilities.auth_alpha.jwt.verifier - options: - inherited_members: true -::: aws_lambda_powertools.utilities.auth_alpha.AuthErrorContext -::: aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions -::: aws_lambda_powertools.utilities.auth_alpha.jwt.testing -::: aws_lambda_powertools.utilities.auth_alpha.oauth2.client -::: aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions diff --git a/docs/utilities/auth.md b/docs/utilities/auth.md index c379e756aca..7583e4a0e2e 100644 --- a/docs/utilities/auth.md +++ b/docs/utilities/auth.md @@ -1,15 +1,15 @@ --- -title: Auth (alpha) +title: Auth description: JWT access-token verification for Lambda status: new --- -!!! warning "Alpha / experimental" - This utility ships under the `auth_alpha` namespace while we collect feedback. Its public API may change before GA. Pin your Powertools version before using it in production. - Auth verifies JWT access tokens in any Lambda workload. Use `verify()` directly, create Event Handler middleware with `require()`, or build a Lambda authorizer response with `authorize()`. -For client-credentials tokens used to call a downstream API, see [OAuth2 client (alpha)](oauth2.md). +For client-credentials tokens used to call a downstream API, see [OAuth2 client](oauth2.md). + +???+ note "Coming from `auth_alpha`?" + Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0. That import path still works and emits a `PowertoolsDeprecationWarning`; it goes away in v4. Change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. ```mermaid flowchart LR @@ -60,7 +60,7 @@ Build checks cannot validate dependencies supplied only by the runtime or separa Create the verifier outside the Lambda handler so warm invocations reuse its signing-key cache. Configure the trusted issuer, this workload's audience, and the algorithms accepted from that issuer. ```python title="basic.py" ---8<-- "examples/auth_alpha/jwt/src/basic.py" +--8<-- "examples/auth/jwt/src/basic.py" ``` Replace `token_use` with the access-token marker used by your identity provider. This prevents another JWT type from being accepted only because it has the same audience. @@ -89,7 +89,7 @@ Static `jwks` avoids network access, but your application must rotate those keys `verifier.require()` creates Event Handler middleware bound to the verifier and requested scopes. Create the verifier outside the handler to reuse its cache. ```python title="middleware.py" ---8<-- "examples/auth_alpha/jwt/src/middleware.py" +--8<-- "examples/auth/jwt/src/middleware.py" ``` Here, `app.get()` registers the middleware only for `GET /orders`. For each matching request, the middleware: @@ -114,7 +114,7 @@ Configure public routes and CORS preflight separately. Without middleware, pass the complete `Authorization` header to `verify_authorization_header()`. It validates the Bearer scheme and verifies the extracted JWT: ```python title="direct.py" ---8<-- "examples/auth_alpha/jwt/src/direct.py" +--8<-- "examples/auth/jwt/src/direct.py" ``` Both verification methods require `iss`, `aud`, and `exp`; use `required_claims` to require additional claims. @@ -126,7 +126,7 @@ Both verification methods require `iss`, `aud`, and `exp`; use `required_claims` This complete Lambda adds provider-specific token checks, a required scope, a tenant authorization rule, and custom error handling: ```python title="custom_authorization.py" ---8<-- "examples/auth_alpha/jwt/src/custom_authorization.py" +--8<-- "examples/auth/jwt/src/custom_authorization.py" ``` Match `expected_claims` to your provider's access-token profile. `authorize` runs after verification and scope checks. @@ -151,7 +151,7 @@ An expired cache with a failed refresh raises `JWKSFetchError`; stale keys are n Call `prefetch()` after constructing the verifier to retrieve keys during Lambda INIT: ```python title="prefetch.py" ---8<-- "examples/auth_alpha/jwt/src/prefetch.py" +--8<-- "examples/auth/jwt/src/prefetch.py" ``` Prefetching can reduce first-invocation latency, but a provider outage can fail the cold start. Without it, the first `verify()` fetches keys. @@ -163,7 +163,7 @@ Static `jwks` avoids network access. Recreate the verifier or execution environm Use the Cognito profile for resource-bound Cognito access tokens: ```python title="cognito.py" ---8<-- "examples/auth_alpha/jwt/src/cognito.py" +--8<-- "examples/auth/jwt/src/cognito.py" ``` This profile checks RS256, `token_use="access"`, the configured app client ID, and the resource audience. Cognito ID tokens and access tokens without the configured resource audience are rejected. @@ -175,7 +175,7 @@ Use `JWTVerifier.any_of()` when the same Lambda trusts access tokens from multip Use `authorize()` when API Gateway invokes a dedicated Lambda authorizer: ```python title="authorizer.py" ---8<-- "examples/auth_alpha/jwt/src/authorizer/authorizer.py" +--8<-- "examples/auth/jwt/src/authorizer/authorizer.py" ``` The helper supports REST API TOKEN and REQUEST events and HTTP API REQUEST payloads. Choose `response_format="iam"` for an IAM policy or `response_format="simple"` for an HTTP API 2.0 simple response. @@ -187,7 +187,7 @@ Invalid tokens and insufficient scopes return Deny or `isAuthorized=false`. If s The example template disables API Gateway authorizer-result caching so every request is verified: ```yaml title="templates/sam.yaml" ---8<-- "examples/auth_alpha/jwt/templates/sam.yaml" +--8<-- "examples/auth/jwt/templates/sam.yaml" ``` If enabling Gateway caching, include every authorization input in its identity sources. A cached allow can still outlive JWT expiration until the cache TTL ends. @@ -215,7 +215,7 @@ Log `reason.value` and `retryable`, not exception messages, tokens, claims, or r Use `mock_claims` to test the complete middleware Lambda without cryptography or network calls: ```python title="test_middleware.py" ---8<-- "examples/auth_alpha/jwt/tests/test_middleware.py" +--8<-- "examples/auth/jwt/tests/test_middleware.py" ``` The test exercises the HTTP event, Bearer extraction, and scope check. `mock_claims` replaces only token verification and restores it on exit. diff --git a/docs/utilities/oauth2.md b/docs/utilities/oauth2.md index 236bbc6f300..4fcc8d0b701 100644 --- a/docs/utilities/oauth2.md +++ b/docs/utilities/oauth2.md @@ -1,12 +1,9 @@ --- -title: OAuth2 client (alpha) +title: OAuth2 client description: Acquire and cache client-credentials tokens for downstream APIs status: new --- -!!! warning "Alpha / experimental" - This utility ships under the `auth_alpha` namespace while we collect feedback. Its public API may change before GA. Pin your Powertools version before using it in production. - `OAuth2Client` obtains bearer tokens for a Lambda function calling an API on its own behalf. It uses the client-credentials grant with `client_secret_basic` (default) or explicit `client_secret_post` authentication. @@ -68,7 +65,7 @@ Create the client outside the Lambda handler so warm invocations reuse its token This complete Lambda loads a plain-string secret through Parameters and calls `GET /stock/{sku}` on an inventory API that returns JSON: ```python title="client_credentials.py" ---8<-- "examples/auth_alpha/oauth2/src/client_credentials.py" +--8<-- "examples/auth/oauth2/src/client_credentials.py" ``` Configure these environment variables: @@ -108,7 +105,7 @@ Select your provider's method; there is no automatic fallback. API requests alwa This example uses `CLIENT_SECRET` instead of `CLIENT_SECRET_NAME` and calls `INVENTORY_URL` directly: ```python title="client_secret_post.py" ---8<-- "examples/auth_alpha/oauth2/src/client_secret_post.py" +--8<-- "examples/auth/oauth2/src/client_secret_post.py" ``` You can also pass the Parameters `load_secret` function from the first example as `client_secret`. @@ -156,7 +153,7 @@ Your application selects the client; routing and failover are not automatic. Pass the fresh `Authorization: Bearer ` dictionary from `auth_headers()` to your HTTP client: ```python title="headers.py" ---8<-- "examples/auth_alpha/oauth2/src/headers.py" +--8<-- "examples/auth/oauth2/src/headers.py" ``` This example validates HTTPS before acquiring credentials. Configure your HTTP client's timeouts, redirects, and retries yourself. @@ -223,7 +220,7 @@ Invalid headers and case-insensitive Authorization overrides are rejected before ### Errors and diagnostics -OAuth errors inherit from `AuthError` in `auth_alpha.exceptions`. +OAuth errors inherit from `AuthError` in `auth.exceptions`. | Exception | Reason | Retryable | | --------- | ------ | --------- | @@ -236,7 +233,7 @@ Invalid client configuration, method, URL, timeout, headers, or option names rai Use the fixed `reason.value` and `retryable` fields for logs and metrics: ```python title="diagnostics.py" ---8<-- "examples/auth_alpha/oauth2/src/diagnostics.py" +--8<-- "examples/auth/oauth2/src/diagnostics.py" ``` This handler returns proxy-style responses and uses the environment-secret deployment settings. @@ -284,5 +281,5 @@ Cancelling the task does not stop the worker's request; timeouts still apply. In Mock the client operation when testing application behavior, and test your provider configuration separately: ```python title="test_client_credentials.py" ---8<-- "examples/auth_alpha/oauth2/tests/test_client_credentials.py" +--8<-- "examples/auth/oauth2/tests/test_client_credentials.py" ``` diff --git a/examples/auth_alpha/jwt/src/authorizer/authorizer.py b/examples/auth/jwt/src/authorizer/authorizer.py similarity index 87% rename from examples/auth_alpha/jwt/src/authorizer/authorizer.py rename to examples/auth/jwt/src/authorizer/authorizer.py index a94ee913e0b..b8133db6e12 100644 --- a/examples/auth_alpha/jwt/src/authorizer/authorizer.py +++ b/examples/auth/jwt/src/authorizer/authorizer.py @@ -1,8 +1,8 @@ import os from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError from aws_lambda_powertools.utilities.typing import LambdaContext logger = Logger() diff --git a/examples/auth_alpha/jwt/src/authorizer/requirements.txt b/examples/auth/jwt/src/authorizer/requirements.txt similarity index 100% rename from examples/auth_alpha/jwt/src/authorizer/requirements.txt rename to examples/auth/jwt/src/authorizer/requirements.txt diff --git a/examples/auth_alpha/jwt/src/backend/backend.py b/examples/auth/jwt/src/backend/backend.py similarity index 100% rename from examples/auth_alpha/jwt/src/backend/backend.py rename to examples/auth/jwt/src/backend/backend.py diff --git a/examples/auth_alpha/jwt/src/backend/requirements.txt b/examples/auth/jwt/src/backend/requirements.txt similarity index 100% rename from examples/auth_alpha/jwt/src/backend/requirements.txt rename to examples/auth/jwt/src/backend/requirements.txt diff --git a/examples/auth_alpha/jwt/src/basic.py b/examples/auth/jwt/src/basic.py similarity index 88% rename from examples/auth_alpha/jwt/src/basic.py rename to examples/auth/jwt/src/basic.py index 5f389a986a5..009f4ba1d0f 100644 --- a/examples/auth_alpha/jwt/src/basic.py +++ b/examples/auth/jwt/src/basic.py @@ -1,6 +1,6 @@ import os -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext verifier = JWTVerifier( diff --git a/examples/auth_alpha/jwt/src/cognito.py b/examples/auth/jwt/src/cognito.py similarity index 90% rename from examples/auth_alpha/jwt/src/cognito.py rename to examples/auth/jwt/src/cognito.py index fd580c3d3ef..e7e63f1a09f 100644 --- a/examples/auth_alpha/jwt/src/cognito.py +++ b/examples/auth/jwt/src/cognito.py @@ -1,7 +1,7 @@ import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() diff --git a/examples/auth_alpha/jwt/src/custom_authorization.py b/examples/auth/jwt/src/custom_authorization.py similarity index 93% rename from examples/auth_alpha/jwt/src/custom_authorization.py rename to examples/auth/jwt/src/custom_authorization.py index 7120cfe11ae..992eb9dea13 100644 --- a/examples/auth_alpha/jwt/src/custom_authorization.py +++ b/examples/auth/jwt/src/custom_authorization.py @@ -2,7 +2,7 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response -from aws_lambda_powertools.utilities.auth_alpha import AuthErrorContext, JWTVerifier +from aws_lambda_powertools.utilities.auth import AuthErrorContext, JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() diff --git a/examples/auth_alpha/jwt/src/direct.py b/examples/auth/jwt/src/direct.py similarity index 86% rename from examples/auth_alpha/jwt/src/direct.py rename to examples/auth/jwt/src/direct.py index 7dc443e46b1..35d3b991a68 100644 --- a/examples/auth_alpha/jwt/src/direct.py +++ b/examples/auth/jwt/src/direct.py @@ -1,8 +1,8 @@ import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidTokenError, JWKSFetchError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidTokenError, JWKSFetchError from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() diff --git a/examples/auth_alpha/jwt/src/middleware.py b/examples/auth/jwt/src/middleware.py similarity index 91% rename from examples/auth_alpha/jwt/src/middleware.py rename to examples/auth/jwt/src/middleware.py index f5bc1ac546e..57b8b9f7eae 100644 --- a/examples/auth_alpha/jwt/src/middleware.py +++ b/examples/auth/jwt/src/middleware.py @@ -1,7 +1,7 @@ import os from aws_lambda_powertools.event_handler import APIGatewayHttpResolver -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext app = APIGatewayHttpResolver() diff --git a/examples/auth_alpha/jwt/src/prefetch.py b/examples/auth/jwt/src/prefetch.py similarity index 88% rename from examples/auth_alpha/jwt/src/prefetch.py rename to examples/auth/jwt/src/prefetch.py index 880bc5e2456..1c74a555e17 100644 --- a/examples/auth_alpha/jwt/src/prefetch.py +++ b/examples/auth/jwt/src/prefetch.py @@ -1,6 +1,6 @@ import os -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from aws_lambda_powertools.utilities.typing import LambdaContext verifier = JWTVerifier( diff --git a/examples/auth_alpha/jwt/templates/sam.yaml b/examples/auth/jwt/templates/sam.yaml similarity index 100% rename from examples/auth_alpha/jwt/templates/sam.yaml rename to examples/auth/jwt/templates/sam.yaml diff --git a/examples/auth_alpha/jwt/tests/test_middleware.py b/examples/auth/jwt/tests/test_middleware.py similarity index 91% rename from examples/auth_alpha/jwt/tests/test_middleware.py rename to examples/auth/jwt/tests/test_middleware.py index d5a4c110068..1a43a89e059 100644 --- a/examples/auth_alpha/jwt/tests/test_middleware.py +++ b/examples/auth/jwt/tests/test_middleware.py @@ -1,6 +1,6 @@ import json -from aws_lambda_powertools.utilities.auth_alpha.jwt.testing import mock_claims +from aws_lambda_powertools.utilities.auth.jwt.testing import mock_claims def test_list_orders(monkeypatch): diff --git a/examples/auth_alpha/oauth2/src/client_credentials.py b/examples/auth/oauth2/src/client_credentials.py similarity index 94% rename from examples/auth_alpha/oauth2/src/client_credentials.py rename to examples/auth/oauth2/src/client_credentials.py index 036f2192133..2b53f433847 100644 --- a/examples/auth_alpha/oauth2/src/client_credentials.py +++ b/examples/auth/oauth2/src/client_credentials.py @@ -4,7 +4,7 @@ from botocore.config import Config from aws_lambda_powertools.utilities import parameters -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext secrets = parameters.SecretsProvider( diff --git a/examples/auth_alpha/oauth2/src/client_secret_post.py b/examples/auth/oauth2/src/client_secret_post.py similarity index 92% rename from examples/auth_alpha/oauth2/src/client_secret_post.py rename to examples/auth/oauth2/src/client_secret_post.py index 9d2dd112c48..a46a1d54c5a 100644 --- a/examples/auth_alpha/oauth2/src/client_secret_post.py +++ b/examples/auth/oauth2/src/client_secret_post.py @@ -1,6 +1,6 @@ import os -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext # Create outside the handler so warm invocations can reuse the token cache. diff --git a/examples/auth_alpha/oauth2/src/diagnostics.py b/examples/auth/oauth2/src/diagnostics.py similarity index 86% rename from examples/auth_alpha/oauth2/src/diagnostics.py rename to examples/auth/oauth2/src/diagnostics.py index d1c41daffc8..6804ae031e7 100644 --- a/examples/auth_alpha/oauth2/src/diagnostics.py +++ b/examples/auth/oauth2/src/diagnostics.py @@ -3,8 +3,8 @@ from urllib.parse import quote from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError from aws_lambda_powertools.utilities.typing import LambdaContext logger = Logger() diff --git a/examples/auth_alpha/oauth2/src/headers.py b/examples/auth/oauth2/src/headers.py similarity index 94% rename from examples/auth_alpha/oauth2/src/headers.py rename to examples/auth/oauth2/src/headers.py index 42d4022d3fd..a259796c088 100644 --- a/examples/auth_alpha/oauth2/src/headers.py +++ b/examples/auth/oauth2/src/headers.py @@ -3,7 +3,7 @@ import urllib3 -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client from aws_lambda_powertools.utilities.typing import LambdaContext INVENTORY_URL = os.environ["INVENTORY_URL"] diff --git a/examples/auth_alpha/oauth2/tests/test_client_credentials.py b/examples/auth/oauth2/tests/test_client_credentials.py similarity index 100% rename from examples/auth_alpha/oauth2/tests/test_client_credentials.py rename to examples/auth/oauth2/tests/test_client_credentials.py diff --git a/examples/auth_alpha/oauth2/tests/test_client_secret_post.py b/examples/auth/oauth2/tests/test_client_secret_post.py similarity index 100% rename from examples/auth_alpha/oauth2/tests/test_client_secret_post.py rename to examples/auth/oauth2/tests/test_client_secret_post.py diff --git a/examples/auth_alpha/oauth2/tests/test_documented_configuration.py b/examples/auth/oauth2/tests/test_documented_configuration.py similarity index 96% rename from examples/auth_alpha/oauth2/tests/test_documented_configuration.py rename to examples/auth/oauth2/tests/test_documented_configuration.py index 85867570dbc..2fb88088249 100644 --- a/examples/auth_alpha/oauth2/tests/test_documented_configuration.py +++ b/examples/auth/oauth2/tests/test_documented_configuration.py @@ -8,8 +8,8 @@ import pytest import urllib3 -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError EXAMPLES = Path(__file__).parents[1] / "src" diff --git a/examples/auth_alpha/oauth2/tests/test_headers.py b/examples/auth/oauth2/tests/test_headers.py similarity index 97% rename from examples/auth_alpha/oauth2/tests/test_headers.py rename to examples/auth/oauth2/tests/test_headers.py index 64811c4df8e..07f9417a6ef 100644 --- a/examples/auth_alpha/oauth2/tests/test_headers.py +++ b/examples/auth/oauth2/tests/test_headers.py @@ -4,7 +4,7 @@ import pytest import urllib3 -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client +from aws_lambda_powertools.utilities.auth import OAuth2Client EXAMPLE = Path(__file__).parents[1] / "src" / "headers.py" diff --git a/mkdocs.yml b/mkdocs.yml index 99a4014457a..b598d138c92 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,7 +95,7 @@ nav: # - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md # - Customer to advocate: contributing/tracks/customer_advocate.md - API Documentation: - - Auth (alpha): api_doc/auth_alpha.md + - Auth: api_doc/auth.md - Batch Processing: - Base: api_doc/batch/base.md - Decorators: api_doc/batch/decorators.md diff --git a/noxfile.py b/noxfile.py index 1d17df74687..8ac273ca7e0 100644 --- a/noxfile.py +++ b/noxfile.py @@ -276,7 +276,7 @@ def test_with_auth_required_packages(session: nox.Session): """Verify the Auth utility using only its declared optional dependencies.""" build_and_run_test( session, - folders=[f"{PREFIX_TESTS_FUNCTIONAL}/auth_alpha/jwt/"], + folders=[f"{PREFIX_TESTS_FUNCTIONAL}/auth/jwt/"], extras="jwt", ) @@ -286,6 +286,6 @@ def test_with_oauth2_required_packages(session: nox.Session): """Verify OAuth token acquisition without JWT or cryptography dependencies.""" build_and_run_test( session, - folders=[f"{PREFIX_TESTS_FUNCTIONAL}/auth_alpha/oauth2/"], + folders=[f"{PREFIX_TESTS_FUNCTIONAL}/auth/oauth2/"], extras="oauth2", ) diff --git a/tests/functional/auth_alpha/__init__.py b/tests/functional/auth/__init__.py similarity index 100% rename from tests/functional/auth_alpha/__init__.py rename to tests/functional/auth/__init__.py diff --git a/tests/functional/auth_alpha/conftest.py b/tests/functional/auth/conftest.py similarity index 100% rename from tests/functional/auth_alpha/conftest.py rename to tests/functional/auth/conftest.py diff --git a/tests/functional/auth_alpha/jwt/__init__.py b/tests/functional/auth/jwt/__init__.py similarity index 100% rename from tests/functional/auth_alpha/jwt/__init__.py rename to tests/functional/auth/jwt/__init__.py diff --git a/tests/functional/auth_alpha/jwt/conftest.py b/tests/functional/auth/jwt/conftest.py similarity index 93% rename from tests/functional/auth_alpha/jwt/conftest.py rename to tests/functional/auth/jwt/conftest.py index e5259dab923..d2fcf4c4856 100644 --- a/tests/functional/auth_alpha/jwt/conftest.py +++ b/tests/functional/auth/jwt/conftest.py @@ -5,7 +5,7 @@ import pytest from cryptography.hazmat.primitives.asymmetric import rsa -from aws_lambda_powertools.utilities.auth_alpha.jwt._internal import jwks as jwks_module +from aws_lambda_powertools.utilities.auth.jwt._internal import jwks as jwks_module @pytest.fixture(scope="session") diff --git a/tests/functional/auth_alpha/jwt/imports/__init__.py b/tests/functional/auth/jwt/imports/__init__.py similarity index 100% rename from tests/functional/auth_alpha/jwt/imports/__init__.py rename to tests/functional/auth/jwt/imports/__init__.py diff --git a/tests/functional/auth_alpha/jwt/imports/_auth_import_probe.py b/tests/functional/auth/jwt/imports/_auth_import_probe.py similarity index 88% rename from tests/functional/auth_alpha/jwt/imports/_auth_import_probe.py rename to tests/functional/auth/jwt/imports/_auth_import_probe.py index b0155a1482f..c53a536beb1 100644 --- a/tests/functional/auth_alpha/jwt/imports/_auth_import_probe.py +++ b/tests/functional/auth/jwt/imports/_auth_import_probe.py @@ -21,8 +21,8 @@ def find_spec(self, fullname, path=None, target=None): if scenario == "static": sys.meta_path.insert(0, BlockImports("urllib3")) - from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidSignatureError + from aws_lambda_powertools.utilities.auth import JWTVerifier + from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidSignatureError fixture = json.load(sys.stdin) verifier = JWTVerifier( @@ -43,7 +43,7 @@ def find_spec(self, fullname, path=None, target=None): raise AssertionError("Invalid signature was accepted") assert "urllib3" not in sys.modules elif scenario == "remote": - from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier + from aws_lambda_powertools.utilities.auth import JWTVerifier assert "urllib3" not in sys.modules verifier = JWTVerifier( @@ -53,8 +53,8 @@ def find_spec(self, fullname, path=None, target=None): ) assert "urllib3" in sys.modules elif scenario == "exports": - auth = importlib.import_module("aws_lambda_powertools.utilities.auth_alpha") - jwt_auth = importlib.import_module("aws_lambda_powertools.utilities.auth_alpha.jwt") + auth = importlib.import_module("aws_lambda_powertools.utilities.auth") + jwt_auth = importlib.import_module("aws_lambda_powertools.utilities.auth.jwt") exports = {"JWTVerifier", "AuthFailureReason", "AuthErrorContext"} assert exports <= set(dir(auth)) @@ -76,7 +76,7 @@ def find_spec(self, fullname, path=None, target=None): assert members["AuthFailureReason"] is jwt_auth.AuthFailureReason assert members["AuthErrorContext"] is jwt_auth.AuthErrorContext elif scenario == "star": - from aws_lambda_powertools.utilities.auth_alpha import * # noqa: E402,F403 + from aws_lambda_powertools.utilities.auth import * # noqa: E402,F403 assert {"JWTVerifier", "AuthFailureReason", "AuthErrorContext"} <= globals().keys() else: diff --git a/tests/functional/auth_alpha/jwt/imports/test_imports.py b/tests/functional/auth/jwt/imports/test_imports.py similarity index 100% rename from tests/functional/auth_alpha/jwt/imports/test_imports.py rename to tests/functional/auth/jwt/imports/test_imports.py diff --git a/tests/functional/auth_alpha/jwt/integrations/__init__.py b/tests/functional/auth/jwt/integrations/__init__.py similarity index 100% rename from tests/functional/auth_alpha/jwt/integrations/__init__.py rename to tests/functional/auth/jwt/integrations/__init__.py diff --git a/tests/functional/auth_alpha/jwt/integrations/test_authorizer.py b/tests/functional/auth/jwt/integrations/test_authorizer.py similarity index 98% rename from tests/functional/auth_alpha/jwt/integrations/test_authorizer.py rename to tests/functional/auth/jwt/integrations/test_authorizer.py index bb7c1969adf..74aa3a71d41 100644 --- a/tests/functional/auth_alpha/jwt/integrations/test_authorizer.py +++ b/tests/functional/auth/jwt/integrations/test_authorizer.py @@ -2,8 +2,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import JWKSFetchError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import JWKSFetchError from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import ( APIGatewayAuthorizerEventV2, APIGatewayAuthorizerRequestEvent, diff --git a/tests/functional/auth_alpha/jwt/integrations/test_failure_visibility.py b/tests/functional/auth/jwt/integrations/test_failure_visibility.py similarity index 96% rename from tests/functional/auth_alpha/jwt/integrations/test_failure_visibility.py rename to tests/functional/auth/jwt/integrations/test_failure_visibility.py index 0028c236f34..c5e1cc60f1b 100644 --- a/tests/functional/auth_alpha/jwt/integrations/test_failure_visibility.py +++ b/tests/functional/auth/jwt/integrations/test_failure_visibility.py @@ -5,8 +5,8 @@ import pytest from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response -from aws_lambda_powertools.utilities.auth_alpha import AuthErrorContext, AuthFailureReason, JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import JWKSFetchError +from aws_lambda_powertools.utilities.auth import AuthErrorContext, AuthFailureReason, JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import JWKSFetchError from tests.functional.utils import load_event ARN = "arn:aws:execute-api:us-east-1:123456789012:api123/prod/GET/orders" diff --git a/tests/functional/auth_alpha/jwt/integrations/test_middleware.py b/tests/functional/auth/jwt/integrations/test_middleware.py similarity index 99% rename from tests/functional/auth_alpha/jwt/integrations/test_middleware.py rename to tests/functional/auth/jwt/integrations/test_middleware.py index bde43f6887b..a7c3e27cdad 100644 --- a/tests/functional/auth_alpha/jwt/integrations/test_middleware.py +++ b/tests/functional/auth/jwt/integrations/test_middleware.py @@ -10,7 +10,7 @@ LambdaFunctionUrlResolver, Response, ) -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier +from aws_lambda_powertools.utilities.auth import JWTVerifier from tests.functional.utils import load_event diff --git a/tests/functional/auth_alpha/jwt/test_errors.py b/tests/functional/auth/jwt/test_errors.py similarity index 96% rename from tests/functional/auth_alpha/jwt/test_errors.py rename to tests/functional/auth/jwt/test_errors.py index 5c87b3c4ce7..918e0205ccc 100644 --- a/tests/functional/auth_alpha/jwt/test_errors.py +++ b/tests/functional/auth/jwt/test_errors.py @@ -8,8 +8,8 @@ import urllib3 from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import ( +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import ( InvalidClaimsError, InvalidSignatureError, InvalidTokenError, diff --git a/tests/functional/auth_alpha/jwt/test_jwks_cache.py b/tests/functional/auth/jwt/test_jwks_cache.py similarity index 98% rename from tests/functional/auth_alpha/jwt/test_jwks_cache.py rename to tests/functional/auth/jwt/test_jwks_cache.py index 7bc9147b5d1..28980edc388 100644 --- a/tests/functional/auth_alpha/jwt/test_jwks_cache.py +++ b/tests/functional/auth/jwt/test_jwks_cache.py @@ -4,8 +4,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidTokenError, JWKSFetchError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidTokenError, JWKSFetchError JWKS_URL = "https://idp.example.com/keys" ISSUER = "https://idp.example.com/" diff --git a/tests/functional/auth_alpha/jwt/test_profiles.py b/tests/functional/auth/jwt/test_profiles.py similarity index 97% rename from tests/functional/auth_alpha/jwt/test_profiles.py rename to tests/functional/auth/jwt/test_profiles.py index 714af18463a..b16dcd13b5d 100644 --- a/tests/functional/auth_alpha/jwt/test_profiles.py +++ b/tests/functional/auth/jwt/test_profiles.py @@ -2,8 +2,8 @@ import pytest from cryptography.hazmat.primitives.asymmetric import rsa -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import ( +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import ( InvalidClaimsError, InvalidSignatureError, InvalidTokenError, diff --git a/tests/functional/auth_alpha/jwt/test_testing.py b/tests/functional/auth/jwt/test_testing.py similarity index 81% rename from tests/functional/auth_alpha/jwt/test_testing.py rename to tests/functional/auth/jwt/test_testing.py index 53e34f442c3..fb35e6efddf 100644 --- a/tests/functional/auth_alpha/jwt/test_testing.py +++ b/tests/functional/auth/jwt/test_testing.py @@ -1,8 +1,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidTokenError -from aws_lambda_powertools.utilities.auth_alpha.jwt.testing import mock_claims +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidTokenError +from aws_lambda_powertools.utilities.auth.jwt.testing import mock_claims def test_mock_claims_is_scoped_and_restores_real_verification(jwks): diff --git a/tests/functional/auth_alpha/jwt/test_token_profile.py b/tests/functional/auth/jwt/test_token_profile.py similarity index 96% rename from tests/functional/auth_alpha/jwt/test_token_profile.py rename to tests/functional/auth/jwt/test_token_profile.py index 51cb6a13c0f..09ccb8b6e49 100644 --- a/tests/functional/auth_alpha/jwt/test_token_profile.py +++ b/tests/functional/auth/jwt/test_token_profile.py @@ -4,8 +4,8 @@ import pytest from aws_lambda_powertools.event_handler import APIGatewayHttpResolver -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidClaimsError, InvalidSignatureError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidClaimsError, InvalidSignatureError from tests.functional.utils import load_event ARN = "arn:aws:execute-api:us-east-1:123456789012:api123/prod/GET/orders" diff --git a/tests/functional/auth_alpha/jwt/test_verifier.py b/tests/functional/auth/jwt/test_verifier.py similarity index 98% rename from tests/functional/auth_alpha/jwt/test_verifier.py rename to tests/functional/auth/jwt/test_verifier.py index a8700262dd9..39e790f6ff8 100644 --- a/tests/functional/auth_alpha/jwt/test_verifier.py +++ b/tests/functional/auth/jwt/test_verifier.py @@ -4,8 +4,8 @@ import pytest from cryptography.hazmat.primitives.asymmetric import ec, ed25519 -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import ( +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import ( InvalidClaimsError, InvalidSignatureError, InvalidTokenError, diff --git a/tests/functional/auth_alpha/oauth2/__init__.py b/tests/functional/auth/oauth2/__init__.py similarity index 100% rename from tests/functional/auth_alpha/oauth2/__init__.py rename to tests/functional/auth/oauth2/__init__.py diff --git a/tests/functional/auth_alpha/oauth2/test_auth_methods.py b/tests/functional/auth/oauth2/test_auth_methods.py similarity index 96% rename from tests/functional/auth_alpha/oauth2/test_auth_methods.py rename to tests/functional/auth/oauth2/test_auth_methods.py index cbbac878978..5ef563023b5 100644 --- a/tests/functional/auth_alpha/oauth2/test_auth_methods.py +++ b/tests/functional/auth/oauth2/test_auth_methods.py @@ -5,8 +5,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import TokenExchangeError TOKEN_URL = "https://idp.example.com/token?tenant=inventory" TOKEN_RESPONSE = {"access_token": "test-token", "token_type": "Bearer", "expires_in": 600} diff --git a/tests/functional/auth_alpha/oauth2/test_client.py b/tests/functional/auth/oauth2/test_client.py similarity index 99% rename from tests/functional/auth_alpha/oauth2/test_client.py rename to tests/functional/auth/oauth2/test_client.py index 5b988a91c57..2b6e7aaa5bf 100644 --- a/tests/functional/auth_alpha/oauth2/test_client.py +++ b/tests/functional/auth/oauth2/test_client.py @@ -8,8 +8,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import TokenExchangeError TOKEN_URL = "https://idp.example.com/oauth/token" diff --git a/tests/functional/auth_alpha/oauth2/test_errors.py b/tests/functional/auth/oauth2/test_errors.py similarity index 89% rename from tests/functional/auth_alpha/oauth2/test_errors.py rename to tests/functional/auth/oauth2/test_errors.py index 62cf783cc59..7bc63eec915 100644 --- a/tests/functional/auth_alpha/oauth2/test_errors.py +++ b/tests/functional/auth/oauth2/test_errors.py @@ -7,9 +7,9 @@ import urllib3 from aws_lambda_powertools import Logger -from aws_lambda_powertools.utilities.auth_alpha import AuthFailureReason, OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.exceptions import AuthError -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth import AuthFailureReason, OAuth2Client +from aws_lambda_powertools.utilities.auth.exceptions import AuthError +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError TOKEN_URL = "https://idp.example.com/token" RESOURCE_URL = "https://api.example.com/orders" @@ -99,8 +99,8 @@ def test_exchange_errors_expose_fixed_reason_and_retryability( def test_outbound_and_jwt_errors_share_the_public_base(): - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthError as JWTAuthError - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import AuthFailureReason as JWTFailureReason + from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthError as JWTAuthError + from aws_lambda_powertools.utilities.auth.jwt.exceptions import AuthFailureReason as JWTFailureReason assert JWTAuthError is AuthError assert JWTFailureReason is AuthFailureReason diff --git a/tests/functional/auth_alpha/oauth2/test_imports.py b/tests/functional/auth/oauth2/test_imports.py similarity index 91% rename from tests/functional/auth_alpha/oauth2/test_imports.py rename to tests/functional/auth/oauth2/test_imports.py index 7ea0f42adcc..ce59ad0cb2a 100644 --- a/tests/functional/auth_alpha/oauth2/test_imports.py +++ b/tests/functional/auth/oauth2/test_imports.py @@ -16,8 +16,8 @@ def find_spec(self, fullname, path=None, target=None): raise AssertionError("OAuth imported JWT dependencies") sys.meta_path.insert(0, BlockJWT()) -import aws_lambda_powertools.utilities.auth_alpha as auth -import aws_lambda_powertools.utilities.auth_alpha.oauth2 as oauth +import aws_lambda_powertools.utilities.auth as auth +import aws_lambda_powertools.utilities.auth.oauth2 as oauth assert "urllib3" not in sys.modules assert "OAuth2Client" in dir(auth) assert "OAuth2Client" in dir(oauth) diff --git a/tests/functional/auth/test_auth_alpha_alias.py b/tests/functional/auth/test_auth_alpha_alias.py new file mode 100644 index 00000000000..914322c69a3 --- /dev/null +++ b/tests/functional/auth/test_auth_alpha_alias.py @@ -0,0 +1,35 @@ +"""The old auth_alpha import path keeps working, warns once, and hands out the same objects.""" + +import subprocess +import sys + +PROBE = """ +import warnings +with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + from aws_lambda_powertools.utilities.auth_alpha import AuthFailureReason as OldReason + from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier as OldVerifier + from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidSignatureError as OldError + from aws_lambda_powertools.utilities.auth_alpha.oauth2 import OAuth2Client as OldClient +from aws_lambda_powertools.utilities.auth import AuthFailureReason, JWTVerifier, OAuth2Client +from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidSignatureError + +assert OldVerifier is JWTVerifier +assert OldClient is OAuth2Client +assert OldReason is AuthFailureReason +assert OldError is InvalidSignatureError +categories = [w.category.__name__ for w in caught] +assert categories == ["PowertoolsDeprecationWarning"], categories +assert "aws_lambda_powertools.utilities.auth instead" in str(caught[0].message) +print("ok") +""" + + +def test_auth_alpha_alias_warns_once_and_shares_objects(): + # GIVEN code written against the alpha namespace + # WHEN it imports the package and its submodules in a fresh interpreter + result = subprocess.run([sys.executable, "-c", PROBE], capture_output=True, text=True, check=False) + + # THEN one deprecation warning fires and every name is the same object as in the new namespace + assert result.returncode == 0, result.stderr + assert result.stdout.strip() == "ok" diff --git a/tests/integration/auth_alpha/conftest.py b/tests/integration/auth/conftest.py similarity index 100% rename from tests/integration/auth_alpha/conftest.py rename to tests/integration/auth/conftest.py diff --git a/tests/integration/auth_alpha/jwt/test_https.py b/tests/integration/auth/jwt/test_https.py similarity index 95% rename from tests/integration/auth_alpha/jwt/test_https.py rename to tests/integration/auth/jwt/test_https.py index 13dde0f6a38..0f17a9c2380 100644 --- a/tests/integration/auth_alpha/jwt/test_https.py +++ b/tests/integration/auth/jwt/test_https.py @@ -5,8 +5,8 @@ import pytest from cryptography.hazmat.primitives.asymmetric import rsa -from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier -from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import JWKSFetchError +from aws_lambda_powertools.utilities.auth import JWTVerifier +from aws_lambda_powertools.utilities.auth.jwt.exceptions import JWKSFetchError def verifier(endpoint, **options): diff --git a/tests/integration/auth_alpha/oauth2/__init__.py b/tests/integration/auth/oauth2/__init__.py similarity index 100% rename from tests/integration/auth_alpha/oauth2/__init__.py rename to tests/integration/auth/oauth2/__init__.py diff --git a/tests/integration/auth_alpha/oauth2/test_https.py b/tests/integration/auth/oauth2/test_https.py similarity index 98% rename from tests/integration/auth_alpha/oauth2/test_https.py rename to tests/integration/auth/oauth2/test_https.py index 01a9f147d10..ff253c47718 100644 --- a/tests/integration/auth_alpha/oauth2/test_https.py +++ b/tests/integration/auth/oauth2/test_https.py @@ -7,8 +7,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import DownstreamRequestError, TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import DownstreamRequestError, TokenExchangeError TOKEN_RESPONSE = {"access_token": "local-test-token", "token_type": "Bearer", "expires_in": 600} diff --git a/tests/integration/auth_alpha/oauth2/test_provider_contracts.py b/tests/integration/auth/oauth2/test_provider_contracts.py similarity index 98% rename from tests/integration/auth_alpha/oauth2/test_provider_contracts.py rename to tests/integration/auth/oauth2/test_provider_contracts.py index 640292f5a84..1fe2a4ad80c 100644 --- a/tests/integration/auth_alpha/oauth2/test_provider_contracts.py +++ b/tests/integration/auth/oauth2/test_provider_contracts.py @@ -28,8 +28,8 @@ import pytest -from aws_lambda_powertools.utilities.auth_alpha import OAuth2Client -from aws_lambda_powertools.utilities.auth_alpha.oauth2.exceptions import TokenExchangeError +from aws_lambda_powertools.utilities.auth import OAuth2Client +from aws_lambda_powertools.utilities.auth.oauth2.exceptions import TokenExchangeError PROFILES = { "auth0": { From a79ef7432b26b74328decbba714a393b7d758fde Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Sun, 15 Nov 2026 14:10:43 +0000 Subject: [PATCH 2/2] feat(auth): drop the auth_alpha namespace entirely, no alias --- .../references/auth-jwt-oauth2.md | 2 +- .../utilities/auth_alpha/__init__.py | 52 ------------------- docs/utilities/auth.md | 2 +- .../functional/auth/test_auth_alpha_alias.py | 35 ------------- 4 files changed, 2 insertions(+), 89 deletions(-) delete mode 100644 aws_lambda_powertools/utilities/auth_alpha/__init__.py delete mode 100644 tests/functional/auth/test_auth_alpha_alias.py diff --git a/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md b/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md index 8503ad61907..7cee6cc922d 100644 --- a/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md +++ b/.agents/skills/building-lambda-functions-with-powertools-python/references/auth-jwt-oauth2.md @@ -9,7 +9,7 @@ For client-credentials tokens used to call a downstream API, see [OAuth2 client] > **Note: Coming from `auth_alpha`?** -Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0. That import path still works and emits a `PowertoolsDeprecationWarning`; it goes away in v4. Change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. +Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0, under an alpha label that said the API could change before GA. The alpha namespace is gone; change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. ```mermaid flowchart LR diff --git a/aws_lambda_powertools/utilities/auth_alpha/__init__.py b/aws_lambda_powertools/utilities/auth_alpha/__init__.py deleted file mode 100644 index c6044652522..00000000000 --- a/aws_lambda_powertools/utilities/auth_alpha/__init__.py +++ /dev/null @@ -1,52 +0,0 @@ -"""Deprecated import path. Auth graduated to ``aws_lambda_powertools.utilities.auth``; this alias goes away in v4.""" - -from __future__ import annotations - -import importlib -import importlib.abc -import importlib.util -import sys -import warnings -from typing import TYPE_CHECKING, Any - -from aws_lambda_powertools.warnings import PowertoolsDeprecationWarning - -if TYPE_CHECKING: - from importlib.machinery import ModuleSpec - from types import ModuleType - -_OLD = __name__ -_NEW = "aws_lambda_powertools.utilities.auth" - -warnings.warn( - f"{_OLD} is deprecated and will be removed in v4. Import from {_NEW} instead; the API is the same.", - category=PowertoolsDeprecationWarning, - stacklevel=2, -) - - -class _AliasFinder(importlib.abc.MetaPathFinder, importlib.abc.Loader): - """Serve ``auth_alpha.`` with the very same module object as ``auth.``.""" - - def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> ModuleSpec | None: - if fullname.startswith(f"{_OLD}."): - return importlib.util.spec_from_loader(fullname, self) - return None - - def create_module(self, spec: ModuleSpec) -> ModuleType: - return importlib.import_module(f"{_NEW}{spec.name[len(_OLD) :]}") - - def exec_module(self, module: ModuleType) -> None: - return None - - -if not any(isinstance(finder, _AliasFinder) for finder in sys.meta_path): - sys.meta_path.insert(0, _AliasFinder()) - - -def __getattr__(name: str) -> Any: - return getattr(importlib.import_module(_NEW), name) - - -def __dir__() -> list[str]: - return dir(importlib.import_module(_NEW)) diff --git a/docs/utilities/auth.md b/docs/utilities/auth.md index 7583e4a0e2e..acc1b487fcc 100644 --- a/docs/utilities/auth.md +++ b/docs/utilities/auth.md @@ -9,7 +9,7 @@ Auth verifies JWT access tokens in any Lambda workload. Use `verify()` directly, For client-credentials tokens used to call a downstream API, see [OAuth2 client](oauth2.md). ???+ note "Coming from `auth_alpha`?" - Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0. That import path still works and emits a `PowertoolsDeprecationWarning`; it goes away in v4. Change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. + Auth shipped as `aws_lambda_powertools.utilities.auth_alpha` from 3.36.0 to 3.40.0, under an alpha label that said the API could change before GA. The alpha namespace is gone; change the import to `aws_lambda_powertools.utilities.auth`, nothing else changes. ```mermaid flowchart LR diff --git a/tests/functional/auth/test_auth_alpha_alias.py b/tests/functional/auth/test_auth_alpha_alias.py deleted file mode 100644 index 914322c69a3..00000000000 --- a/tests/functional/auth/test_auth_alpha_alias.py +++ /dev/null @@ -1,35 +0,0 @@ -"""The old auth_alpha import path keeps working, warns once, and hands out the same objects.""" - -import subprocess -import sys - -PROBE = """ -import warnings -with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") - from aws_lambda_powertools.utilities.auth_alpha import AuthFailureReason as OldReason - from aws_lambda_powertools.utilities.auth_alpha import JWTVerifier as OldVerifier - from aws_lambda_powertools.utilities.auth_alpha.jwt.exceptions import InvalidSignatureError as OldError - from aws_lambda_powertools.utilities.auth_alpha.oauth2 import OAuth2Client as OldClient -from aws_lambda_powertools.utilities.auth import AuthFailureReason, JWTVerifier, OAuth2Client -from aws_lambda_powertools.utilities.auth.jwt.exceptions import InvalidSignatureError - -assert OldVerifier is JWTVerifier -assert OldClient is OAuth2Client -assert OldReason is AuthFailureReason -assert OldError is InvalidSignatureError -categories = [w.category.__name__ for w in caught] -assert categories == ["PowertoolsDeprecationWarning"], categories -assert "aws_lambda_powertools.utilities.auth instead" in str(caught[0].message) -print("ok") -""" - - -def test_auth_alpha_alias_warns_once_and_shares_objects(): - # GIVEN code written against the alpha namespace - # WHEN it imports the package and its submodules in a fresh interpreter - result = subprocess.run([sys.executable, "-c", PROBE], capture_output=True, text=True, check=False) - - # THEN one deprecation warning fires and every name is the same object as in the new namespace - assert result.returncode == 0, result.stderr - assert result.stdout.strip() == "ok"