clear-skies-aws 1.10.2__py3-none-any.whl → 2.0.2__py3-none-any.whl

clearskies_aws/backends/sqs_backend.py

@@ -1,10 +1,18 @@
-from clearskies.backends.backend import Backend
-from clearskies import model
+from __future__ import annotations
+
 import json
-from typing import Any, Callable, Dict, List, Tuple
-class SqsBackend(Backend):
+from typing import Any
+
+from clearskies import Model
+from clearskies.query import Query
+from types_boto3_sqs import SQSClient
+
+from clearskies_aws.backends import backend
+
+
+class SqsBackend(backend.Backend):
     """
-    SQS backend for clearskies
+    SQS backend for clearskies.
 
     There's not too much to this.  Just set it on your model and set the table name equal to the SQS url.
 
@@ -17,64 +25,37 @@ class SqsBackend(Backend):
     See the SQS context in this library for processing your queue data.
     """
 
-    _boto3 = None
-    _environment = None
-    _sqs = None
-
-    _allowed_configs = [
-        'table_name',
-        'model_columns',
-    ]
+    _sqs: SQSClient
 
-    _required_configs = [
-        'table_name',
-    ]
+    @property
+    def sqs(self) -> SQSClient:
+        if not hasattr(self, "_sqs"):
+            if not self.environment.get("AWS_REGION", True):
+                raise ValueError("To use SQS you must use set AWS_REGION in the .env file or an environment variable")
 
-    def __init__(self, boto3, environment):
-        self._boto3 = boto3
-        self._environment = environment
-        if not environment.get('AWS_REGION', True):
-            raise ValueError('To use SQS you must use set AWS_REGION in the .env file or an environment variable')
+            self._sqs = self.boto3.client("sqs", region_name=self.environment.get("AWS_REGION", True))
 
-        self._sqs = self._boto3.client('sqs', region_name=environment.get('AWS_REGION', True))
+        return self._sqs
 
