clear-skies 1.19.22__py3-none-any.whl → 2.0.23__py3-none-any.whl

clearskies/endpoints/restful_api.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import configs, decorators
+from clearskies.authentication import Authentication, Authorization, Public
+from clearskies.endpoint_group import EndpointGroup
+from clearskies.endpoints.create import Create
+from clearskies.endpoints.delete import Delete
+from clearskies.endpoints.get import Get
+from clearskies.endpoints.simple_search import SimpleSearch
+from clearskies.endpoints.update import Update
+
+if TYPE_CHECKING:
+    from clearskies import Column, Endpoint, Model, Schema, SecurityHeader
+
+
+class RestfulApi(EndpointGroup):
+    """
+    Full CRUD operations for a model.
+
+    This endpoint group sets up all five standard endpoints to manage a model:
+
+     1. Create
+     2. Update
+     3. Delete
+     4. Get
+     5. List
+
+    As such, you can set any option for all of the above endpoints.  All five endpoints are enabled by default
+    but can be turned off individually.  It's important to understand that the actual API behavior is controlled
+    by other endoints.  This endpoint group creates them and routes requests to them.  So, to fully understand
+    the behavior of the subsequent Restful API, you have to consult the documentation for the endpoints themselves.
+
+    For routing purposes, the create and list endpoints are reachable via the URL specified for this endpoint group
+    and are separated by request method (POST for create by default, GET for list).  The update, delete, and get
+    endoints all expect the id to be appended to the base URL, and then are separated by request method
+    (PATCH for update, DELETE for delete, and GET for get).  See the example app and calls below:
+
+    ```python
+    import clearskies
+    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()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        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",
+        )
+    )
+    wsgi()
+    ```
+
+    Which spins up a fully functional API.  In the below usage examples we create two users, fetch
+    one of them, update a user, delete the other, and then list all users.
+
+    ```bash
+    $ curl 'http://localhost:8080/users' -d '{"name":"Bob", "username": "bob", "age": 25}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "8bd9c03f-bb0c-41bd-afbc-f9526ded88f4",
+            "name": "Bob",
+            "username": "bob",
+            "age": 25,
+            "created_at": "2025-06-10T12:39:35+00:00",
+            "updated_at": "2025-06-10T12:39:35+00:00"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/users' -d '{"name":"Alice", "username": "alice", "age": 22}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
+            "name": "Alice",
+            "username": "alice",
+            "age": 22,
+            "created_at": "2025-06-10T12:42:59+00:00",
+            "updated_at": "2025-06-10T12:42:59+00:00"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/users/8bd9c03f-bb0c-41bd-afbc-f9526ded88f4' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "8bd9c03f-bb0c-41bd-afbc-f9526ded88f4",
+            "name": "Bob",
+            "username": "bob",
+            "age": 25,
+            "created_at": "2025-06-10T12:39:35+00:00",
+            "updated_at": "2025-06-10T12:39:35+00:00"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/users/16d483c6-0eb1-4104-b07b-32f3d736223f' -d '{"name":"Alice Smith", "age": 23}' -X PATCH | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
+            "name": "Alice Smith",
+            "username": "alice",
+            "age": 23,
+            "created_at": "2025-06-10T12:42:59+00:00",
+            "updated_at": "2025-06-10T12:45:01+00:00"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/users/8bd9c03f-bb0c-41bd-afbc-f9526ded88f4' -X DELETE | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {},
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/users/' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+            "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
+            "name": "Alice Smith",
+            "username": "alice",
+            "age": 23,
+            "created_at": "2025-06-10T12:42:59+00:00",
+            "updated_at": "2025-06-10T12:45:01+00:00"
+            }
+        ],
+        "pagination": {
+            "number_results": 1,
+            "limit": 50,
+            "next_page": {}
+        },
+        "input_errors": {}
+    }
+    ```
+    """
+
+    """
+    The endpoint class to use for managing the create operation.
+
+    This defaults to `clearskies.endpoints.Create`.  To disable the create operation all together,
+    set this to None.
+    """
+    create_endpoint = configs.Endpoint(default=Create)
+
+    """
+    The endpoint class to use for managing the delete operation.
+
+    This defaults to `clearskies.endpoints.Delete`.  To disable the delete operation all together,
+    set this to None.
+    """
+    delete_endpoint = configs.Endpoint(default=Delete)
+
+    """
+    The endpoint class to use for managing the update operation.
+
+    This defaults to `clearskies.endpoints.Update`.  To disable the update operation all together,
+    set this to None.
+    """
+    update_endpoint = configs.Endpoint(default=Update)
+
+    """
+    The endpoint class to use to fetch individual records.
+
+    This defaults to `clearskies.endpoints.Get`.  To disable the get operation all together,
+    set this to None.
+    """
+    get_endpoint = configs.Endpoint(default=Get)
+
+    """
+    The endpoint class to use to list records.
+
+    This defaults to `clearskies.endpoints.SimpleSearch`.  To disable the list operation all together,
+    set this to None.
+    """
+    list_endpoint = configs.Endpoint(default=SimpleSearch)
+
+    """
+    The request method(s) to use to route to the create operation.  Default is ["POST"].
+    """
+    create_request_methods = configs.SelectList(
+        allowed_values=["GET", "POST", "PUT", "DELETE", "PATCH"], default=["POST"]
+    )
+
+    """
+    The request method(s) to use to route to the update operation.  Default is ["PATCH"].
+    """
+    update_request_methods = configs.SelectList(
+        allowed_values=["GET", "POST", "PUT", "DELETE", "PATCH"], default=["PATCH"]
+    )
+
+    """
+    The request method(s) to use to route to the delete operation.  Default is ["DELETE"].
+    """
+    delete_request_methods = configs.SelectList(
+        allowed_values=["GET", "POST", "PUT", "DELETE", "PATCH"], default=["DELETE"]
+    )
+
+    """
+    The request method(s) to use to route to the get operation.  Default is ["GET"].
+    """
+    get_request_methods = configs.SelectList(allowed_values=["GET", "POST", "PUT", "DELETE", "PATCH"], default=["GET"])
+
+    """
+    The request method(s) to use to route to the create operation.  Default is ["GET"].
+    """
+    list_request_methods = configs.SelectList(
+        allowed_values=["GET", "POST", "PUT", "DELETE", "PATCH", "QUERY"], default=["GET", "POST", "QUERY"]
+    )
+
+    """
+    The request method(s) to use to route to the create operation.  Default is ["POST"].
+    """
+    id_column_name = configs.ModelColumn("model_class", default=None)
+
+    """
+    The base URL to be used for all the endpoints.
+    """
+    url = configs.String(default="")
+
+    authentication = configs.Authentication(default=Public())
+    authorization = configs.Authorization(default=Authorization())
+    output_map = configs.Callable(default=None)
+    output_schema = configs.Schema(default=None)
+    model_class = configs.ModelClass(default=None)
+    readable_column_names = configs.ReadableModelColumns("model_class", default=[])
+    writeable_column_names = configs.WriteableModelColumns("model_class", default=[])
+    searchable_column_names = configs.SearchableModelColumns("model_class", default=[])
+    sortable_column_names = configs.ReadableModelColumns("model_class", default=[])
+    default_sort_column_name = configs.ModelColumn("model_class", required=True)
+    default_sort_direction = configs.Select(["ASC", "DESC"], default="ASC")
+    default_limit = configs.Integer(default=50)
+    maximum_limit = configs.Integer(default=200)
+    group_by_column_name = configs.ModelColumn("model_class")
+    input_validation_callable = configs.Callable(default=None)
+    include_routing_data_in_request_data = configs.Boolean(default=False)
+    column_overrides = configs.Columns(default={})
+    internal_casing = configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
+    external_casing = configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
+    security_headers = configs.SecurityHeaders(default=[])
+    description = configs.String(default="")
+    where = configs.Conditions(default=[])
+    _descriptor_config_map = None
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        model_class: type[Model],
+        writeable_column_names: list[str],
+        readable_column_names: list[str],
+        searchable_column_names: list[str],
+        sortable_column_names: list[str],
+        default_sort_column_name: str,
+        read_only: bool = False,
+        create_endpoint: type[Endpoint] | None = Create,
+        delete_endpoint: type[Endpoint] | None = Delete,
+        update_endpoint: type[Endpoint] | None = Update,
+        get_endpoint: type[Endpoint] | None = Get,
+        list_endpoint: type[Endpoint] | None = SimpleSearch,
+        create_request_methods: list[str] = ["POST"],
+        update_request_methods: list[str] = ["PATCH"],
+        delete_request_methods: list[str] = ["DELETE"],
+        get_request_methods: list[str] = ["GET"],
+        list_request_methods: list[str] = ["GET"],
+        id_column_name: str = "",
+        group_by_column_name: str = "",
+        input_validation_callable: Callable | None = None,
+        include_routing_data_in_request_data: bool = False,
+        url: str = "",
+        default_sort_direction: str = "ASC",
+        default_limit: int = 50,
+        maximum_limit: int = 200,
+        request_methods: list[str] = ["POST"],
+        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 = "",
+        authentication: Authentication = Public(),
+        authorization: Authorization = Authorization(),
+    ):
+        self.finalize_and_validate_configuration()
+
+        id_column_name = id_column_name if id_column_name else model_class.id_column_name
+
+        # figure out which endpoints we actually need
+        endpoints_to_build = []
+        if not read_only:
+            if create_endpoint:
+                endpoints_to_build.append(
+                    {
+                        "class": create_endpoint,
+                        "request_methods": create_request_methods,
+                    }
+                )
+            if delete_endpoint:
+                endpoints_to_build.append(
+                    {
+                        "class": delete_endpoint,
+                        "request_methods": delete_request_methods,
+                        "url_suffix": f"/:{id_column_name}",
+                    }
+                )
+            if update_endpoint:
+                endpoints_to_build.append(
+                    {
+                        "class": update_endpoint,
+                        "request_methods": update_request_methods,
+                        "url_suffix": f"/:{id_column_name}",
+                    }
+                )
+        if get_endpoint:
+            endpoints_to_build.append(
+                {
+                    "class": get_endpoint,
+                    "request_methods": get_request_methods,
+                    "url_suffix": f"/:{id_column_name}",
+                }
+            )
+        if list_endpoint:
+            endpoints_to_build.append(
+                {
+                    "class": list_endpoint,
+                    "request_methods": list_request_methods,
+                }
+            )
+
+        # and now build them!  Pass along our own kwargs to the endoints when we build them.  Now, technically, I
+        # know what the kwargs are for each endpoint.  However, it would be a lot of duplication to manually
+        # instantiate each endpoint and pass along all the kwargs.  So, fetch the list of kwargs from our own
+        # __init__ and then compare that with the kwargs of the __init__ for each endpoint and map everything
+        # automatically like that.  Then add in the individual config from above.
+
+        # these lines take all of the arguments we were initialized with and dumps it into a dict.  It's the
+        # equivalent of combining both *args and **kwargs without using either
+        my_args = inspect.getfullargspec(self.__class__)
+        local_variables = inspect.currentframe().f_locals  # type: ignore
+        available_args = {arg: local_variables[arg] for arg in my_args.args[1:]}
+
+        # we handle this one manually
+        del available_args["url"]
+
+        # now loop through the list of endpoints
+        endpoints = []
+        for endpoint_to_build in endpoints_to_build:
+            # grab our class and any pre-defined configs
+            endpoint_class = endpoint_to_build["class"]
+            url_suffix = endpoint_to_build.get("url_suffix")
+
+            # now get the allowed args out of the init and fill them out with our own.
+            endpoint_args = inspect.getfullargspec(endpoint_class)
+            nendpoint_args = len(endpoint_args.args)
+            nendpoint_kwargs = len(endpoint_args.defaults) if endpoint_args.defaults else 0
+            final_args: list[str] = []
+            final_kwargs: dict[str, Any] = {}
+            for arg in endpoint_args.args[1:]:
+                if not available_args.get(arg):
+                    continue
+                final_kwargs[arg] = available_args[arg]
+
+            if url_suffix:
+                final_kwargs["url"] = url_suffix
+            final_kwargs["request_methods"] = endpoint_to_build["request_methods"]
+            endpoints.append(endpoint_class(*final_args, **final_kwargs))  # type: ignore
+
+        super().__init__(
+            endpoints,
+            url=url,
+            response_headers=response_headers,
+            security_headers=security_headers,
+            authentication=authentication,
+            authorization=authorization,
+        )

