Merge branch 'develop' into feat/cloudformation-custom-resource

Author: leandrodamascena

.github/actions/seal/action.yml

@@ -79,7 +79,7 @@ runs:
       shell: bash
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+      uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
       with:
         if-no-files-found: error
         name: ${{ steps.export_artifact_name.outputs.artifact_name }}

.github/actions/upload-artifact/action.yml

@@ -68,7 +68,7 @@ runs:
       shell: bash
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+      uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
       with:
         if-no-files-found: ${{ inputs.if-no-files-found }}
         name: ${{ inputs.name }}

.github/actions/upload-release-provenance/action.yml

@@ -42,7 +42,7 @@ runs:
 
     - id: download-provenance
       name: Download newly generated provenance
-      uses: actions/download-artifact@9782bd6a9848b53b110e712e20e42d89988822b7 # v3.0.1
+      uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
       with:
         name: ${{ inputs.provenance_name }}
 

.github/workflows/quality_check.yml

@@ -73,7 +73,7 @@ jobs:
       - name: Complexity baseline
         run: make complexity-baseline
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@6d798873df2b1b8e5846dba6fb86631229fbcb17 # 4.4.0
+        uses: codecov/codecov-action@125fc84a9a348dbcf27191600683ec096ec9021c # 4.4.1
         with:
           file: ./coverage.xml
           env_vars: PYTHON

.pre-commit-config.yaml

@@ -34,6 +34,7 @@ repos:
         entry: poetry run cfn-lint
         language: system
         types: [yaml]
+        exclude: examples/homepage/install/.*?/serverless\.yml$
         files: examples/.*
   - repo: https://github.com/rhysd/actionlint
     rev: "fd7ba3c382e13dcc0248e425b4cbc3f1185fa3ee" # v1.6.24

CHANGELOG.md

@@ -43,7 +43,7 @@
     validation_error_definition,
     validation_error_response_definition,
 )
-from aws_lambda_powertools.event_handler.util import _FrozenDict
+from aws_lambda_powertools.event_handler.util import _FrozenDict, extract_origin_header
 from aws_lambda_powertools.shared.cookies import Cookie
 from aws_lambda_powertools.shared.functions import powertools_dev_is_set
 from aws_lambda_powertools.shared.json_encoder import Encoder
