clear-skies 2.0.5__py3-none-any.whl → 2.0.7__py3-none-any.whl

clearskies/endpoints/simple_search.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import inspect
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Callable
+
+import clearskies.configs
+import clearskies.exceptions
+from clearskies import authentication, autodoc, typing
+from clearskies.endpoints.list import List
+from clearskies.functional import string
+from clearskies.input_outputs import InputOutput
+
+if TYPE_CHECKING:
+    from clearskies import Column, Schema, SecurityHeader
+    from clearskies.model import Model
+
+
+class SimpleSearch(List):
+    """
+    Create an endpoint that supports searching by exact values via url/JSON parameters.
+
+    This acts exactly like the list endpoint but additionally grants the client the ability to search records
+    via URL parameters or JSON POST body parameters.  You just have to specify which columns are searchable.
+
+    In the following example we tell the `SimpleSearch` endpoint that we want it to return records from the
+    `Student` model, return `id`, `name`, and `grade` in the results, and allow the user to search by
+    `name` and `grade`.  We also seed the memory backend with data so the endpoint has something to return:
+
+    ```python
+    import clearskies
+
+
+    class Student(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        grade = clearskies.columns.Integer()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.SimpleSearch(
+            Student,
+            readable_column_names=["id", "name", "grade"],
+            sortable_column_names=["name", "grade"],
+            searchable_column_names=["name", "grade"],
+            default_sort_column_name="name",
+        ),
+        bindings={
+            "memory_backend_default_data": [
+                {
+                    "model_class": Student,
+                    "records": [
+                        {"id": "1-2-3-4", "name": "Bob", "grade": 5},
+                        {"id": "1-2-3-5", "name": "Jane", "grade": 3},
+                        {"id": "1-2-3-6", "name": "Greg", "grade": 3},
+                        {"id": "1-2-3-7", "name": "Bob", "grade": 2},
+                    ],
+                },
+            ],
+        },
+    )
+    wsgi()
+    ```
+
+    Here is the basic operation of the endpoint itself, without any search parameters, in which case it behaves
+    identically to the list endpoint:
+
+    ```bash
+    $ curl 'http://localhost:8080' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "1-2-3-4",
+                "name": "Bob",
+                "grade": 5
+            },
+            {
+                "id": "1-2-3-7",
+                "name": "Bob",
+                "grade": 2
+            },
+            {
+                "id": "1-2-3-6",
+                "name": "Greg",
+                "grade": 3
+            },
+            {
+                "id": "1-2-3-5",
+                "name": "Jane",
+                "grade": 3
+            }
+        ],
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    We can then search on name via the `name` URL parameter:
+
+    ```bash
+    $ curl 'http://localhost:8080?name=Bob' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "1-2-3-4",
+                "name": "Bob",
+                "grade": 5
+            },
+            {
+                "id": "1-2-3-7",
+                "name": "Bob",
+                "grade": 2
+            }
+        ],
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    and multiple search terms are allowed:
+
+    ```bash
+    $ curl 'http://localhost:8080?name=Bob&grade=2' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "1-2-3-7",
+                "name": "Bob",
+                "grade": 2
+            }
+        ],
+        "pagination": {},
+    "input_errors": {}
+    }
+    ```
+
+    Pagination and sorting work just like with the list endpoint:
+
+    ```bash
+    $ curl 'http://localhost:8080?sort=grade&direction=desc&limit=2' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "1-2-3-4",
+                "name": "Bob",
+                "grade": 5
+            },
+            {
+                "id": "1-2-3-5",
+                "name": "Jane",
+                "grade": 3
+            }
+        ],
+        "pagination": {
+            "number_results": 4,
+            "limit": 2,
+            "next_page": {
+                "start": 2
+            }
+        },
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080?sort=grade&direction=desc&limit=2&start=2' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "1-2-3-6",
+                "name": "Greg",
+                "grade": 3
+            },
+            {
+                "id": "1-2-3-7",
+                "name": "Bob",
+                "grade": 2
+            }
+        ],
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        model_class: type[Model],
+        readable_column_names: list[str],
+        sortable_column_names: list[str],
+        searchable_column_names: list[str],
+        default_sort_column_name: str,
+        default_sort_direction: str = "ASC",
+        default_limit: int = 50,
+        maximum_limit: int = 200,
+        where: typing.condition | list[typing.condition] = [],
+        joins: typing.join | list[typing.join] = [],
+        url: str = "",
+        request_methods: list[str] = ["GET", "POST", "QUERY"],
+        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.Authentication = authentication.Public(),
+        authorization: authentication.Authorization = authentication.Authorization(),
+    ):
+        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, readable_column_names, sortable_column_names, default_sort_column_name)
+
+    def check_search_in_request_data(self, request_data: dict[str, Any], query_parameters: dict[str, Any]) -> None:
+        for input_source_label, input_data in [("request body", request_data), ("URL data", query_parameters)]:
+            for column_name, value in input_data.items():
+                if column_name in self.allowed_request_keys and column_name not in self.searchable_column_names:
+                    continue
+                if column_name not in self.searchable_column_names:
+                    raise clearskies.exceptions.ClientError(
+                        f"Invalid request parameter found in {input_source_label}: '{column_name}'"
+                    )
+                [relationship_column_name, final_column_name] = self.unpack_column_name_with_relationship(column_name)
+                column_to_check = relationship_column_name if relationship_column_name else final_column_name
+                value_error = self.searchable_columns[column_to_check].check_search_value(
+                    value, relationship_reference=final_column_name
+                )
+                if value_error:
+                    raise clearskies.exceptions.InputErrors({column_name: value_error})
+
+    def configure_model_from_request_data(
+        self,
+        model: Model,
+        request_data: dict[str, Any],
+        query_parameters: dict[str, Any],
+        pagination_data: dict[str, Any],
+    ) -> Model:
+        model = super().configure_model_from_request_data(
+            model,
+            request_data,
+            query_parameters,
+            pagination_data,
+        )
+
+        for input_source in [request_data, query_parameters]:
+            for column_name, value in input_source.items():
+                if column_name not in self.searchable_column_names:
+                    continue
+
+                model = self.add_join(column_name, model)
+                [relationship_column_name, column_name] = self.unpack_column_name_with_relationship(column_name)
+                if relationship_column_name:
+                    self.columns[relationship_column_name].add_search(model, value, relationship_reference=column_name)
+                else:
+                    model = self.columns[column_name].add_search(model, value, operator="=")
+
+        return model
+
+    def documentation_url_search_parameters(self) -> list[autodoc.request.Parameter]:
+        docs = []
+        for column in self.searchable_columns.values():
+            column_doc = column.documentation()[0]
+            column_doc.name = self.auto_case_internal_column_name(column_doc.name)
+            docs.append(
+                autodoc.request.URLParameter(
+                    column_doc,
+                    description=f"Search by {column_doc.name} (via exact match)",
+                )
+            )
+        return docs  # type: ignore

clearskies/endpoints/update.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import inspect
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Callable, Type
+
+import clearskies.configs
+import clearskies.exceptions
+from clearskies import authentication, autodoc, typing
+from clearskies.endpoints.get import Get
+from clearskies.functional import routing, string
+from clearskies.input_outputs import InputOutput
+
+if TYPE_CHECKING:
+    from clearskies import SecurityHeader
+    from clearskies.model import Column, Model, Schema
+
+
+class Update(Get):
+    """
+    An endpoint to update a record.
+
+    This endpoint handles update operations.  As with the `Get` endpoint, it will lookup the record by taking
+    the record id (or any other unique column you specify) out of the URL and then will fetch that record
+    using the model class.  Then, it will use the model and list of writeable column names to validate the
+    incoming user input.  The default request method is `PATCH`.  If everything checks out, it will then
+    update the record.
+
+    ```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(validators=[clearskies.validators.Required()])
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Update(
+            model_class=User,
+            url="/{id}",
+            readable_column_names=["id", "name", "username"],
+            writeable_column_names=["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' -X PATCH -d '{"name": "Bobby Brown", "username": "bobbybrown"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "1-2-3-4",
+            "name": "Bobby Brown",
+            "username": "bobbybrown"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl 'http://localhost:8080/1-2-3-5' -X PATCH -d '{"name": 12345, "username": ""}' | jq
+    {
+        "status": "input_errors",
+        "error": "",
+        "data": [],
+        "pagination": {},
+        "input_errors": {
+            "name": "value should be a string",
+            "username": "'username' is required."
+        }
+    }
+    """
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        model_class: type[Model],
+        url: str,
+        writeable_column_names: list[str],
+        readable_column_names: list[str],
+        record_lookup_column_name: str | None = None,
+        input_validation_callable: Callable | None = None,
+        request_methods: list[str] = ["PATCH"],
+        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.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, readable_column_names)
+
+    def handle(self, input_output: InputOutput) -> Any:
+        request_data = self.get_request_data(input_output)
+        if not request_data and input_output.has_body():
+            raise clearskies.exceptions.ClientError("Request body was not valid JSON")
+        model = self.fetch_model(input_output)
+        self.validate_input_against_schema(request_data, input_output, model)
+        model.save(request_data)
+        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
+        # Many swagger UIs will only allow one response per status code, and we use the same status code (200)
+        # for both a success response and an input error response.  This could be fixed by changing the status
+        # code for input error responses, but there's not actually a great HTTP status code for that, so :shrug:
+        # standard_error_responses = [self.documentation_input_error_response()]
+        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_request_parameters(),
+                    *self.documentation_url_parameters(),
+                ],
+                root_properties={
+                    "security": self.documentation_request_security(),
+                },
+            ),
+        ]
+
+    def documentation_request_parameters(self) -> list[autodoc.request.Parameter]:
+        return [
+            *self.standard_json_request_parameters(self.model_class),
+        ]
+
+    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/environment.py

@@ -0,0 +1,104 @@
+import os.path
+from typing import Any
+
+
+class Environment:
+    """
+    This loads up the environment configuration for the application.
+
+    It looks in 3 possible places: first, it looks in os.environ.  Next, it tries to load up the .env file.
+    Therefore, the application root directory should be passed in, at will look for a .env file there.
+    It should contain lines like NAME=value.  Finally, if there is a value of `secret://path/to/secret`,
+    it will use the secret service to look up the secret value.
+
+    It is a very basic parser.  Empty lines and lines starting with a # will be ignored.  Otherwise everything
+    is assumed to be a string.
+    """
+
+    _env_file_config: dict[str, Any] = None  # type: ignore
+    _resolved_values: dict[str, Any] = {}
+    os_environ: dict[str, Any] = {}
+
+    def __init__(self, env_file_path, os_environ, secrets):
+        self._env_file_path = env_file_path
+        self.os_environ = os_environ
+        self.secrets = secrets
+        self._resolved_values = {}
+
+    def get(self, name, silent=False) -> Any:
+        self._load_env_file()
+        if name in self.os_environ:
+            return self.resolve_value(self.os_environ[name])
+        if name in self._env_file_config:
+            return self.resolve_value(self._env_file_config[name])
+
+        if not silent:
+            raise KeyError(f"Could not find environment config '{name}' in environment or .env file")
+        return None
+
+    def _load_env_file(self):
+        if self._env_file_config is not None:
+            return
+
+        self._env_file_config = {}
+        if not os.path.isfile(self._env_file_path):
+            return
+
+        with open(self._env_file_path, "r") as env_file:
+            line_number = 0
+            for line in env_file.readlines():
+                line_number += 1
+                (key, value) = self._parse_env_line(line, line_number)
+                if key is None:
+                    continue
+
+                self._env_file_config[key] = value
+
+    def _parse_env_line(self, line, line_number):
+        line = line.strip()
+        if not line:
+            return (None, None)
+        if line[0] == "#":
+            return (None, None)
+        if not "=" in line:
+            raise ValueError(f"Parse error in environment line #{line_number}: should be 'key=value'")
+
+        equal_index = line.index("=")
+        key = line[:equal_index].strip()
+        value = line[equal_index + 1 :].strip()
+        lc_value = value.lower()
+        if lc_value == "true":
+            return (key, True)
+        if lc_value == "false":
+            return (key, False)
+        if lc_value[0] == '"' and lc_value[-1] == '"':
+            return (key, value.strip('"'))
+        if lc_value[0] == "'" and lc_value[-1] == "'":
+            return (key, value.strip("'"))
+        try:
+            as_int = int(value)
+            return (key, as_int)
+        except:
+            pass
+        try:
+            as_float = float(value)
+            return (key, as_float)
+        except:
+            pass
+        return (key, value)
+
+    def resolve_value(self, value):
+        if type(value) != str or value[:9] != "secret://":
+            return value
+
+        secret_path = value[9:]
+        if secret_path[0] != "/":
+            secret_path = f"/{secret_path}"
+        if secret_path not in self._resolved_values:
+            if not self.secrets:
+                raise ValueError(
+                    "References to the secret engine were found in the environment, "
+                    + "but a secret engine was not provided"
+                )
+            self._resolved_values[secret_path] = self.secrets.get(secret_path)
+        return self._resolved_values[secret_path]

clearskies/exceptions/__init__.py

@@ -0,0 +1,19 @@
+from clearskies.exceptions.authentication import Authentication
+from clearskies.exceptions.authorization import Authorization
+from clearskies.exceptions.client_error import ClientError
+from clearskies.exceptions.input_errors import InputErrors
+from clearskies.exceptions.missing_dependency import MissingDependency
+from clearskies.exceptions.moved_permanently import MovedPermanently
+from clearskies.exceptions.moved_temporarily import MovedTemporarily
+from clearskies.exceptions.not_found import NotFound
+
+__all__ = [
+    "Authentication",
+    "Authorization",
+    "ClientError",
+    "InputErrors",
+    "MissingDependency",
+    "MovedPermanently",
+    "MovedTemporarily",
+    "NotFound",
+]

clearskies/exceptions/authentication.py

@@ -0,0 +1,2 @@
+class Authentication(Exception):
+    pass

clearskies/exceptions/authorization.py

@@ -0,0 +1,2 @@
+class Authorization(Exception):
+    pass

clearskies/exceptions/client_error.py

@@ -0,0 +1,2 @@
+class ClientError(Exception):
+    pass

clearskies/exceptions/input_errors.py

@@ -0,0 +1,4 @@
+class InputErrors(Exception):
+    def __init__(self, errors):
+        super().__init__(self, "Input Error")
+        self.errors = errors

clearskies/exceptions/missing_dependency.py

@@ -0,0 +1,2 @@
+class MissingDependency(Exception):
+    pass

clearskies/exceptions/moved_permanently.py

@@ -0,0 +1,3 @@
+class MovedPermanently(Exception):
+    def __init__(self, location):
+        super().__init__(self, location)

clearskies/exceptions/moved_temporarily.py

@@ -0,0 +1,3 @@
+class MovedTemporarily(Exception):
+    def __init__(self, location):
+        super().__init__(self, location)

clearskies/exceptions/not_found.py

@@ -0,0 +1,2 @@
+class NotFound(Exception):
+    pass

clearskies/functional/__init__.py

@@ -0,0 +1,7 @@
+from . import routing, string, validations
+
+__all__ = [
+    "routing",
+    "string",
+    "validations",
+]