docs(lint): adjust markdownlint to our current conventions

Author: heitorlessa

.markdownlint.yaml

@@ -32,7 +32,7 @@ MD006: true
 # MD007/ul-indent - Unordered list indentation
 MD007:
   # Spaces for indent
-  indent: 2
+  indent: 4
   # Whether to indent the first level of the list
   start_indented: false
   # Spaces for first level indent (when start_indented is set)
@@ -66,7 +66,7 @@ MD013:
   # Number of characters for headings
   heading_line_length: 80
   # Number of characters for code blocks
-  code_block_line_length: 180
+  code_block_line_length: 265
   # Include code blocks
   code_blocks: true
   # Include tables

docs/changelog.md

@@ -1,2 +1,4 @@
 [comment]: <> (Includes Changelog content entire file as a snippet)
+<!-- changelog is partially generated, so it doesn't follow headings and required structure, so we disable it. -->
+<!-- markdownlint-disable -->
 --8<-- "CHANGELOG.md"

docs/core/event_handler/api_gateway.md

@@ -18,10 +18,12 @@ Event handler for Amazon API Gateway REST and HTTP APIs, and Application Loader
 
 ### Required resources
 
-You must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"} or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} configured to invoke your Lambda function. There is no additional permissions or dependencies required to use this utility.
+You must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"} or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} configured to invoke your Lambda function.
 
 This is the sample infrastructure for API Gateway we are using for the examples in this documentation.
 
+???+ info "There is no additional permissions or dependencies required to use this utility."
+
 ```yaml title="AWS Serverless Application Model (SAM) example"
 AWSTemplateFormatVersion: '2010-09-09'
 Transform: AWS::Serverless-2016-10-31
@@ -35,7 +37,7 @@ Globals:
 		AllowHeaders: "'Content-Type,Authorization,X-Amz-Date'"
 		MaxAge: "'300'"
 	BinaryMediaTypes:               # see Binary responses section
-		- '*~1*'  # converts to */* for any binary type
+		- '*~1*'                    # converts to */* for any binary type
 	Function:
 	Timeout: 5
 	Runtime: python3.8
@@ -59,8 +61,11 @@ Resources:
 			ApiEvent:
 				Type: Api
 				Properties:
-				Path: /{proxy+}  # Send requests on any path to the lambda function
-				Method: ANY  # Send requests using any http method to the lambda function
+                    # NOTE: this is a catch-all rule to simply the documentation.
+                    # explicit routes and methods are recommended for prod instead
+                    # for example, Path: /hello, Method: GET
+				    Path: /{proxy+}  # Send requests on any path to the lambda function
+				    Method: ANY  # Send requests using any http method to the lambda function
 ```
 
 ### Event Resolvers
@@ -355,7 +360,9 @@ You can also combine nested paths with greedy regex to catch in between routes.
         ...
     }
     ```
+
 ### HTTP Methods
+
 You can use named decorators to specify the HTTP method that should be handled in your functions. As well as the
 `get` method already shown above, you can use `post`, `put`, `patch`, `delete`, and `patch`.
 
@@ -487,7 +494,6 @@ def lambda_handler(event, context):
 	return app.resolve(event, context)
 ```
 
-
 ### Handling not found routes
 
 By default, we return `404` for any unmatched route.
@@ -528,7 +534,6 @@ def lambda_handler(event, context):
 	return app.resolve(event, context)
 ```
 
-
 ### Exception handling
 
 You can use **`exception_handler`** decorator with any Python exception. This allows you to handle a common exception outside your route, for example validation errors.
@@ -754,13 +759,13 @@ For convenience, these are the default values when using `CORSConfig` to enable
 ???+ warning
     Always configure `allow_origin` when using in production.
 
-Key | Value | Note
-------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------
-**[allow_origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank"}**: `str` | `*` | Only use the default value for development. **Never use `*` for production** unless your use case requires it
-**[allow_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers){target="_blank"}**: `List[str]` | `[Authorization, Content-Type, X-Amz-Date, X-Api-Key, X-Amz-Security-Token]` | Additional headers will be appended to the default list for your convenience
-**[expose_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers){target="_blank"}**: `List[str]` | `[]` | Any additional header beyond the [safe listed by CORS specification](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header){target="_blank"}.
-**[max_age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age){target="_blank"}**: `int` | `` | Only for pre-flight requests if you choose to have your function to handle it instead of API Gateway
-**[allow_credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials){target="_blank"}**: `bool` | `False` | Only necessary when you need to expose cookies, authorization headers or TLS client certificates.
+| Key                                                                                                                                          | Value                                                                        | Note                                                                                                                                                                      |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[allow_origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank"}**: `str`            | `*`                                                                          | Only use the default value for development. **Never use `*` for production** unless your use case requires it                                                             |
+| **[allow_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers){target="_blank"}**: `List[str]`    | `[Authorization, Content-Type, X-Amz-Date, X-Api-Key, X-Amz-Security-Token]` | Additional headers will be appended to the default list for your convenience                                                                                              |
+| **[expose_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers){target="_blank"}**: `List[str]`  | `[]`                                                                         | Any additional header beyond the [safe listed by CORS specification](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header){target="_blank"}. |
+| **[max_age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age){target="_blank"}**: `int`                      | ``                                                                           | Only for pre-flight requests if you choose to have your function to handle it instead of API Gateway                                                                      |
+| **[allow_credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials){target="_blank"}**: `bool` | `False`                                                                      | Only necessary when you need to expose cookies, authorization headers or TLS client certificates.                                                                         |
 
 ### Fine grained responses
 
@@ -1132,7 +1137,6 @@ This sample project contains a Users function with two distinct set of routes, `
 
 === "Project layout"
 