-    def configure(self):
-        pass
-
-    def create(self, data, model):
-        self._sqs.send_message(
-            QueueUrl=model.table_name(),
+    def create(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        self.sqs.send_message(
+            QueueUrl=model.destination_name(),
             MessageBody=json.dumps(data),
         )
         return {**data}
 
-    def update(self, id, data, model):
+    def update(self, id: int | str, data: dict[str, Any], model: Model) -> dict[str, Any]:
         raise ValueError("The SQS backend only supports the create operation")
 
-    def delete(self, id, model):
+    def delete(self, id: int | str, model: Model) -> bool:
         raise ValueError("The SQS backend only supports the create operation")
 
-    def count(self, configuration, model):
+    def count(self, query: Query) -> int:
         raise ValueError("The SQS backend only supports the create operation")
 
-    def records(self,
-                configuration: Dict[str, Any],
-                model: model.Model,
-                next_page_data: Dict[str, str] = None) -> List[Dict[str, Any]]:
+    def records(
+        self,
+        query: Query,
+        next_page_data: dict[str, str | int] | None = None,
+    ) -> list[dict[str, Any]]:
         raise ValueError("The SQS backend only supports the create operation")
-        return []
-
-    def validate_pagination_kwargs(self, kwargs: Dict[str, Any], case_mapping: Callable) -> str:
-        return ''
-
-    def allowed_pagination_keys(self) -> List[str]:
-        return []
-
-    def documentation_pagination_next_page_response(self, case_mapping: Callable) -> List[Any]:
-        return []
-
-    def documentation_pagination_next_page_example(self, case_mapping: Callable) -> Dict[str, Any]:
-        return {}
-
-    def documentation_pagination_parameters(self, case_mapping: Callable) -> List[Tuple[Any]]:
-        return []

clearskies_aws/contexts/__init__.py

@@ -1,10 +1,23 @@
-from .cli import cli
-from .cli_websocket_mock import cli_websocket_mock
-from .lambda_api_gateway import lambda_api_gateway
-from .lambda_api_gateway_web_socket import lambda_api_gateway_web_socket
-from .lambda_elb import lambda_elb
-from .lambda_http_gateway import lambda_http_gateway
-from .lambda_invocation import lambda_invocation
-from .lambda_sqs_standard_partial_batch import lambda_sqs_standard_partial_batch
-from .lambda_sns import lambda_sns
-from .wsgi import wsgi
+from __future__ import annotations
+
+from clearskies_aws.contexts.cli_web_socket_mock import CliWebSocketMock
+from clearskies_aws.contexts.lambda_alb import LambdaAlb
+from clearskies_aws.contexts.lambda_api_gateway import LambdaApiGateway
+from clearskies_aws.contexts.lambda_api_gateway_web_socket import (
+    LambdaApiGatewayWebSocket,
+)
+from clearskies_aws.contexts.lambda_invocation import LambdaInvocation
+from clearskies_aws.contexts.lambda_sns import LambdaSns
+from clearskies_aws.contexts.lambda_sqs_standard_partial_batch import (
+    LambdaSqsStandardPartialBatch,
+)
+
+__all__ = [
+    "CliWebSocketMock",
+    "LambdaAlb",
+    "LambdaApiGateway",
+    "LambdaApiGatewayWebSocket",
+    "LambdaInvocation",
+    "LambdaSns",
+    "LambdaSqsStandardPartialBatch",
+]

clearskies_aws/contexts/cli_web_socket_mock.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from clearskies.contexts import cli
+
+from clearskies_aws.input_outputs import CliWebSocketMock as CliWebSocketMockInputOutput
+
+
+class CliWebSocketMock(cli.Cli):
+    """
+    Help assist with testing websockets locally.
+
+    The LambdaApiGatewayWebSocket context makes it easy to run websocket applications, but testing
+    these locally is literally impossible.  This context provides a close analogue to the way
+    the LambdaApiGatewayWebSocket context works to give some testing capabilities when running
+    locally.
+    """
+
+    def __call__(self):
+        return self.execute_application(CliWebSocketMockInputOutput())

clearskies_aws/contexts/lambda_alb.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.contexts.context import Context
+
+from clearskies_aws.input_outputs import LambdaAlb as LambdaAlbInputOutput
+
+
+class LambdaAlb(Context):
+    """
+    Run a clearskies application in a lambda behind an application load balancer.
+
+    There's nothing special here: just build your application, use the LambdaAlb context in a standard AWS lambda
+    handler, and attach your lambda to an ALB.  This generally expects that the ALB will forward all requests to
+    the clearskies application, which will therefore handle all routing.  However, you can also use path-based
+    routing in your target group to forward some subset of requests to separate lambdas, each using this same
+    context.  When you do this, keep in mind that AWS still passes along the full path (including the part handled
+    by the ALB), so you want to make sure that your clearskies application is configured with the full URL as well.
+
+    Per AWS norms, you should create the context in the "root" of your python application, and then invoke it
+    inside a standard lambda handler function.  This will allow AWS to cache the full application, improving
+    performance.  If you create and invoke the context inside of your lambda handler, it will effectively turn
+    off any caching.  In addition, clearskies does a fair amount of configuration validation when you create the
+    context, so this work will be repeated on every call.
+
+    ```
+    import clearskies
+    import clearskies_aws
+    from clearskies.validators import Required, Unique
+    from clearskies import columns
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = columns.Uuid()
+        name = columns.String(validators=[Required()])
+        username = columns.String(
+            validators=[
+                Required(),
+                Unique(),
+            ]
+        )
+        age = columns.Integer(validators=[Required()])
+        created_at = columns.Created()
+        updated_at = columns.Updated()
+
+
+    application = clearskies_aws.contexts.LambdaAlb(
+        clearskies.endpoints.RestfulApi(
+            url="users",
+            model_class=User,
+            readable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            writeable_column_names=["name", "username", "age"],
+            sortable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            searchable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            default_sort_column_name="name",
+        )
+    )
+
+
+    def lambda_handler(event, context):
+        return application(event, context)
+    ```
+
+    ### Context for Callables
+
+    When using this context, two additional named arguments become available to any callables invoked by clearskies:
+    `event` and `context`.  These correspond to the original `event` and `context` variables provided by AWS to
+    the lambda.
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaAlbInputOutput(event, context))

clearskies_aws/contexts/lambda_api_gateway.py

@@ -1,30 +1,77 @@
-from ..input_outputs import LambdaAPIGateway as LambdaAPIGatewayInputOutput
-from ..di import StandardDependencies
-from clearskies.contexts.build_context import build_context
+from __future__ import annotations
+
+from typing import Any
+
 from clearskies.contexts.context import Context
-class LambdaAPIGateway(Context):
-    def __init__(self, di):
-        super().__init__(di)
-
-    def __call__(self, event, context):
-        if self.handler is None:
-            raise ValueError("Cannot execute LambdaAPIGateway context without first configuring it")
-
-        return self.handler(LambdaAPIGatewayInputOutput(event, context))
-def lambda_api_gateway(
-    application,
-    di_class=StandardDependencies,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        LambdaAPIGateway,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
+
+from clearskies_aws.input_outputs import LambdaApiGateway as LambdaApiGatewayInputOutput
+
+
+class LambdaApiGateway(Context):
+    """
+    Run a clearskies application in a lambda behind an API Gateway (v1 or v2).
+
+    There's nothing special here: just build your application, use the LambdaApiGateway context in a standard AWS
+    lambda handler, and attach your lambda to an Api Gateway.  Per AWS norms, you should create the context in
+    the "root" of your python application, and then invoke it inside a standard lambda handler function.  This
+    will allow AWS to cache the full application, improving performance.  If you create and invoke the context
+    inside of your lambda handler, it will effectively turn off any caching.  In addition, clearskies does a fair
+    amount of configuration validation when you create the context, so this work will be repeated on every call.
+
+    ```
+    import clearskies
+    import clearskies_aws
+    from clearskies.validators import Required, Unique
+    from clearskies import columns
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = columns.Uuid()
+        name = columns.String(validators=[Required()])
+        username = columns.String(
+            validators=[
+                Required(),
+                Unique(),
+            ]
+        )
+        age = columns.Integer(validators=[Required()])
+        created_at = columns.Created()
+        updated_at = columns.Updated()
+
+
+    application = clearskies_aws.contexts.LambdaApiGateway(
+        clearskies.endpoints.RestfulApi(
+            url="users",
+            model_class=User,
+            readable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            writeable_column_names=["name", "username", "age"],
+            sortable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            searchable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
+            default_sort_column_name="name",
+        )
     )
+
+
+    def lambda_handler(event, context):
+        return application(event, context)
+    ```
+
+    ### Context for Callables
+
+    When using this context, a number of additional named arguments become available to any callables invoked by
+    clearskies:
+
+     1. `event`
+     2. `context`
+     3. `resource`
+     4. `stage`
+     5. `request_id`
+     6. `api_id`
+     7. `api_version` (v1 or v2)
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayInputOutput(event, context))

clearskies_aws/contexts/lambda_api_gateway_web_socket.py

@@ -1,30 +1,57 @@
-from ..input_outputs import LambdaAPIGatewayWebSocket as LambdaAPIGatewayWebSocketInputOutput
-from ..di import StandardDependencies
-from clearskies.contexts.build_context import build_context
+from __future__ import annotations
+
+from typing import Any
+
 from clearskies.contexts.context import Context
-class LambdaAPIGatewayWebSocket(Context):
-    def __init__(self, di):
-        super().__init__(di)
-
-    def __call__(self, event, context):
-        if self.handler is None:
-            raise ValueError("Cannot execute LambdaAPIGatewayWebSocket context without first configuring it")
-
-        return self.handler(LambdaAPIGatewayWebSocketInputOutput(event, context))
-def lambda_api_gateway_web_socket(
-    application,
-    di_class=StandardDependencies,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        LambdaAPIGatewayWebSocket,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
-    )
+
+from clearskies_aws.input_outputs import (
+    LambdaApiGatewayWebSocket as LambdaApiGatewayWebSocketInputOutput,
+)
+
+
+class LambdaApiGatewayWebSocket(Context):
+    """
+    Run a clearskies application behind an API Gateway that is configured for use as a websocket.
+
+    Websockets work much differently than standard API endpoints.  Most importantly, none of the standard HTTP
+    concepts exist.  Websockets requests don't have any of:
+
+     1. URL Path
+     2. Query Parameters
+     3. HTTP Headers
+     4. Response Headers
+     5. An HTTP Response
+
+    So in short, everything works completely differently.  The reason is because a websocket is a
+    two-way communication channel that's created over a TCP/IP connection.  It does start with an HTTP request,
+    but this is a one time request when the communication channel is first created.  Later messages (which
+    are where the bulk of the communication happens) travel over the already-open connection, so
+    the communication looks nothing like HTTP.  Usually, the data traveling over this connection is
+    a JSON payload, and since the connection is already opened it doesn't have any of the metadata associated
+    with an HTTP request (hence the lack of url/query/headers).  In addition, the communication is no longer
+    transactional - messages from the client to the server do not come with a direct response, and the server
+    can send messages to the client without needing the former to initiate the conversation.
+
+    Routing and authorization are usually handled in-band, which means that the routing parameters or authentication
+    data are added directly to the JSON body sent over the open connection.  This often results in applications
+    having to handle such things themselves, since the typical standards of web frameworks won't match up.  In
+    the case of routing with an API Gateway, it has its own suggested standard of setting a routekey where the
+    API gateway will check for an application-defined route parameter in the request body and use this to route
+    to an appropriate lambda.  With clearskies, you can also use the `clearskies.endpoints.JsonParamEndpointGroup`
+    to accomplish the same.
+
+    With a websocket through API Gateway, headers are available during the `on_connect` phase, so you can always
+    perform authentication then and record the result with the connection id (which can be used much like a
+    session id).  Otherwise, authentication is typically handled by including the authentication token in every
+    message payload.
+
+    ### Sending Messages
+
+    An important part of using websockets is being able to manage and send messages to clients.  To help with this,
+    there is a base model class in `clearskies_aws.models.WebSocketConnectionModel`.  Check the documentation for
+    this class to understand how this is managed and see a "starter" websocket application.
+
+    """
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any], url: str = "") -> Any:  # type: ignore[override]
+        return self.execute_application(LambdaApiGatewayWebSocketInputOutput(event, context, url))

