feature: extract code examples to python files (#24)

ran-isenberg · web-flow · commit 9c4c6440fd49 · 2022-04-18T21:34:51.000+03:00
diff --git a/.flake8 b/.flake8
@@ -1,5 +1,5 @@
 [flake8]
-exclude = docs, .eggs, setup.py, example, .cdk,out, .git, dist, *.md, *.yaml, *.txt, *.ini
+exclude = .eggs, setup.py, example, .cdk,out, .git, dist, *.md, *.yaml, *.txt, *.ini
 ignore = E203, E266, W503, BLK100, W291, I004
 max-line-length = 150
 max-complexity = 15
diff --git a/Makefile b/Makefile
@@ -8,7 +8,7 @@ dev:
 
 lint:
 	@echo "Running flake8"
-	flake8 service/* tests/*
+	flake8 service/* tests/* docs/examples/*
 
 complex:
 	@echo "Running Radon"
diff --git a/docs/best_practices/environment_variables.md b/docs/best_practices/environment_variables.md
@@ -27,20 +27,10 @@ Read more about the importance of validating environment variables and how this
 You need to define all your environment variables in a Pydantic schema class that extend Pydantic's BaseModel class.
 
 For example:
-=== "schemas/env_vars.py"
 
-    ```python hl_lines="5"
-    from typing import Literal
-
-    from pydantic import BaseModel, HttpUrl, constr
-
-    class MyHandlerEnvVars(BaseModel):
-        REST_API: HttpUrl
-        ROLE_ARN: constr(min_length=20, max_length=2048)
-        POWERTOOLS_SERVICE_NAME: constr(min_length=1)
-        LOG_LEVEL: Literal['DEBUG', 'INFO', 'ERROR', 'CRITICAL', 'WARNING', 'EXCEPTION']
-
-    ```
+```python hl_lines="6" title="schemas/env_vars.py"
+--8<-- "docs/examples/best_practices/environment_variables/env_vars.py"
+```
 
 All Pydantic schemas extend Pydantic’s ‘BaseModel’ class, turning them into a dataclass.
 
@@ -60,23 +50,10 @@ The decorator 'init_environment_variables' is defined under the utility folder *
 
 The decorator requires a **model** parameter, which in this example is the name of the schema class we defined above.
 
-=== "handlers/my_handler.py"
-
-    ```python hl_lines="11"
-    import json
-    from http import HTTPStatus
-    from typing import Any, Dict
-
-    from aws_lambda_powertools.utilities.typing import LambdaContext
-
-    from service.handlers.schemas.env_vars import MyHandlerEnvVars
-    from service.handlers.utils.env_vars_parser import init_environment_variables
-
 
-    @init_environment_variables(model=MyHandlerEnvVars)
-    def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
-        return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
-    ```
+```python hl_lines="11" title="handlers/my_handler.py"
+--8<-- "docs/examples/best_practices/environment_variables/my_handler.py"
+```
 
 ## **Global Getter Usage**
 The getter function 'get_environment_variables' is defined under the utility folder **service.utils.env_vars_parser.py** and imported in the handler.
@@ -85,25 +62,9 @@ The getter function returns a parsed and validated global instance of the enviro
 
 It can be used *anywhere* in the function code, not just the handler.
 
-=== "handlers/my_handler.py"
-
-    ```python hl_lines="13"
-    import json
-    from http import HTTPStatus
-    from typing import Any, Dict
-
-    from aws_lambda_powertools.utilities.typing import LambdaContext
-
-    from service.handlers.schemas.env_vars import MyHandlerEnvVars
-    from service.handlers.utils.env_vars_parser import get_environment_variables, init_environment_variables
-
-
-    @init_environment_variables(model=MyHandlerEnvVars)
-    def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
-        env_vars: MyHandlerEnvVars = get_environment_variables(model=MyHandlerEnvVars)
-        return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
-    ```
-
+```python hl_lines="13" title="handlers/my_handler.py"
+--8<-- "docs/examples/best_practices/environment_variables/getter.py"
+```
 
 
 ## **More Details**
diff --git a/docs/best_practices/input_validation.md b/docs/best_practices/input_validation.md
@@ -69,29 +69,9 @@ The parser is a called with the function 'parse'.
 
 Use the envelope class that matches the AWS service that triggers your AWS Lambda function.
 
-=== "my_handler.py"
-
-    ```python hl_lines="14"
-    from typing import Any, Dict
-
-    from aws_lambda_powertools.utilities.parser import ValidationError, parse
-    from aws_lambda_powertools.utilities.parser.envelopes import ApiGatewayEnvelope
-    from aws_lambda_powertools.utilities.typing import LambdaContext
-
-    from service.handlers.schemas.input import Input
-
-
-    def my_handler(event: Dict[str, Any], context: LambdaContext):
-        # validate input
-        try:
-            # we want to extract and parse the HTTP body from the api gw envelope
-            input: Input = parse(event=event, model=Input, envelope=ApiGatewayEnvelope)
-        except (ValidationError, TypeError) as err:
-            # log error, return BAD_REQUEST
-
-        # process input
-
-    ```
+```python hl_lines="13" title="my_handler.py"
+--8<-- "docs/examples/best_practices/input_validation/my_handler.py"
+```
 
 ## Accessing Envelope Metadata
 
diff --git a/docs/best_practices/logger.md b/docs/best_practices/logger.md
@@ -14,7 +14,10 @@ It’s a wrapper of Python’s logging library that provides extra capabilities
 
 
 ## **Usage in Handler**
-The logger is a singleton which is defined under the utility folder **service.utils.observability.py** and imported in the handler.
+
+```python hl_lines="8 12 13" title="my_handler.py"
+--8<-- "docs/examples/best_practices/logger/my_handler.py"
+```
 
 ## **Blog Reference**
 Read more about the importance of the logger and how to use AWS CloudWatch logs in my blog. Click [**HERE**](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-1-logging){:target="_blank" rel="noopener"}
diff --git a/docs/best_practices/metrics.md b/docs/best_practices/metrics.md
@@ -20,7 +20,10 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://cons
 
 
 ## **Usage in Handler**
-The metrics is a singleton which is defined under the utility folder **service.utils.observability.py** and imported in the handler.
+
+```python hl_lines="11 14 16" title="my_handler.py"
+--8<-- "docs/examples/best_practices/metrics/my_handler.py"
+```
 
 ## **Blog Reference**
 Read more about the importance of the business KPis and metrics in my blog. Click [**HERE**](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-3-business-domain-observability){:target="_blank" rel="noopener"}
diff --git a/docs/best_practices/tracer.md b/docs/best_practices/tracer.md
@@ -14,7 +14,10 @@ Tracer is a thin wrapper for [AWS X-Ray Python SDK](https://github.com/aws/aws-x
 
 
 ## **Usage in Handler**
-The tracer is a singleton which is defined under the utility folder **service.utils.observability.py** and imported in the handler.
+
+```python hl_lines="11 14 19" title="my_handler.py"
+--8<-- "docs/examples/best_practices/tracer/my_handler.py"
+```
 
 ## **Blog Reference**
 Read more about the importance of observability and traces in my blog. Click [**HERE**](https://www.ranthebuilder.cloud/post/aws-lambda-cookbook-elevate-your-handler-s-code-part-2-observability){:target="_blank" rel="noopener"}
diff --git a/docs/examples/best_practices/environment_variables/env_vars.py b/docs/examples/best_practices/environment_variables/env_vars.py
@@ -0,0 +1,10 @@
+from typing import Literal
+
+from pydantic import BaseModel, HttpUrl, constr
+
+
+class MyHandlerEnvVars(BaseModel):
+    REST_API: HttpUrl
+    ROLE_ARN: constr(min_length=20, max_length=2048)
+    POWERTOOLS_SERVICE_NAME: constr(min_length=1)
+    LOG_LEVEL: Literal['DEBUG', 'INFO', 'ERROR', 'CRITICAL', 'WARNING', 'EXCEPTION']
diff --git a/docs/examples/best_practices/environment_variables/getter.py b/docs/examples/best_practices/environment_variables/getter.py
@@ -0,0 +1,14 @@
+import json
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+from service.handlers.schemas.env_vars import MyHandlerEnvVars
+from service.handlers.utils.env_vars_parser import get_environment_variables, init_environment_variables
+
+
+@init_environment_variables(model=MyHandlerEnvVars)
+def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
+    env_vars: MyHandlerEnvVars = get_environment_variables(model=MyHandlerEnvVars)  # noqa: F841
+    return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
diff --git a/docs/examples/best_practices/environment_variables/my_handler.py b/docs/examples/best_practices/environment_variables/my_handler.py
@@ -0,0 +1,14 @@
+import json
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+from service.handlers.schemas.env_vars import MyHandlerEnvVars
+from service.handlers.utils.env_vars_parser import get_environment_variables, init_environment_variables
+
+
+@init_environment_variables(model=MyHandlerEnvVars)
+def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
+    env_vars: MyHandlerEnvVars = get_environment_variables(model=MyHandlerEnvVars)  # noqa: F841
+    return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
diff --git a/docs/examples/best_practices/input_validation/my_handler.py b/docs/examples/best_practices/input_validation/my_handler.py
@@ -0,0 +1,17 @@
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.parser import ValidationError, parse
+from aws_lambda_powertools.utilities.parser.envelopes import ApiGatewayEnvelope
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+from service.handlers.schemas.input import Input
+
+
+def my_handler(event: Dict[str, Any], context: LambdaContext):
+    try:
+        input: Input = parse(event=event, model=Input, envelope=ApiGatewayEnvelope)  # noqa: F841
+    except (ValidationError, TypeError):
+        # log error, return BAD_REQUEST
+        return {'statusCode': HTTPStatus.BAD_REQUEST}
+    # process input
diff --git a/docs/examples/best_practices/logger/my_handler.py b/docs/examples/best_practices/logger/my_handler.py
@@ -0,0 +1,14 @@
+import json
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.logging.logger import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger: Logger = Logger(service='my_service')  # JSON output format, service name can be set by environment variable "POWERTOOLS_SERVICE_NAME"
+
+
+def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
+    logger.set_correlation_id(context.aws_request_id)
+    logger.debug('my_handler is called')
+    return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
diff --git a/docs/examples/best_practices/metrics/my_handler.py b/docs/examples/best_practices/metrics/my_handler.py
@@ -0,0 +1,17 @@
+import json
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.metrics.metrics import Metrics, MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+SERVICE_NAME = 'my_service'
+
+# namespace and service name can be set by environment variable "POWERTOOLS_METRICS_NAMESPACE" and "POWERTOOLS_SERVICE_NAME" accordingly
+metrics = Metrics(namespace='my_product_kpi', service=SERVICE_NAME)
+
+
+@metrics.log_metrics
+def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
+    metrics.add_metric(name='ValidEvents', unit=MetricUnit.Count, value=1)
+    return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
diff --git a/docs/examples/best_practices/tracer/my_handler.py b/docs/examples/best_practices/tracer/my_handler.py
@@ -0,0 +1,22 @@
+import json
+from http import HTTPStatus
+from typing import Any, Dict
+
+from aws_lambda_powertools.tracing.tracer import Tracer
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+SERVICE_NAME = 'my_service'
+
+# service name can be set by environment variable "POWERTOOLS_SERVICE_NAME". Disabled by setting POWERTOOLS_TRACE_DISABLED to "True"
+tracer: Tracer = Tracer(service=SERVICE_NAME)
+
+
+@tracer.capture_method(capture_response=False)
+def inner_function_example(event: Dict[str, Any]) -> Dict[str, Any]:
+    return {}
+
+
+@tracer.capture_lambda_handler(capture_response=False)
+def my_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
+    inner_function_example(event)
+    return {'statusCode': HTTPStatus.OK, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps({'message': 'success'})}
