feat: add high level imports

.flake8

@@ -1,5 +1,5 @@
 [flake8]
-exclude = docs, .eggs, setup.py, example, .aws-sam
+exclude = docs, .eggs, setup.py, example, .aws-sam, .git, dist, *.md, *.yaml, example/samconfig.toml, *.txt, *.ini
 ignore = E203, E266, W503, BLK100, W291, I004
 max-line-length = 120
 max-complexity = 15

.pre-commit-config.yaml

@@ -35,4 +35,3 @@ repos:
             language: system
             types: [python]
             exclude: example
-fail_fast: true

Makefile

@@ -15,7 +15,7 @@ format:
 	poetry run black aws_lambda_powertools tests
 
 lint: format
-	poetry run flake8
+	poetry run flake8 aws_lambda_powertools/* tests/* example/*
 
 test:
 	poetry run pytest -vvv --cov=./ --cov-report=xml

aws_lambda_powertools/__init__.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
 """Top-level package for Lambda Python Powertools."""
-import logging
+
+
+from .logging import Logger  # noqa: F401
+from .metrics import Metrics, single_metric  # noqa: F401
+from .package_logger import set_package_logger_handler
+from .tracing import Tracer  # noqa: F401
 
 __author__ = """Amazon Web Services"""
 
-logger = logging.getLogger("aws_lambda_powertools")
-logger.addHandler(logging.NullHandler())
-logger.propagate = False
+set_package_logger_handler()

aws_lambda_powertools/logging/logger.py

@@ -125,7 +125,7 @@ def logger_setup(
     -------
         **Logger class - Same UX**
 
-        from aws_lambda_powertools.logging import Logger
+        from aws_lambda_powertools import Logger
         logger = Logger(service="payment") # same env var still applies
 
     """
@@ -143,7 +143,7 @@ def logger_inject_lambda_context(
     -------
         **Logger class - Same UX**
 
-        from aws_lambda_powertools.logging import Logger
+        from aws_lambda_powertools import Logger
         logger = Logger(service="payment") # same env var still applies
         @logger.inject_lambda_context
         def handler(evt, ctx):
@@ -307,7 +307,7 @@ class Logger(logging.Logger):
     -------
     **Setups structured logging in JSON for Lambda functions with explicit service name**
 
-        >>> from aws_lambda_powertools.logging import Logger
+        >>> from aws_lambda_powertools import Logger
         >>> logger = Logger(service="payment")
         >>>
         >>> def handler(event, context):
@@ -317,15 +317,15 @@ class Logger(logging.Logger):
 
         $ export POWERTOOLS_SERVICE_NAME="payment"
         $ export POWERTOOLS_LOGGER_SAMPLE_RATE=0.01 # 1% debug sampling
-        >>> from aws_lambda_powertools.logging import Logger
+        >>> from aws_lambda_powertools import Logger
         >>> logger = Logger()
         >>>
         >>> def handler(event, context):
                 logger.info("Hello")
 
     **Append payment_id to previously setup structured log logger**
 
-        >>> from aws_lambda_powertools.logging import Logger
+        >>> from aws_lambda_powertools import Logger
         >>> logger = Logger(service="payment")
         >>>
         >>> def handler(event, context):
@@ -398,7 +398,7 @@ def inject_lambda_context(self, lambda_handler: Callable[[Dict, Any], Any] = Non
         -------
         **Captures Lambda contextual runtime info (e.g memory, arn, req_id)**
 
-            from aws_lambda_powertools.logging import Logger
+            from aws_lambda_powertools import Logger
 
             logger = Logger(service="payment")
 
@@ -408,7 +408,7 @@ def handler(event, context):
 
         **Captures Lambda contextual runtime info and logs incoming request**
 
-            from aws_lambda_powertools.logging import Logger
+            from aws_lambda_powertools import Logger
 
             logger = Logger(service="payment")
 

aws_lambda_powertools/metrics/__init__.py

@@ -1,7 +1,6 @@
 """CloudWatch Embedded Metric Format utility
 """
-from aws_lambda_powertools.helper.models import MetricUnit
-
+from ..helper.models import MetricUnit
 from .exceptions import MetricUnitError, MetricValueError, SchemaValidationError, UniqueNamespaceError
 from .metric import single_metric
 from .metrics import Metrics

aws_lambda_powertools/metrics/base.py

@@ -9,8 +9,7 @@
 
 import fastjsonschema
 
-from aws_lambda_powertools.helper.models import MetricUnit
-
+from ..helper.models import MetricUnit
 from .exceptions import MetricUnitError, MetricValueError, SchemaValidationError, UniqueNamespaceError
 
 logger = logging.getLogger(__name__)

aws_lambda_powertools/metrics/metric.py

@@ -3,8 +3,8 @@
 from contextlib import contextmanager
 from typing import Dict
 
-from aws_lambda_powertools.helper.models import MetricUnit
-from aws_lambda_powertools.metrics.base import MetricManager
+from ..helper.models import MetricUnit
+from .base import MetricManager
 
 logger = logging.getLogger(__name__)
 
@@ -69,7 +69,8 @@ def single_metric(name: str, unit: MetricUnit, value: float, namespace: str = No
     -------
     **Creates cold start metric with function_version as dimension**
 
-        from aws_lambda_powertools.metrics import single_metric, MetricUnit
+        from aws_lambda_powertools import single_metric
+        from aws_lambda_powertools.metrics import MetricUnit
 
         with single_metric(name="ColdStart", unit=MetricUnit.Count, value=1, namespace="ServerlessAirline") as metric:
                 metric.add_dimension(name="function_version", value=47)
@@ -78,7 +79,8 @@ def single_metric(name: str, unit: MetricUnit, value: float, namespace: str = No
 
         $ export POWERTOOLS_METRICS_NAMESPACE="ServerlessAirline"
 
-        from aws_lambda_powertools.metrics import single_metric, MetricUnit
+        from aws_lambda_powertools import single_metric
+        from aws_lambda_powertools.metrics import MetricUnit
 
         with single_metric(name="ColdStart", unit=MetricUnit.Count, value=1) as metric:
                 metric.add_dimension(name="function_version", value=47)

aws_lambda_powertools/metrics/metrics.py

@@ -4,7 +4,7 @@
 import os
 from typing import Any, Callable
 
-from aws_lambda_powertools.metrics.base import MetricManager
+from .base import MetricManager
 
 logger = logging.getLogger(__name__)
 
@@ -30,7 +30,7 @@ class Metrics(MetricManager):
     -------
     **Creates a few metrics and publish at the end of a function execution**
 
-        from aws_lambda_powertools.metrics import Metrics
+        from aws_lambda_powertools import Metrics
 
         metrics = Metrics(namespace="ServerlessAirline", service="payment")
         metrics.add_metric(name="ColdStart", unit=MetricUnit.Count, value=1)

aws_lambda_powertools/middleware_factory/factory.py

@@ -76,7 +76,7 @@ def lambda_handler(event, context):
 
     **Trace execution of custom middleware**
 
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
 
         tracer = Tracer(service="payment") # or via env var

aws_lambda_powertools/package_logger.py

@@ -0,0 +1,7 @@
+import logging
+
+
+def set_package_logger_handler():
+    logger = logging.getLogger("aws_lambda_powertools")
+    logger.addHandler(logging.NullHandler())
+    logger.propagate = False

aws_lambda_powertools/tracing/tracer.py

@@ -50,7 +50,7 @@ class Tracer:
     -------
     **A Lambda function using Tracer**
 
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         tracer = Tracer(service="greeting")
 
         @tracer.capture_method
@@ -67,7 +67,7 @@ def handler(event: dict, context: Any) -> Dict:
 
     **Booking Lambda function using Tracer that adds additional annotation/metadata**
 
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         tracer = Tracer(service="booking")
 
         @tracer.capture_method
@@ -89,7 +89,7 @@ def handler(event: dict, context: Any) -> Dict:
     **A Lambda function using service name via POWERTOOLS_SERVICE_NAME**
 
         export POWERTOOLS_SERVICE_NAME="booking"
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         tracer = Tracer()
 
         @tracer.capture_lambda_handler
@@ -101,15 +101,15 @@ def handler(event: dict, context: Any) -> Dict:
     **Reuse an existing instance of Tracer anywhere in the code**
 
         # lambda_handler.py
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         tracer = Tracer()
 
         @tracer.capture_lambda_handler
         def handler(event: dict, context: Any) -> Dict:
             ...
 
         # utils.py
-        from aws_lambda_powertools.tracing import Tracer
+        from aws_lambda_powertools import Tracer
         tracer = Tracer()
         ...
 
@@ -301,7 +301,7 @@ def some_function()
 
         **Custom async method using capture_method decorator**
 
-            from aws_lambda_powertools.tracing import Tracer
+            from aws_lambda_powertools import Tracer
             tracer = Tracer(service="booking")
 
             @tracer.capture_method
@@ -319,7 +319,7 @@ def lambda_handler(event: dict, context: Any) -> Dict:
 
         **Tracing nested async calls**
 
-            from aws_lambda_powertools.tracing import Tracer
+            from aws_lambda_powertools import Tracer
             tracer = Tracer(service="booking")
 
             @tracer.capture_method
@@ -341,7 +341,7 @@ async def async_tasks():
 
         This may not needed once [this bug is closed](https://github.com/aws/aws-xray-sdk-python/issues/164)
 
-            from aws_lambda_powertools.tracing import Tracer
+            from aws_lambda_powertools import Tracer
             tracer = Tracer(service="booking")
 
             async def get_identity():
@@ -362,7 +362,7 @@ async def async_tasks():
 
         This may not needed once [this bug is closed](https://github.com/aws/aws-xray-sdk-python/issues/164)
 
-            from aws_lambda_powertools.tracing import Tracer
+            from aws_lambda_powertools import Tracer
             tracer = Tracer(service="booking")
 
             async def get_identity():

docs/content/core/logger.mdx

@@ -37,7 +37,7 @@ By default, Logger uses **INFO** log level. You can either change log level via
 You can also explicitly set a service name via `service` param or via `POWERTOOLS_SERVICE_NAME` env var. This sets **service** key that will be present across all log statements.
 
 ```python:title=app.py
-from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools import Logger
 # POWERTOOLS_SERVICE_NAME defined
 logger = Logger() # highlight-line
 
@@ -63,7 +63,7 @@ Key | Type | Example | Description
 You can enrich your structured logs with key Lambda context information via `inject_lambda_context`.
 
 ```python:title=collect.py
-from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools import Logger
 
 logger = Logger()
 
@@ -86,7 +86,7 @@ You can also explicitly log any incoming event using `log_event` param or via `P
 </Note><br/>
 
 ```python:title=log_handler_event.py
-from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools import Logger
 
 logger = Logger()
 
@@ -151,7 +151,7 @@ Key | Type | Example
 You can append your own keys to your existing Logger via `structure_logs` with **append** param.
 
 ```python:title=collect.py
-from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools import Logger
 
 logger = Logger()
 
@@ -194,7 +194,7 @@ This happens on an entire request basis, and <strong>DEBUG</strong> level is set
 </Note><br/>
 
 ```python:title=collect.py
-from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools import Logger
 
 # Sample 1% of debug logs e.g. 0.1
 logger = Logger(sample_rate=0.1) # highlight-line

docs/content/core/metrics.mdx

@@ -36,7 +36,8 @@ You can explicitly set a namespace name via `namespace` param or via `POWERTOOLS
 You can also pass a service name via `service` param or `POWERTOOLS_SERVICE_NAME` env var. This will create a dimension with the service name.
 
 ```python:title=app.py
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 # POWERTOOLS_METRICS_NAMESPACE and POWERTOOLS_SERVICE_NAME defined
 metrics = Metrics() # highlight-line
@@ -54,7 +55,8 @@ You can initialize Metrics anywhere in your code as many times as you need - It'
 You can create metrics using `add_metric`, and manually create dimensions for all your aggregate metrics using `add_dimension`.
 
 ```python:title=app.py
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 metrics = Metrics(namespace="ExampleApplication", service="booking")
 # highlight-start
@@ -79,7 +81,8 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `single_met
 
 
 ```python:title=single_metric.py
-from aws_lambda_powertools.metrics import MetricUnit, single_metric
+from aws_lambda_powertools import single_metric
+from aws_lambda_powertools.metrics import MetricUnit
 
 with single_metric(name="ColdStart", unit=MetricUnit.Count, value=1, namespace="ExampleApplication") as metric: # highlight-line
     metric.add_dimension(name="function_context", value="$LATEST")
@@ -91,7 +94,8 @@ with single_metric(name="ColdStart", unit=MetricUnit.Count, value=1, namespace="
 As you finish adding all your metrics, you need to serialize and flush them to standard output. You can do that right before you return your response to the caller via `log_metrics`.
 
 ```python:title=lambda_handler.py
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 metrics = Metrics(service="ExampleService")
 metrics.add_metric(name="ColdStart", unit="Count", value=1)
@@ -115,7 +119,8 @@ def lambda_handler(evt, ctx):
 </Note><br/>
 
 ```python:title=lambda_handler_nested_middlewares.py
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 metrics = Metrics(namespace="ExampleApplication", service="booking")
 metrics.add_metric(name="ColdStart", unit="Count", value=1)
@@ -135,7 +140,8 @@ If you prefer not to use `log_metrics` because you might want to encapsulate add
 
 ```python:title=manual_metric_serialization.py
 import json
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 metrics = Metrics(namespace="ExampleApplication", service="booking")
 metrics.add_metric(name="ColdStart", unit="Count", value=1)
@@ -152,7 +158,8 @@ print(json.dumps(your_metrics_object))
 You can capture cold start metrics automatically with `log_metrics` via `capture_cold_start_metric` param.
 
 ```python:title=lambda_handler.py
-from aws_lambda_powertools.metrics import Metrics, MetricUnit
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
 
 metrics = Metrics(service="ExampleService")