@@ -782,7 +782,8 @@ def __init__(
 
     def _add_cors(self, event: ResponseEventT, cors: CORSConfig):
         """Update headers to include the configured Access-Control headers"""
-        self.response.headers.update(cors.to_dict(event.get_header_value("Origin")))
+        extracted_origin_header = extract_origin_header(event.resolved_headers_field)
+        self.response.headers.update(cors.to_dict(extracted_origin_header))
 
     def _add_cache_control(self, cache_control: str):
         """Set the specified cache control headers for 200 http responses. For non-200 `no-cache` is used."""
@@ -2129,7 +2130,8 @@ def _not_found(self, method: str) -> ResponseBuilder:
         headers = {}
         if self._cors:
             logger.debug("CORS is enabled, updating headers.")
-            headers.update(self._cors.to_dict(self.current_event.get_header_value("Origin")))
+            extracted_origin_header = extract_origin_header(self.current_event.resolved_headers_field)
+            headers.update(self._cors.to_dict(extracted_origin_header))
 
             if method == "OPTIONS":
                 logger.debug("Pre-flight request detected. Returning CORS with null response")

aws_lambda_powertools/event_handler/api_gateway.py

@@ -1,3 +1,8 @@
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.data_classes.shared_functions import get_header_value
+
+
 class _FrozenDict(dict):
     """
     A dictionary that can be used as a key in another dictionary.
@@ -11,3 +16,27 @@ class _FrozenDict(dict):
 
     def __hash__(self):
         return hash(frozenset(self.keys()))
+
+
+def extract_origin_header(resolver_headers: Dict[str, Any]):
+    """
+    Extracts the 'origin' or 'Origin' header from the provided resolver headers.
+
+    The 'origin' or 'Origin' header can be either a single header or a multi-header.
+
+    Args:
+        resolver_headers (Dict): A dictionary containing the headers.
+
+    Returns:
+        Optional[str]: The value(s) of the origin header or None.
+    """
+    resolved_header = get_header_value(
+        headers=resolver_headers,
+        name="origin",
+        default_value=None,
+        case_sensitive=False,
+    )
+    if isinstance(resolved_header, list):
+        return resolved_header[0]
+
+    return resolved_header

aws_lambda_powertools/event_handler/util.py

@@ -1,6 +1,2 @@
 class InvalidLoggerSamplingRateError(Exception):
     pass
-
-
-class OrphanedChildLoggerError(Exception):
-    pass

aws_lambda_powertools/logging/exceptions.py

@@ -19,13 +19,10 @@
     Optional,
     TypeVar,
     Union,
-    cast,
     overload,
 )
 
 from aws_lambda_powertools.logging.constants import (
-    LOGGER_ATTRIBUTE_HANDLER,
-    LOGGER_ATTRIBUTE_POWERTOOLS_HANDLER,
     LOGGER_ATTRIBUTE_PRECONFIGURED,
 )
 from aws_lambda_powertools.shared import constants
@@ -37,7 +34,7 @@
 from aws_lambda_powertools.utilities import jmespath_utils
 
 from ..shared.types import AnyCallableT
-from .exceptions import InvalidLoggerSamplingRateError, OrphanedChildLoggerError
+from .exceptions import InvalidLoggerSamplingRateError
 from .filters import SuppressFilter
 from .formatter import (
     RESERVED_FORMATTER_CUSTOM_KEYS,
@@ -239,14 +236,14 @@ def __init__(
         self.child = child
         self.logger_formatter = logger_formatter
         self._stream = stream or sys.stdout
+        self.logger_handler = logger_handler or logging.StreamHandler(self._stream)
         self.log_uncaught_exceptions = log_uncaught_exceptions
 
         self._is_deduplication_disabled = resolve_truthy_env_var_choice(
             env=os.getenv(constants.LOGGER_LOG_DEDUPLICATION_ENV, "false"),
         )
         self._default_log_keys = {"service": self.service, "sampling_rate": self.sampling_rate}
         self._logger = self._get_logger()
-        self.logger_handler = logger_handler or self._get_handler()
 
         # NOTE: This is primarily to improve UX, so IDEs can autocomplete LambdaPowertoolsFormatter options
         # previously, we masked all of them as kwargs thus limiting feature discovery
@@ -285,18 +282,6 @@ def _get_logger(self) -> logging.Logger:
 
         return logging.getLogger(logger_name)
 
-    def _get_handler(self) -> logging.Handler:
-        # is a logger handler already configured?
-        if getattr(self, LOGGER_ATTRIBUTE_HANDLER, None):
-            return self.logger_handler
-
-        # for children, use parent's handler
-        if self.child:
-            return getattr(self._logger.parent, LOGGER_ATTRIBUTE_POWERTOOLS_HANDLER, None)  # type: ignore[return-value] # always checked in formatting
-
-        # otherwise, create a new stream handler (first time init)
-        return logging.StreamHandler(self._stream)
-
     def _init_logger(
         self,
         formatter_options: Optional[Dict] = None,
@@ -335,7 +320,6 @@ def _init_logger(
         # std logging will return the same Logger with our attribute if name is reused
         logger.debug(f"Marking logger {self.service} as preconfigured")
         self._logger.init = True  # type: ignore[attr-defined]
-        self._logger.powertools_handler = self.logger_handler  # type: ignore[attr-defined]
 
     def _configure_sampling(self) -> None:
         """Dynamically set log level based on sampling rate
@@ -691,20 +675,15 @@ def removeFilter(self, filter: logging._FilterType) -> None:  # noqa: A002 # fil
     @property
     def registered_handler(self) -> logging.Handler:
         """Convenience property to access the first logger handler"""
-        return self._get_handler()
+        # We ignore mypy here because self.child encodes whether or not self._logger.parent is
+        # None, mypy can't see this from context but we can
+        handlers = self._logger.parent.handlers if self.child else self._logger.handlers  # type: ignore[union-attr]
+        return handlers[0]
 
     @property
     def registered_formatter(self) -> BasePowertoolsFormatter:
         """Convenience property to access the first logger formatter"""
-        handler = self.registered_handler
-        if handler is None:
-            raise OrphanedChildLoggerError(
-                "Orphan child loggers cannot append nor remove keys until a parent is initialized first. "
-                "To solve this issue, you can A) make sure a parent logger is initialized first, or B) move append/remove keys operations to a later stage."  # noqa: E501
-                "Reference: https://docs.powertools.aws.dev/lambda/python/latest/core/logger/#reusing-logger-across-your-code",
-            )
-
-        return cast(BasePowertoolsFormatter, handler.formatter)
+        return self.registered_handler.formatter  # type: ignore[return-value]
 
     @property
     def log_level(self) -> int:

aws_lambda_powertools/logging/logger.py

@@ -9,17 +9,21 @@
 def copy_config_to_registered_loggers(
     source_logger: Logger,
     log_level: Optional[Union[int, str]] = None,
+    ignore_log_level=False,
     exclude: Optional[Set[str]] = None,
     include: Optional[Set[str]] = None,
 ) -> None:
     """Copies source Logger level and handler to all registered loggers for consistent formatting.
 
     Parameters
     ----------
+    ignore_log_level
     source_logger : Logger
         Powertools for AWS Lambda (Python) Logger to copy configuration from
     log_level : Union[int, str], optional
         Logging level to set to registered loggers, by default uses source_logger logging level
+    ignore_log_level: bool
+        Whether to not touch log levels for discovered loggers. log_level param is disregarded when this is set.
     include : Optional[Set[str]], optional
         List of logger names to include, by default all registered loggers are included
     exclude : Optional[Set[str]], optional
@@ -54,7 +58,7 @@ def copy_config_to_registered_loggers(
 
     registered_loggers = _find_registered_loggers(source_logger, loggers, filter_func)
     for logger in registered_loggers:
-        _configure_logger(source_logger, logger, level)
+        _configure_logger(source_logger=source_logger, logger=logger, level=level, ignore_log_level=ignore_log_level)
 
 
 def _include_registered_loggers_filter(loggers: Set[str]):
@@ -78,13 +82,21 @@ def _find_registered_loggers(
     return root_loggers
 
 
-def _configure_logger(source_logger: Logger, logger: logging.Logger, level: Union[int, str]) -> None:
+def _configure_logger(
+    source_logger: Logger,
+    logger: logging.Logger,
+    level: Union[int, str],
+    ignore_log_level: bool = False,
+) -> None:
+    # customers may not want to copy the same log level from Logger to discovered loggers
+    if not ignore_log_level:
+        logger.setLevel(level)
+        source_logger.debug(f"Logger {logger} reconfigured to use logging level {level}")
+
     logger.handlers = []
-    logger.setLevel(level)
     logger.propagate = False  # ensure we don't propagate logs to existing loggers, #1073
     source_logger.append_keys(name="%(name)s")  # include logger name, see #1267
 
-    source_logger.debug(f"Logger {logger} reconfigured to use logging level {level}")
     for source_handler in source_logger.handlers:
         logger.addHandler(source_handler)
         source_logger.debug(f"Logger {logger} reconfigured to use {source_handler}")

aws_lambda_powertools/logging/utils.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "2.37.0"
+VERSION = "2.38.1"

aws_lambda_powertools/shared/version.py

@@ -1,5 +1,5 @@
 # v9.1.18
-FROM squidfunk/mkdocs-material@sha256:48d1914439e935734b9b0886c9d82da37d804d8f7a42cf2aedf090b054de2928
+FROM squidfunk/mkdocs-material@sha256:5358893a04dc6ed0e267ef1c0c06abc5d6b00d13dd0fee703c978ef98d56fd53
 # pip-compile --generate-hashes --output-file=requirements.txt requirements.in
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

docs/Dockerfile

@@ -496,6 +496,16 @@ Notice in the CloudWatch Logs output how `payment_id` appears as expected when l
     ```json hl_lines="12"
     --8<-- "examples/logger/src/logger_reuse_output.json"
     ```
+???+ note "Note: About Child Loggers"
+    Coming from standard library, you might be used to use `logging.getLogger(__name__)`. This will create a new instance of a Logger with a different name.
+
+    In Powertools, you can have the same effect by using `child=True` parameter: `Logger(child=True)`. This creates a new Logger instance named after `service.<module>`. All state changes will be propagated bi-directionally between Child and Parent.
+
+    For that reason, there could be side effects depending on the order the Child Logger is instantiated, because Child Loggers don't have a handler.
+
+    For example, if you instantiated a Child Logger and immediately used `logger.append_keys/remove_keys/set_correlation_id` to update logging state, this might fail if the Parent Logger wasn't instantiated.
+
+    In this scenario, you can either ensure any calls manipulating state are only called when a Parent Logger is instantiated (example above), or refrain from using `child=True` parameter altogether.
 
 ### Sampling debug logs
 
@@ -571,56 +581,48 @@ You can use import and use them as any other Logger formatter via `logger_format
 
 ### Migrating from other Loggers
 
-If you're migrating from other Loggers, there are few key points to be aware of: [Service parameter](#the-service-parameter), [Child Loggers](#child-loggers), [Overriding Log records](#overriding-log-records), and [Logging exceptions](#logging-exceptions).
+If you're migrating from other Loggers, there are few key points to be aware of: [Service parameter](#the-service-parameter), [Inheriting Loggers](#inheriting-loggers), [Overriding Log records](#overriding-log-records), and [Logging exceptions](#logging-exceptions).
 
 #### The service parameter
 
 Service is what defines the Logger name, including what the Lambda function is responsible for, or part of (e.g payment service).
 
 For Logger, the `service` is the logging key customers can use to search log operations for one or more functions - For example, **search for all errors, or messages like X, where service is payment**.
 
-#### Child Loggers
+#### Inheriting Loggers
 
-<center>
-```mermaid
-stateDiagram-v2
-    direction LR
-    Parent: Logger()
-    Child: Logger(child=True)
-    Parent --> Child: bi-directional updates
-    Note right of Child
-        Both have the same service
-    end note
-```
-</center>
+??? tip "Tip: Prefer [Logger Reuse feature](#reusing-logger-across-your-code) over inheritance unless strictly necessary, [see caveats.](#reusing-logger-across-your-code)"
 
-For inheritance, Logger uses `child` parameter to ensure we don't compete with its parents config. We name child Loggers following Python's convention: _`{service}`.`{filename}`_.
+> Python Logging hierarchy happens via the dot notation: `service`, `service.child`, `service.child_2`
+For inheritance, Logger uses a `child=True` parameter along with `service` being the same value across Loggers.
 
-Changes are bidirectional between parents and loggers. That is, appending a key in a child or parent will ensure both have them. This means, having the same `service` name is important when instantiating them.
+For child Loggers, we introspect the name of your module where `Logger(child=True, service="name")` is called, and we name your Logger as **{service}.{filename}**.
 
-=== "logging_inheritance_good.py"
+???+ danger
+    A common issue when migrating from other Loggers is that `service` might be defined in the parent Logger (no child param), and not defined in the child Logger:
+
+=== "logging_inheritance_bad.py"
 
     ```python hl_lines="1 9"
-    --8<-- "examples/logger/src/logging_inheritance_good.py"
+    --8<-- "examples/logger/src/logging_inheritance_bad.py"
     ```
 
 === "logging_inheritance_module.py"
-
     ```python hl_lines="1 9"
     --8<-- "examples/logger/src/logging_inheritance_module.py"
     ```
 
-There are two important side effects when using child loggers:
+In this case, Logger will register a Logger named `payment`, and a Logger named `service_undefined`. The latter isn't inheriting from the parent, and will have no handler, resulting in no message being logged to standard output.
 
-1. **Service name mismatch**. Logging messages will be dropped as child loggers don't have logging handlers.
-    * Solution: use `POWERTOOLS_SERVICE_NAME` env var. Alternatively, use the same service explicit value.
-2. **Changing state before a parent instantiate**. Using `logger.append_keys` or `logger.remove_keys` without a parent Logger will lead to `OrphanedChildLoggerError` exception.
-    * Solution: always initialize parent Loggers first. Alternatively, move calls to `append_keys`/`remove_keys` from the child at a later stage.
+???+ tip
+    This can be fixed by either ensuring both has the `service` value as `payment`, or simply use the environment variable `POWERTOOLS_SERVICE_NAME` to ensure service value will be the same across all Loggers when not explicitly set.
 
-=== "logging_inheritance_bad.py"
+Do this instead:
+
+=== "logging_inheritance_good.py"
 
     ```python hl_lines="1 9"
-    --8<-- "examples/logger/src/logging_inheritance_bad.py"
+    --8<-- "examples/logger/src/logging_inheritance_good.py"
     ```
 
 === "logging_inheritance_module.py"
@@ -811,10 +813,11 @@ for the given name and level to the logging module. By default, this logs all bo
 
 You can copy the Logger setup to all or sub-sets of registered external loggers. Use the `copy_config_to_registered_logger` method to do this.
 
-???+ tip
-    To help differentiate between loggers, we include the standard logger `name` attribute for all loggers we copied configuration to.
+!!! tip "We include the logger `name` attribute for all loggers we copied configuration to help you differentiate them."
+
+By default all registered loggers will be modified. You can change this behavior by providing `include` and `exclude` attributes.
 
-By default all registered loggers will be modified. You can change this behavior by providing `include` and `exclude` attributes. You can also provide optional `log_level` attribute external loggers will be configured with.
+You can also provide optional `log_level` attribute external top-level loggers will be configured with, by default it'll use the source logger log level. You can opt-out by using `ignore_log_level=True` parameter.
 
 ```python hl_lines="10" title="Cloning Logger config to all other registered standard loggers"
 ---8<-- "examples/logger/src/cloning_logger_config.py"