clear-skies 2.0.27__py3-none-any.whl

clearskies/endpoints/delete.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import authentication, autodoc, decorators
+from clearskies.endpoints.get import Get
+
+if TYPE_CHECKING:
+    from clearskies import Model, SecurityHeader, typing
+    from clearskies.input_outputs import InputOutput
+
+
+class Delete(Get):
+    """
+    An endpoint that deletes a single record by id (or other unique column).
+
+    This endpoint is intended to delete a single record.  You have to provide a model class and (optionally) the name
+    of the column that it should use to lookup the matching record.  If you don't specifically tell it what column to
+    use to lookup the record, it will assume that you want to use the id column of the model.  Finally, you must
+    declare a route parameter with a matching column name: the delete endpoint will then fetch the desired record id
+    out of the URL path.  The default request method is DELETE. Here's a simple example:
+
+    ```python
+    import clearskies
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        username = clearskies.columns.String()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Delete(
+            model_class=User,
+            url="/{id}",
+        ),
+        bindings={
+            "memory_backend_default_data": [
+                {
+                    "model_class": User,
+                    "records": [
+                        {"id": "1-2-3-4", "name": "Bob Brown", "username": "bobbrown"},
+                        {"id": "1-2-3-5", "name": "Jane Doe", "username": "janedoe"},
+                        {"id": "1-2-3-6", "name": "Greg", "username": "greg"},
+                    ],
+                },
+            ],
+        },
+    )
+    wsgi()
+    ```
+
+    And when invoked:
+
+    ```bash
+    $ curl 'http://localhost:8080/1-2-3-4' -X DELETE | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {},
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        model_class: type[Model],
+        url: str,
+        record_lookup_column_name: str | None = None,
+        response_headers: list[str | Callable[..., list[str]]] = [],
+        request_methods: list[str] = ["DELETE"],
+        internal_casing: str = "snake_case",
+        external_casing: str = "snake_case",
+        security_headers: list[SecurityHeader] = [],
+        description: str = "",
+        where: typing.condition | list[typing.condition] = [],
+        joins: typing.join | list[typing.join] = [],
+        authentication: authentication.Authentication = authentication.Public(),
+        authorization: authentication.Authorization = authentication.Authorization(),
+    ):
+        # see comment in clearskies.endpoints.Create.__init__
+        self.request_methods = request_methods
+
+        # we need to call the parent but don't have to pass along any of our kwargs.  They are all optional in our parent, and our parent class
+        # just stores them in parameters, which we have already done.  However, the parent does do some extra initialization stuff that we need,
+        # which is why we have to call the parent.
+        super().__init__(model_class, url, [model_class.id_column_name])
+
+    def handle(self, input_output: InputOutput) -> Any:
+        model = self.fetch_model(input_output)
+        model.delete()
+        return self.success(input_output, {})
+
+    def documentation(self) -> list[autodoc.request.Request]:
+        output_autodoc = (autodoc.schema.Object(self.auto_case_internal_column_name("data"), children={}),)
+
+        authentication = self.authentication
+        standard_error_responses = [self.documentation_input_error_response()]
+        if not getattr(authentication, "is_public", False):
+            standard_error_responses.append(self.documentation_access_denied_response())
+            if getattr(authentication, "can_authorize", False):
+                standard_error_responses.append(self.documentation_unauthorized_response())
+
+        return [
+            autodoc.request.Request(
+                self.description,
+                [
+                    self.documentation_success_response(
+                        output_autodoc,  # type: ignore
+                        description=self.description,
+                    ),
+                    *standard_error_responses,
+                    self.documentation_generic_error_response(),
+                ],
+                relative_path=self.url,
+                request_methods=self.request_methods,
+                parameters=[
+                    *self.documentation_url_parameters(),
+                ],
+                root_properties={
+                    "security": self.documentation_request_security(),
+                },
+            ),
+        ]
+
+    def documentation_models(self) -> dict[str, autodoc.schema.Schema]:
+        return {}

clearskies/endpoints/get.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import autodoc, configs, decorators, exceptions
+from clearskies.authentication import Authentication, Authorization, Public
+from clearskies.endpoint import Endpoint
+from clearskies.functional import routing, string
+
+if TYPE_CHECKING:
+    from clearskies import Column, Schema, SecurityHeader, typing
+    from clearskies.input_outputs import InputOutput
+    from clearskies.model import Model
+
+
+class Get(Endpoint):
+    """
+    An endpoint that fetches a single record by id (or other unique column).
+
+    This endpoint is intended to return a single record.  You have to provide a model class, the list of columns
+    to return, and (optionally) the name of the column that it should use to lookup the matching record.  If you don't
+    specifically tell it what column to use to lookup the record, it will assume that you want to use the id column
+    of the model.  Finally, you must declare a route parameter with a matching column name: the get endpoint will then
+    fetch the desired record id out of the URL path.  Here's a simple example:
+
+    ```python
+    import clearskies
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        username = clearskies.columns.String()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Get(
+            model_class=User,
+            url="/{id}",
+            readable_column_names=["id", "name", "username"],
+        ),
+        bindings={
+            "memory_backend_default_data": [
+                {
+                    "model_class": User,
+                    "records": [
+                        {"id": "1-2-3-4", "name": "Bob Brown", "username": "bobbrown"},
+                        {"id": "1-2-3-5", "name": "Jane Doe", "username": "janedoe"},
+                        {"id": "1-2-3-6", "name": "Greg", "username": "greg"},
+                    ],
+                },
+            ],
+        },
+    )
+    wsgi()
+    ```
+
+    And when invoked:
+
+    ```bash
+    $ curl 'http://localhost:8080/1-2-3-4' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "1-2-3-4",
+            "name": "Bob Brown",
+            "username": "bobbrown"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/1-2-3-5' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "1-2-3-5",
+            "name": "Jane Doe",
+            "username": "janedoe"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/notauser' | jq
+    {
+        "status": "client_error",
+        "error": "Not Found",
+        "data": [],
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    """
+    Specify the name of the column that should be used to look up the record.
+
+    If not specified, it will default to the id column name.  There must be a matching route parameter in the URL.
+
+    ```python
+    import clearskies
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        username = clearskies.columns.String()
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Get(
+            model_class=User,
+            url="/{username}",
+            readable_column_names=["id", "name", "username"],
+            record_lookup_column_name="username",
+        ),
+        bindings={
+            "memory_backend_default_data": [
+                {
+                    "model_class": User,
+                    "records": [
+                        {"id": "1-2-3-4", "name": "Bob Brown", "username": "bobbrown"},
+                        {"id": "1-2-3-5", "name": "Jane Doe", "username": "janedoe"},
+                        {"id": "1-2-3-6", "name": "Greg", "username": "greg"},
+                    ],
+                },
+            ],
+        },
+    )
+    wsgi()
+    ```
+
+    Note that `record_lookup_column_name` is set to `username` and we similarly changed the route from
+    `/{id}` to `/{username}`.  We then invoke it with the username rather than the id:
+
+    ```bash
+    $ curl 'http://localhost:8080/janedoe' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "1-2-3-5",
+            "name": "Jane Doe",
+            "username": "janedoe"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+    record_lookup_column_name = configs.ReadableModelColumn("model_class", default=None)
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        model_class: type[Model],
+        url: str,
+        readable_column_names: list[str],
+        record_lookup_column_name: str | None = None,
+        request_methods: list[str] = ["GET"],
+        response_headers: list[str | Callable[..., list[str]]] = [],
+        output_map: Callable[..., dict[str, Any]] | None = None,
+        output_schema: Schema | None = None,
+        column_overrides: dict[str, Column] = {},
+        internal_casing: str = "snake_case",
+        external_casing: str = "snake_case",
+        security_headers: list[SecurityHeader] = [],
+        description: str = "",
+        where: typing.condition | list[typing.condition] = [],
+        joins: typing.join | list[typing.join] = [],
+        authentication: Authentication = Public(),
+        authorization: Authorization = Authorization(),
+    ):
+        try:
+            # we will set the value for this if it isn't already set, and the easiest way is to just fetch it and see if it blows up
+            self.record_lookup_column_name
+        except:
+            self.record_lookup_column_name = self.model_class.id_column_name
+
+        # we need to call the parent but don't have to pass along any of our kwargs.  They are all optional in our parent, and our parent class
+        # just stores them in parameters, which we have already done.  However, the parent does do some extra initialization stuff that we need,
+        # which is why we have to call the parent.
+        super().__init__()
+
+        route_parameters = routing.extract_url_parameter_name_map(url)
+        if self.record_lookup_column_name not in route_parameters:
+            raise KeyError(
+                f"Configuration error for {self.__class__.__name__} endpoint: record_lookup_column_name is set to '{self.record_lookup_column_name}' but no matching routing parameter is found"
+            )
+
+    def get_model_id(self, input_output: InputOutput) -> str:
+        routing_data = input_output.routing_data
+        if self.record_lookup_column_name in routing_data:
+            return routing_data[self.record_lookup_column_name]
+        raise KeyError(
+            f"I didn't receive the ID in my routing data.  I am probably misconfigured.  My record_lookup_column_name is '{self.record_lookup_column_name}' and my route is {self.url}"
+        )
+
+    def fetch_model(self, input_output: InputOutput) -> Model:
+        lookup_column_value = self.get_model_id(input_output)
+        model = self.fetch_model_with_base_query(input_output).find(
+            self.record_lookup_column_name + "=" + lookup_column_value
+        )
+        if not model:
+            raise exceptions.NotFound("Not Found")
+        return model
+
+    def handle(self, input_output: InputOutput) -> Any:
+        model = self.fetch_model(input_output)
+        return self.success(input_output, self.model_as_json(model, input_output))
+
+    def documentation(self) -> list[autodoc.request.Request]:
+        output_schema = self.model_class
+        nice_model = string.camel_case_to_words(output_schema.__name__)
+
+        schema_model_name = string.camel_case_to_snake_case(output_schema.__name__)
+        output_data_schema = self.documentation_data_schema(output_schema, self.readable_column_names)
+        output_autodoc = (
+            autodoc.schema.Object(
+                self.auto_case_internal_column_name("data"), children=output_data_schema, model_name=schema_model_name
+            ),
+        )
+
+        authentication = self.authentication
+        standard_error_responses = []
+        if not getattr(authentication, "is_public", False):
+            standard_error_responses.append(self.documentation_access_denied_response())
+            if getattr(authentication, "can_authorize", False):
+                standard_error_responses.append(self.documentation_unauthorized_response())
+
+        return [
+            autodoc.request.Request(
+                self.description,
+                [
+                    self.documentation_success_response(
+                        output_autodoc,  # type: ignore
+                        description=self.description,
+                    ),
+                    *standard_error_responses,
+                    self.documentation_generic_error_response(),
+                ],
+                relative_path=self.url,
+                request_methods=self.request_methods,
+                parameters=[
+                    *self.documentation_url_parameters(),
+                ],
+                root_properties={
+                    "security": self.documentation_request_security(),
+                },
+            ),
+        ]
+
+    def documentation_models(self) -> dict[str, autodoc.schema.Schema]:
+        output_schema = self.output_schema if self.output_schema else self.model_class
+        schema_model_name = string.camel_case_to_snake_case(output_schema.__name__)
+
+        return {
+            schema_model_name: autodoc.schema.Object(
+                self.auto_case_internal_column_name("data"),
+                children=self.documentation_data_schema(output_schema, self.readable_column_names),
+            ),
+        }

