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

clearskies/endpoints/simple_search.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import authentication, autodoc, decorators, exceptions
+from clearskies.endpoints.list import List
+
+if TYPE_CHECKING:
+    from clearskies import Column, Model, Schema, SecurityHeader, typing
+
+
+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": {}
+    }
+    ```
+    """
+
+    @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 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 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,188 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import authentication, autodoc, decorators, exceptions
+from clearskies.endpoints.get import Get
+from clearskies.functional import string
+from clearskies.input_outputs import InputOutput
+
+if TYPE_CHECKING:
+    from clearskies import Column, Model, Schema, SecurityHeader, typing
+
+
+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."
+        }
+    }
+    """
+
+    @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 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

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import os.path
+from typing import Any
 
 
 class Environment:
@@ -14,8 +17,9 @@ class Environment:
     is assumed to be a string.
     """
 
-    _env_file_config = None
-    _resolved_values = None
+    _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
@@ -23,7 +27,7 @@ class Environment:
         self.secrets = secrets
         self._resolved_values = {}
 
-    def get(self, name, silent=False):
+    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])

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/{handlers/exceptions/input_error.py → exceptions/input_errors.py}

@@ -1,4 +1,4 @@
-class InputError(Exception):
+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/functional/__init__.py

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

clearskies/functional/json.py

@@ -0,0 +1,47 @@
+from typing import Any, cast
+
+
+def get_nested_attribute(data: dict[str, Any] | str, attr_path: str) -> Any:
+    """
+    Extract a nested attribute from JSON data using dot notation.
+
+    This function navigates through a nested JSON structure using a dot-separated path
+    to retrieve a specific attribute. If the input is a string, it will attempt to parse
+    it as JSON first.
+
+    Example:
+    ```
+    data = {"database": {"credentials": {"username": "admin", "password": "secret"}}}
+    username = get_nested_attribute(data, "database.credentials.username")
+    # Returns "admin"
+    ```
+
+    Args:
+        data: The JSON data as a dictionary or a JSON string
+        attr_path: The path to the attribute using dot notation (e.g., "database.username")
+
+    Returns:
+        The value at the specified path
+
+    Raises:
+        ValueError: If the data cannot be parsed as JSON
+        KeyError: If the attribute path doesn't exist in the data
+    """
+    keys = attr_path.split(".", 1)
+    if not isinstance(data, dict):
+        try:
+            import json
+
+            data = json.loads(data)
+        except Exception:
+            raise ValueError(f"Could not parse data as JSON to get attribute '{attr_path}'")
+
+    # At this point, we know data is a dictionary
+    data_dict = cast(dict[str, Any], data)  # Help type checker understand data is a dict
+
+    if len(keys) == 1:
+        if keys[0] not in data_dict:
+            raise KeyError(f"Data does not contain attribute '{attr_path}'")
+        return data_dict[keys[0]]
+
+    return get_nested_attribute(data_dict[keys[0]], keys[1])

clearskies/functional/routing.py

@@ -0,0 +1,92 @@
+import re
+
+
+def match_route(expected_route, incoming_route, allow_partial=False) -> tuple[bool, dict[str, str]]:
+    """
+    Check if two routes match, and returns the routing data if so.
+
+    A partial match happens when the beginning of the incoming route matches the expected route.  It's okay for the
+    incoming route to be longer because the routing system is hierarchical, so a partial match at the beginning
+    can work.  e.g.:
+
+    Expected route: `/users`
+    Incoming route: `/users/orders/5`
+
+    But note that it must fully match all route segments, so this is never a match:
+
+    Expected route: `/user`
+    Incoming route: `/users/orders/5`
+    """
+    expected_route = expected_route.strip("/")
+    incoming_route = incoming_route.strip("/")
+
+    expected_parts = expected_route.split("/")
+    incoming_parts = incoming_route.split("/")
+
+    # quick check: if there are less parts in the incoming route than the expected route, then we can't possibly match
+    if len(incoming_parts) < len(expected_parts):
+        return (False, {})
+    # ditto the opposite, if we can't do a partial match
+    if len(expected_parts) < len(incoming_parts) and not allow_partial:
+        return (False, {})
+
+    # if we got this far then we will do a more complete match, so let's find any routing parameters
+    routing_data = {}
+    routing_parameters = extract_url_parameter_name_map(expected_route)
+    # we want it backwards
+    routing_parameters_by_index = {value: key for (key, value) in routing_parameters.items()}
+    for index in range(len(expected_parts)):
+        if index in routing_parameters_by_index:
+            if not incoming_parts[index]:
+                return (False, {})
+            routing_data[routing_parameters_by_index[index]] = incoming_parts[index]
+        else:
+            if expected_parts[index] != incoming_parts[index]:
+                return (False, {})
+
+    return (True, routing_data)
+
+
+def extract_url_parameter_name_map(url: str) -> dict[str, int]:
+    """
+    Create a map to help match URLs with routing parameters.
+
+    Routing parameters are either brace enclosed or start with colons:
+
+    ```python
+    print(
+        routing.extract_url_parameter_name_map("my/path/{some_parameter}/:other_parameter/more/paths")
+    )
+    # prints {"some_parameter": 2, "other_parameter": 3}
+    ```
+
+    Note that leading and trailing slashes are stripped, so "/my/path/{id}" and "my/path/{id}" give identical
+    parameter maps: `{"id": 2}`
+    """
+    parameter_name_map = {}
+    path_parts = url.strip("/").split("/")
+    for index, part in enumerate(path_parts):
+        if not part:
+            continue
+        if part[0] == ":":
+            match = re.match("^:(\\w[\\w\\d_]{0,})$", part)
+        else:
+            if part[0] != "{":
+                continue
+            if part[-1] != "}":
+                raise ValueError(
+                    f"Invalid route configuration for URL '{url}': section '{part}'"
+                    + " starts with a '{' but does not end with one"
+                )
+            match = re.match("^{(\\w[\\w\\d_]{0,})\\}$", part)
+        if not match:
+            raise ValueError(
+                f"Invalid route configuration for URL '{url}', section '{part}': resource identifiers must start with a letter and contain only letters, numbers, and underscores"
+            )
+        parameter_name = match.group(1)
+        if parameter_name in parameter_name_map:
+            raise ValueError(
+                f"Invalid route configuration for URL '{url}', a URL path named '{parameter_name}' appeared more than once."
+            )
+        parameter_name_map[parameter_name] = index
+    return parameter_name_map