-
     ```python hl_lines="1 8 10 12-15"
     .
     ├── Pipfile                    # project app & dev dependencies; poetry, pipenv, etc.
@@ -1308,7 +1312,7 @@ _**Downsides**_
 
 * **Cold starts**. Frequent deployments and/or high load can diminish the benefit of monolithic functions depending on your latency requirements, due to [Lambda scaling model](https://docs.aws.amazon.com/lambda/latest/dg/invocation-scaling.html){target="_blank"}. Always load test to pragmatically balance between your customer experience and development cognitive load.
 * **Granular security permissions**. The micro function approach enables you to use fine-grained permissions & access controls, separate external dependencies & code signing at the function level. Conversely, you could have multiple functions while duplicating the final code artifact in a monolithic approach.
-    - Regardless, least privilege can be applied to either approaches.
+    * Regardless, least privilege can be applied to either approaches.
 * **Higher risk per deployment**. A misconfiguration or invalid import can cause disruption if not caught earlier in automated testing. Multiple functions can mitigate misconfigurations but they would still share the same code artifact. You can further minimize risks with multiple environments in your CI/CD pipeline.
 
 #### Micro function
@@ -1317,20 +1321,20 @@ _**Downsides**_
 
 A micro function means that your final code artifact will be different to each function deployed. This is generally the approach to start if you're looking for fine-grain control and/or high load on certain parts of your service.
 
-_**Benefits**_
+**Benefits**
 
 * **Granular scaling**. A micro function can benefit from the [Lambda scaling model](https://docs.aws.amazon.com/lambda/latest/dg/invocation-scaling.html){target="_blank"} to scale differently depending on each part of your application. Concurrency controls and provisioned concurrency can also be used at a granular level for capacity management.
 * **Discoverability**. Micro functions are easier do visualize when using distributed tracing. Their high-level architectures can be self-explanatory, and complexity is highly visible — assuming each function is named to the business purpose it serves.
 * **Package size**. An independent function can be significant smaller (KB vs MB) depending on external dependencies it require to perform its purpose. Conversely, a monolithic approach can benefit from [Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html){target="_blank"} to optimize builds for external dependencies.
 
-_**Downsides**_
+**Downsides**
 
-* **Upfront investment**. Python ecosystem doesn't use a bundler — you need a custom build tooling to ensure each function only has what it needs and account for [C bindings for runtime compatibility](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html){target="_blank"}. Operations become more elaborate — you need to standardize tracing labels/annotations, structured logging, and metrics to pinpoint root causes.
-    - Engineering discipline is necessary for both approaches. Micro-function approach however requires further attention in consistency as the number of functions grow, just like any distributed system.
+* **Upfront investment**. You need custom build tooling to bundle assets, including [C bindings for runtime compatibility](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html){target="_blank"}. `Operations become more elaborate — you need to standardize tracing labels/annotations, structured logging, and metrics to pinpoint root causes.
+    * Engineering discipline is necessary for both approaches. Micro-function approach however requires further attention in consistency as the number of functions grow, just like any distributed system.
 * **Harder to share code**. Shared code must be carefully evaluated to avoid unnecessary deployments when that changes. Equally, if shared code isn't a library,
 your development, building, deployment tooling need to accommodate the distinct layout.
 * **Slower safe deployments**. Safely deploying multiple functions require coordination — AWS CodeDeploy deploys and verifies each function sequentially. This increases lead time substantially (minutes to hours) depending on the deployment strategy you choose. You can mitigate it by selectively enabling it in prod-like environments only, and where the risk profile is applicable.