clearskies/endpoints/health_check.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import autodoc, configs, decorators
+from clearskies.endpoint import Endpoint
+
+if TYPE_CHECKING:
+    from clearskies.input_outputs import InputOutput
+
+
+class HealthCheck(Endpoint):
+    """
+    An endpoint that returns 200/500 to denote if backend services are functional.
+
+    You can provide dependency injection names, classes, or a callable.  When invoked, this endpoint
+    will build/call all of them and, as long as none raise any exceptions, return a 200.
+
+    HealthCheck endpoints are always public and ignore authentication/authorization settings.
+
+    If you don't provide any configuration to the endpoint, it will always succeed:
+
+    ```python
+    import clearskies
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.HealthCheck(),
+    )
+    wsgi()
+    ```
+
+    which when invoked:
+
+    ```bash
+    $ curl 'http://localhost:8080' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {},
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    This example demonstrates a failed healthcheck by requesting the cursor (which attempts to connect to the database).
+    Since no database has been setup/configured, it always fails:
+
+    ```python
+    import clearskies
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.HealthCheck(
+            dependency_injection_names=["cursor"],
+        ),
+    )
+    wsgi()
+    ```
+
+    And when invoked returns:
+
+    ```bash
+    $ curl 'http://localhost:8080' | jq
+    {
+        "status": "failure",
+        "error": "",
+        "data": {},
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    with a status code of 500.
+    """
+
+    """
+    A list of dependency injection names that should be fetched when the healthcheck endpoint is invoked.
+
+    If any exceptions are raised when building the dependency injection parameters, the health check will return
+    failure.
+    """
+    dependency_injection_names = configs.StringList(default=[])
+
+    """
+    A list of classes to build with the dependency injection system.
+
+    The If any exceptions are raised when building the classes, then the healthcheck will return a failure.
+    In the following example, since the class-to-build requests the cursor, and we don't have a reachable
+    database configured,
+
+    ```python
+    import clearskies
+
+    class MyClass:
+        def __init__(self, cursor):
+            pass
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.HealthCheck(
+            classes_to_build=[MyClass],
+        ),
+    )
+    wsgi()
+    ```
+    """
+    classes_to_build = configs.Any(default=[])
+
+    """
+    A list of callables to invoke.
+
+    Your callables can request any dependency injection names.  If any exceptions are raised, the healthcheck will
+    return a failure.  The return value from the function is ignored.  In this example we request the cursor from
+    the dependency injection system, which will call the healthcheck to fail since we don't have a database setup
+    and configured:
+
+    ```python
+    import clearskies
+
+    def my_function(cursor):
+        pass
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.HealthCheck(
+            callables=[my_function],
+        ),
+    )
+    wsgi()
+    ```
+    """
+    callables = configs.Any(default=[])
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        dependency_injection_names: list[str] = [],
+        classes_to_build: list[type] = [],
+        callables: list[Callable] = [],
+        description: str = "",
+        url: str = "",
+        request_methods: list[str] = ["GET"],
+    ):
+        # we need to call the parent but don't have to pass along any of our kwargs.  They are all optional in our parent, and our parent class
+        # just stores them in parameters, which we have already done.  However, the parent does do some extra initialization stuff that we need,
+        # which is why we have to call the parent.
+        super().__init__()
+
+    def handle(self, input_output: InputOutput) -> Any:
+        try:
+            for name in self.dependency_injection_names:
+                self.di.build_from_name(name)
+
+            for class_to_build in self.classes_to_build:
+                self.di.build_class(class_to_build)
+
+            for thing_to_call in self.callables:
+                self.di.call_function(thing_to_call)
+        except:
+            return self.failure(input_output)
+
+        return self.success(input_output, {})
+
+    def documentation(self) -> list[autodoc.request.Request]:
+        output_schema = self.model_class
+        output_autodoc = (autodoc.schema.Object(self.auto_case_internal_column_name("data"), children=[]),)
+
+        description = self.description if self.description else "Health Check"
+        return [
+            autodoc.request.Request(
+                description,
+                [
+                    self.documentation_success_response(
+                        output_autodoc,  # type: ignore
+                        description=description,
+                    ),
+                ],
+                relative_path=self.url,
+                request_methods=self.request_methods,
+                parameters=[
+                    *self.documentation_url_parameters(),
+                ],
+            ),
+        ]