clearskies/endpoints/schema.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import authentication, autodoc, configs, decorators
+from clearskies.endpoint import Endpoint
+
+if TYPE_CHECKING:
+    from clearskies import SecurityHeader
+    from clearskies.authentication import Authentication
+    from clearskies.input_outputs import InputOutput
+
+
+class Schema(Endpoint):
+    """
+    An endpoint that automatically creates a swagger doc for the application.
+
+    The schema endpoint must always be attached to an endpoint group.  It will document all endpoints
+    attached to its parent endpoint group.
+
+    Keep in mind that the routing in the endpoint group is greedy and goes from top-down.  As a result,
+    since the schema endpoint (typically) has a specific URL, it's usually best for it to be at the top
+    of your endpoint list.  The following example builds an application with two endpoint groups, each
+    of which has a schema endpoint:
+
+    ```
+    import clearskies
+    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()])
+        company_name = columns.String()
+        created_at = columns.Created()
+        updated_at = columns.Updated()
+
+
+    readable_column_names = [
+        "id",
+        "name",
+        "username",
+        "age",
+        "company_name",
+        "created_at",
+        "updated_at",
+    ]
+    writeable_user_column_names = ["name", "username", "age", "company_name"]
+    users_api = clearskies.EndpointGroup(
+        [
+            clearskies.endpoints.Schema(url="schema"),
+            clearskies.endpoints.RestfulApi(
+                url="users",
+                model_class=User,
+                readable_column_names=readable_column_names,
+                writeable_column_names=writeable_user_column_names,
+                sortable_column_names=readable_column_names,
+                searchable_column_names=readable_column_names,
+                default_sort_column_name="name",
+            ),
+        ],
+        url="/users",
+    )
+
+
+    class SomeThing(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        thing_1 = clearskies.columns.String(validators=[Required()])
+        thing_2 = clearskies.columns.String(validators=[Unique()])
+
+
+    more_endpoints = clearskies.EndpointGroup(
+        [
+            clearskies.endpoints.HealthCheck(url="health"),
+            clearskies.endpoints.Schema(url="schema"),
+            clearskies.endpoints.Callable(
+                lambda request_data, some_things: some_things.create(request_data),
+                model_class=SomeThing,
+                readable_column_names=["id", "thing_1", "thing_2"],
+                writeable_column_names=["thing_1", "thing_2"],
+                request_methods=["POST"],
+                url="some_thing",
+            ),
+            users_api,
+        ]
+    )
+
+    wsgi = clearskies.contexts.WsgiRef(more_endpoints)
+    wsgi()
+    ```
+
+    We attach the `more_endpoints` endpoint group to our context, and this contains 4 endpoints:
+
+     1. A healthcheck
+     2. A schema endpoint
+     3. A callable endpoint
+     4. The `users_api` endpoint group.
+
+    The `users_api` endpoint group then contains it's own schema endpoint and a restful api endpoint
+    with all our standard user CRUD operations.  As a result, we can fetch two different schema endpoints:
+
+    ```
+    curl 'http://localhost/schema'
+
+    curl 'http://localhost/users/schema'
+    ```
+
+    The former documents all endpoints in the system.  The latter only documents the endpoints under the `/users`
+    path provided by the `users_api` endpoint group.
+    """
+
+    """
+    The doc builder class/format to use
+    """
+    schema_format = configs.Any(default=autodoc.formats.oai3_json.Oai3Json)
+
+    """
+    Addiional data to inject into the schema doc.
+
+    This is typically used for setting info/server settings in the resultant swagger doc.  Anything
+    in this dictionary is injected into the "root" of the generated documentation file.
+    """
+    schema_configuration = configs.AnyDict(default={})
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        url: str,
+        schema_format=autodoc.formats.oai3_json.Oai3Json,
+        request_methods: list[str] = ["GET"],
+        response_headers: list[str | Callable[..., list[str]]] = [],
+        security_headers: list[SecurityHeader] = [],
+        schema_configuration: dict[str, Any] = {},
+        authentication: Authentication = authentication.Public(),
+    ):
+        # 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:
+        current_endpoint_groups = self.di.build_from_name("endpoint_groups", cache=True)
+        if not current_endpoint_groups:
+            raise ValueError(
+                f"{self.__class__.__name__} endpoint was attached directly to the context, but it must be attached to an endpoint group (otherwise it has no application to document)."
+            )
+
+        # the endpoint group at the end of the list is the one that invoked us.  Let's grab it
+        # if we don't hvae any endpoint groups then we've been attached directly to a context,
+        # which is pointless - there's nothing for us to document.  So, treat it as an error.
+        endpoint_group = current_endpoint_groups[-1]
+        requests: list[Any] = []
+        models: dict[str, Any] = {}
+        security_schemes: dict[str, Any] = {}
+        for endpoint in endpoint_group.all_endpoints():
+            requests.extend(endpoint.documentation())
+            models = {**models, **endpoint.documentation_models()}
+            # if "user" in models:
+            # print(models["user"].children)
+            # print(endpoint.__class__.__name__)
+            security_schemes = {**security_schemes, **endpoint.documentation_security_schemes()}
+        # print(models["user"].children)
+
+        schema = self.di.build(self.schema_format)
+        schema.set_requests(requests)
+        schema.set_components({"models": models, "securitySchemes": security_schemes})
+        extra_schema_config = {**self.schema_configuration}
+        if "info" not in extra_schema_config:
+            extra_schema_config["info"] = {"title": "Auto generated by clearskies", "version": "1.0"}
+        self.add_response_headers(input_output)
+        return input_output.respond(schema.pretty(root_properties=extra_schema_config), 200)