clearskies_aws/contexts/lambda_invocation.py

@@ -1,48 +1,19 @@
-from clearskies.authentication import public
-from ..input_outputs import LambdaInvocation as LambdaInvocationInputOutput
-from ..di import StandardDependencies
-from clearskies.contexts.build_context import build_context
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.authentication import Public
 from clearskies.contexts.context import Context
-class LambdaInvocation(Context):
-    def __init__(self, di):
-        super().__init__(di)
 
-    def finalize_handler_config(self, config):
-        return {
-            'authentication': public(),
-            **config,
-        }
+from clearskies_aws.input_outputs import LambdaInvocation as LambdaInvocationInputOutput
 
-    def __call__(
-        self,
-        event,
-        context,
-        method=None,
-        url=None,
-    ):
-        if self.handler is None:
-            raise ValueError("Cannot execute LambdaInvocation context without first configuring it")
 
-        return self.handler(LambdaInvocationInputOutput(
-            event,
-            context,
-            method=method,
-            url=url,
-        ))
-def lambda_invocation(
-    application,
-    di_class=StandardDependencies,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        LambdaInvocation,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
-    )
+class LambdaInvocation(Context):
+
+    def __call__(self, event: dict[str, Any], context: dict[str, Any]) -> Any:  # type: ignore[override]
+        return self.execute_application(
+            LambdaInvocationInputOutput(
+                event,
+                context,
+            )
+        )

