improv: update docs, linting

Author: heitorlessa

python/aws_lambda_powertools/metrics/exceptions.py

@@ -1,14 +1,22 @@
 class MetricUnitError(Exception):
+    """When metric unit is not supported by CloudWatch"""
+
     pass
 
 
 class SchemaValidationError(Exception):
+    """When serialization fail schema validation"""
+
     pass
 
 
 class MetricValueError(Exception):
+    """When metric value isn't a valid number"""
+
     pass
 
 
 class UniqueNamespaceError(Exception):
+    """When an additional namespace is set"""
+
     pass

python/aws_lambda_powertools/middleware_factory/exceptions.py

@@ -1,2 +1,4 @@
 class MiddlewareInvalidArgumentError(Exception):
+    """When middleware receives non keyword=arguments"""
+
     pass

python/aws_lambda_powertools/tracing/base.py

@@ -1,11 +1,8 @@
 from __future__ import annotations
 
 import abc
-import copy
-import functools
 import logging
-import os
-from typing import Any, Callable, List
+from typing import Any, List
 
 import aws_xray_sdk
 import aws_xray_sdk.core
@@ -20,7 +17,14 @@ class TracerProvider(metaclass=abc.ABCMeta):
     Providers should be initialized independently. This
     allows providers to control their config/initialization,
     and only pass a class instance to
-    ```aws_lambda_powertools.tracing.tracer.Tracer```.
+    `aws_lambda_powertools.tracing.tracer.Tracer`.
+
+    It also allows custom providers to keep lean while Tracer provide:
+
+    * a simplified UX
+    * decorators for Lambda handler and methods
+    * auto-patching, patch all modules by default or a subset
+    * disabling all tracing operations with a single parameter or env var
 
     Trace providers should implement the following methods:
 
@@ -32,10 +36,17 @@ class TracerProvider(metaclass=abc.ABCMeta):
     * **disable_tracing_provider**
 
     These methods will be called by
-    ```aws_lambda_powertools.tracing.tracer.Tracer```.
-    See ```aws_lambda_powertools.tracing.base.XrayProvider```
+    `aws_lambda_powertools.tracing.tracer.Tracer` -
+    See `aws_lambda_powertools.tracing.base.XrayProvider`
     for a reference implementation.
 
+    `aws_lambda_powertools.tracing.tracer.Tracer` decorators
+    for Lambda and methods use the following provider methods:
+
+    * create_subsegment
+    * put_metadata
+    * end_subsegment
+
     Example
     -------
     **Client using a custom tracing provider**
@@ -112,6 +123,17 @@ def disable_tracing_provider(self):
 
 
 class XrayProvider(TracerProvider):
+    """X-Ray Tracer provider
+
+    It implements all basic ``aws_lambda_powertools.tracing.base.TracerProvider` methods,
+    and automatically annotates cold start on first subsegment created.
+
+    Parameters
+    ----------
+    client : aws_xray_sdk.core.xray_recorder
+        X-Ray recorder client
+    """
+
     def __init__(self, client: aws_xray_sdk.core.xray_recorder = aws_xray_sdk.core.xray_recorder):
         self.client = client
 

python/aws_lambda_powertools/tracing/exceptions.py

@@ -1,5 +1,10 @@
 class InvalidTracerProviderError(Exception):
+    """When given provider doesn't implement `aws_lambda_powertools.tracing.base.TracerProvider`"""
+
     pass
 
+
 class TracerProviderNotInitializedError(Exception):
+    """When given provider isn't initialized/bound"""
+
     pass

python/aws_lambda_powertools/tracing/tracer.py

@@ -4,11 +4,12 @@
 import logging
 import os
 from distutils.util import strtobool
-from typing import Any, Callable, Dict, List
+from typing import Any, Callable, Dict, Generic, List, TypeVar
 
 from .base import TracerProvider, XrayProvider
 from .exceptions import InvalidTracerProviderError, TracerProviderNotInitializedError
 
+subsegment = TypeVar("subsegment")
 is_cold_start = True
 logger = logging.getLogger(__name__)
 
@@ -27,6 +28,9 @@ class Tracer:
     is useful when you are using your own middlewares and want to utilize an existing Tracer.
     Make sure to set `auto_patch=False` in subsequent Tracer instances to avoid double patching.
 
+    Tracer supports custom providers that implement
+    `aws_lambda_powertools.tracing.base.TracerProvider`.
+
     Environment variables
     ---------------------
     POWERTOOLS_TRACE_DISABLED : str
@@ -115,6 +119,13 @@ def handler(event: dict, context: Any) -> Dict:
     Tracer
         Tracer instance with imported modules patched
 
+    Raises
+    ------
+    InvalidTracerProviderError
+        When given provider doesn't implement `aws_lambda_powertools.tracing.base.TracerProvider`
+    TracerProviderNotInitializedError
+        When given provider isn't initialized/bound
+
     Limitations
     -----------
     * Async handler and methods not supported
@@ -152,7 +163,7 @@ def __init__(
         if self.auto_patch:
             self.patch(modules=patch_modules)
 
-    def create_subsegment(self, name: str):
+    def create_subsegment(self, name: str) -> Generic[subsegment]:
         """Creates subsegment/span with a given name
 
         It also assumes Tracer would be instantiated statically so that cold starts are captured.
@@ -168,11 +179,10 @@ def create_subsegment(self, name: str):
 
             self.create_subsegment(name="a meaningful name")
 
-        # FIXME - Return Subsegment Any type
         Returns
         -------
-        models.subsegment
-            AWS X-Ray Subsegment
+        subsegment
+            Trace provider subsegment
         """
         # Will no longer be needed once #155 is resolved
         # https://github.com/aws/aws-xray-sdk-python/issues/155
@@ -204,7 +214,7 @@ def put_annotation(self, key: str, value: Any):
         ----------
         key : str
             Annotation key (e.g. PaymentStatus)
-        value : Any
+        value : any
             Value for annotation (e.g. "CONFIRMED")
         """
         # Will no longer be needed once #155 is resolved
@@ -216,14 +226,14 @@ def put_annotation(self, key: str, value: Any):
         logger.debug(f"Annotating on key '{key}'' with '{value}''")
         self.provider.put_annotation(key=key, value=value)
 
-    def put_metadata(self, key: str, value: object, namespace: str = None):
+    def put_metadata(self, key: str, value: Any, namespace: str = None):
         """Adds metadata to existing segment or subsegment
 
         Parameters
         ----------
         key : str
             Metadata key
-        value : object
+        value : any
             Value for metadata
         namespace : str, optional
             Namespace that metadata will lie under, by default None
@@ -285,7 +295,6 @@ def handler(event, context)
         @functools.wraps(lambda_handler)
         def decorate(event, context):
             self.create_subsegment(name=f"## {lambda_handler.__name__}")
-
             try:
                 logger.debug("Calling lambda handler")
                 response = lambda_handler(event, context)