-    - Automated testing, operational and security reviews are essential to stability in either approaches.
+    * Automated testing, operational and security reviews are essential to stability in either approaches.
 
 ## Testing your code
 

docs/core/event_handler/appsync.md

@@ -770,7 +770,6 @@ Let's assume you have `app.py` as your Lambda function entrypoint and routes in
         app.resolve(event, context)
     ```
 
-
 ## Testing your code
 
 You can test your resolvers by passing a mocked or actual AppSync Lambda event that you're expecting.

docs/core/logger.md

@@ -736,7 +736,6 @@ You might want to continue to use the same date formatting style, or override `l
 
 Logger allows you to either change the format or suppress the following keys altogether at the initialization: `location`, `timestamp`, `level`, `xray_trace_id`.
 
-
 === "lambda_handler.py"
     ```python hl_lines="7 10"
     from aws_lambda_powertools import Logger
@@ -902,7 +901,6 @@ For exceptional cases where you want to completely replace our formatter logic,
 ???+ warning
     You will need to implement `append_keys`, `clear_state`, override `format`, and optionally `remove_keys` to keep the same feature set Powertools Logger provides. This also means keeping state of logging keys added.
 
-
 === "collect.py"
 
     ```python hl_lines="5 7 9-10 13 17 21 24 35"
@@ -1084,7 +1082,6 @@ def handler(event: Dict, context: LambdaContext) -> List:
 
 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. By default all registered loggers will be modified. You can change this behaviour by providing `include` and `exclude` attributes. You can also provide optional `log_level` attribute external loggers will be configured with.
 
-
 ```python hl_lines="10" title="Cloning Logger config to all other registered standard loggers"
 import logging
 

docs/core/metrics.md

@@ -66,7 +66,6 @@ Metric has two global settings that will be used across all metrics emitted:
 	metrics = Metrics(namespace="ServerlessAirline", service="orders") # Sets metric namespace, and service as a metric dimension
 	```
 
-
 ### Creating metrics
 
 You can create metrics using `add_metric`, and you can create dimensions for all your aggregate metrics using `add_dimension` method.

docs/core/tracer.md

@@ -101,7 +101,6 @@ def collect_payment(charge_id):
     The serialization is performed by aws-xray-sdk via `jsonpickle` module. This can cause
     side effects for file-like objects like boto S3 <a href="https://botocore.amazonaws.com/v1/documentation/api/latest/reference/response.html#botocore.response.StreamingBody">`StreamingBody`</a>, where its response will be read only once during serialization.
 
-
 ### Asynchronous and generator functions
 
 ???+ warning
@@ -246,7 +245,6 @@ def handler(event, context):
         ec2_api_calls()
 ```
 
-
 ### Tracing aiohttp requests
 
 ???+ info

docs/index.md

@@ -9,7 +9,6 @@ A suite of utilities for AWS Lambda functions to ease adopting best practices su
 
     Check out [this detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/) with a practical example.
 
-
 ## Install
 
 Powertools is available in the following formats:
@@ -22,7 +21,6 @@ Powertools is available in the following formats:
 
     When using Layers, you can add Lambda Powertools as a dev dependency (or as part of your virtual env) to not impact the development process.
 
-
 ### Lambda Layer
 
 [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data,  or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.
@@ -187,7 +185,6 @@ You can include Lambda Powertools Lambda Layer using [AWS Lambda Console](https:
 
 	Lambda Powertools Lambda Layer do not include `pydantic` library - required dependency for the `parser` utility. See [SAR](#sar) option instead.
 
-
 #### SAR
 
 Serverless Application Repository (SAR) App deploys a CloudFormation stack with a copy of our Lambda Layer in your AWS account and region.
@@ -205,7 +202,6 @@ Despite having more steps compared to the [public Layer ARN](#lambda-layer) opti
 ???+ tip
 	You can create a shared Lambda Layers stack and make this along with other account level layers stack.
 
-
 If using SAM, you can include this SAR App as part of your shared Layers stack, and lock to a specific semantic version. Once deployed, it'll be available across the account this is deployed to.
 
 === "SAM"
@@ -460,7 +456,7 @@ from aws_lambda_powertools.logging.logger import set_package_logger
 set_package_logger() # (1)
 ```
 
-1.  :information_source: this will configure our `aws_lambda_powertools` logger with debug.
+1. :information_source: this will configure our `aws_lambda_powertools` logger with debug.
 
 ## Tenets