clearskies_aws/contexts/lambda_sns.py

@@ -1,43 +1,18 @@
-from ..input_outputs import LambdaSns as LambdaSnsInputOutput
-from ..di import StandardDependencies
-from clearskies.contexts.build_context import build_context
+from __future__ import annotations
+
+from clearskies.authentication import Public
 from clearskies.contexts.context import Context
-from clearskies.authentication import public
 
-class LambdaSns(Context):
-    def __init__(self, di):
-        super().__init__(di)
+from clearskies_aws.input_outputs import LambdaSns as LambdaSnsInputOutput
 
-    def finalize_handler_config(self, config):
-        return {
-            'authentication': public(),
-            **config,
-        }
 
+class LambdaSns(Context):
     def __call__(self, event, context, method=None, url=None):
-        if self.handler is None:
+        if self.execute_application is None:
             raise ValueError("Cannot execute LambdaSnsEvent context without first configuring it")
 
         try:
-            return self.handler(LambdaSnsInputOutput(event, context, method=method, url=url))
+            return self.execute_application(LambdaSnsInputOutput(event, context, method=method, url=url))
         except Exception as e:
-            print('Failed message ' + event['Records'][0]['Sns']['MessageId'] + '. Error error: ' + str(e))
+            print("Failed message " + event["Records"][0]["Sns"]["MessageId"] + ". Error error: " + str(e))
             raise e
-
-def lambda_sns(
-    application,
-    di_class=StandardDependencies,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        LambdaSns,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
-    )

clearskies_aws/contexts/lambda_sqs_standard_partial_batch.py

@@ -1,51 +1,29 @@
+from __future__ import annotations
+
 import traceback
-from ..input_outputs import LambdaSqsStandard as LambdaSqsStandardInputOutput
-from ..di import StandardDependencies
-from clearskies.contexts.build_context import build_context
+
+from clearskies.authentication import Public
 from clearskies.contexts.context import Context
-from clearskies.authentication import public
-class LambdaSqsStandardPartialBatch(Context):
-    def __init__(self, di):
-        super().__init__(di)
 
-    def finalize_handler_config(self, config):
-        return {
-            'authentication': public(),
-            **config,
-        }
+from clearskies_aws.input_outputs import LambdaSqsStandard as LambdaSqsStandardInputOutput
 
-    def __call__(self, event, context, url=None, method=None):
-        if self.handler is None:
-            raise ValueError("Cannot execute LambdaELB context without first configuring it")
 
+class LambdaSqsStandardPartialBatch(Context):
+    def __call__(self, event, context, url="", method="POST"):
         item_failures = []
-        for record in event['Records']:
+        for record in event["Records"]:
+            print("Processing message " + record["messageId"], record["body"])
             try:
-                self.handler(LambdaSqsStandardInputOutput(record['body'], event, context, url=url, method=method))
+                self.execute_application(
+                    LambdaSqsStandardInputOutput(record["body"], event, context, url=url, method=method)
+                )
             except Exception as e:
-                print('Failed message ' + record['messageId'] + ' being returned for retry.  Error error: ' + str(e))
+                print("Failed message " + record["messageId"] + " being returned for retry.  Error error: " + str(e))
                 traceback.print_tb(e.__traceback__)
-                item_failures.append({'itemIdentifier': record['messageId']})
+                item_failures.append({"itemIdentifier": record["messageId"]})
 
         if item_failures:
             return {
                 "batchItemFailures": item_failures,
             }
         return {}
-def lambda_sqs_standard_partial_batch(
-    application,
-    di_class=StandardDependencies,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        LambdaSqsStandardPartialBatch,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
-    )

clearskies_aws/di/__init__.py

@@ -1 +1,6 @@
-from .standard_dependencies import StandardDependencies
+from __future__ import annotations
+
+from clearskies_aws.di import inject
+from clearskies_aws.di.aws_additional_config_auto_import import AwsAdditionalConfigAutoImport
+
+__all__ = ["inject", "AwsAdditionalConfigAutoImport"]

clearskies_aws/di/aws_additional_config_auto_import.py

@@ -0,0 +1,37 @@
+import datetime
+from types import ModuleType
+from typing import Any
+
+import boto3 as boto3_module
+from clearskies import Environment
+from clearskies.di import AdditionalConfigAutoImport
+from clearskies.di.additional_config import AdditionalConfig
+
+from clearskies_aws.secrets import ParameterStore
+
+
+class AwsAdditionalConfigAutoImport(AdditionalConfigAutoImport):
+    """
+    Provide a DI with AWS modules built-in.
+
+    This DI auto injects boto3, boto3 Session and the parameter store.
+    """
+
+    def provide_boto3(self) -> ModuleType:
+        import boto3
+
+        return boto3
+
+    def provide_parameter_store(self) -> ParameterStore:
+        # This is just here so that we can auto-inject the secrets into the environment without having
+        # to force the developer to define a secrets manager
+        return ParameterStore()
+
+    def provide_boto3_session(self, boto3: ModuleType, environment: Environment) -> boto3_module.session.Session:
+        if not environment.get("AWS_REGION", True):
+            raise ValueError(
+                "To use AWS Session you must use set AWS_REGION in the .env file or an environment variable"
+            )
+
+        session = boto3.session.Session(region_name=environment.get("AWS_REGION", True))
+        return session