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

clearskies/columns/belongs_to_id.py

@@ -0,0 +1,478 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import configs, decorators
+from clearskies.autodoc.schema import Object as AutoDocObject
+from clearskies.autodoc.schema import Schema as AutoDocSchema
+from clearskies.autodoc.schema import String as AutoDocString
+from clearskies.columns.string import String
+from clearskies.di.inject import InputOutput
+from clearskies.functional import validations
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+class BelongsToId(String):
+    """
+    Declares that this model belongs to another - that it has a parent.
+
+    ## Usage
+
+    The way that a belongs to relationship works is that the child model (e.g. the one with
+    the BelongsToId column) needs to have a column that stores the id of the parent it is related
+    to.  Then you can attach the BelongsToModel class and point it to the column containing the
+    id.  If you allow the end-user to set the parent id in a save action, the belongs to column
+    will automatically verify that the given id corresponds to an actual record.  Here's a simple
+    usage example:
+
+    ```python
+    import clearskies
+
+
+    class Category(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+
+    class Product(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        category_id = clearskies.columns.BelongsToId(Category)
+        category = clearskies.columns.BelongsToModel("category_id")
+
+
+    def test_belongs_to(products: Product, categories: Category):
+        toys = categories.create({"name": "Toys"})
+        auto = categories.create({"name": "Auto"})
+
+        # Note: we set the cateogry by setting "category_id"
+        ball = products.create({"name": "ball", "category_id": toys.id})
+
+        # note: we set the category by saving a category model to "category"
+        fidget_spinner = products.create({"name": "Fidget Spinner", "category": toys})
+
+        return {
+            "ball_category": ball.category.name,
+            "fidget_spinner_category": fidget_spinner.category.name,
+            "ball_id_check": ball.category_id == ball.category.id,
+            "ball_fidget_id_check": fidget_spinner.category_id == ball.category.id,
+        }
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(test_belongs_to),
+        classes=[Category, Product],
+    )
+
+    if __name__ == "__main__":
+        cli()
+    ```
+
+    ## Circular Dependency Trees
+
+    The opposite of a BelongsToId relationship is a HasMany relationship.  It's common
+    for the child model to contain a BelonsToId column to point to the parent, and then
+    have the parent contain a HasMany column to point to the child.  This creates circular
+    depenency errors in python.  To work around this, clearskies requires the addition of
+    a "model reference" class that looks like this:
+
+    ```python
+    import some_model
+
+
+    class SomeModelReference:
+        def get_model_class(self):
+            return some_model.SomeModel
+    ```
+
+    These have to live in their own file, should use relative imports to import the file containing
+    the model, and should not be imported into the module they live in.  So, sticking with the example
+    of categories and products, you would have the following directory structure:
+
+    ```
+    ├── models
+    │   ├── category.py
+    │   ├── category_reference.py
+    │   ├── product.py
+    │   └── product_reference.py
+    │
+    └── app.py
+    ```
+
+    The files would then contain:
+
+    category.py
+    ```python
+    import clearskies
+    import models.product_reference
+
+
+    class Category(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        products = clearskies.columns.HasMany(product_reference.ProductReference)
+    ```
+
+    category_reference.py
+    ```python
+    from clearskies.model import ModelClassReference
+    from . import cateogry
+
+
+    class CategoryReference(ModelClassReference):
+        def get_model_class(self):
+            return category.Category
+    ```
+
+    product.py
+    ```python
+    import clearskies
+    import models.category_reference
+
+
+    class Product(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        category_id = clearskies.columns.BelongsToId(CategoryReference)
+        category = clearskies.columns.BelongsToModel("category_id")
+    ```
+
+    product_reference.py
+    ```python
+    from clearskies.model import ModelClassReference
+    from . import product
+
+
+    class ProductReference(ModelClassReference):
+        def get_model_class(self):
+            return product.Product
+    ```
+    """
+
+    """ The model class we belong to. """
+    parent_model_class = configs.ModelClass(required=True)
+
+    """
+    The name of the property used to fetch the parent model itself.
+
+    Note that this isn't set explicitly, but by adding a BelongsToModel column to the model.
+    """
+    model_column_name = configs.String()
+
+    """
+    The list of columns from the parent that should be included when converting this column to JSON.
+
+    When configuring readable columns for an endpoint, you can specify the BelongsToModel column.
+    If you do this, you must set readable_parent_columns on the BelongsToId column to specify which
+    columns from the parent model should be returned in the response.  See this example:
+
+    ```python
+    import clearskies
+
+    class Owner(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+    class Pet(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        owner_id = clearskies.columns.BelongsToId(
+            Owner,
+            readable_parent_columns=["id", "name"],
+        )
+        owner = clearskies.columns.BelongsToModel("owner_id")
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.List(
+            Pet,
+            sortable_column_names=["id", "name"],
+            readable_column_names=["id", "name", "owner"],
+            default_sort_column_name="name",
+        ),
+        classes=[Owner, Pet],
+        bindings={
+            "memory_backend_default_data": [
+                {
+                    "model_class": Owner,
+                    "records": [
+                        {"id": "1-2-3-4", "name": "John Doe"},
+                        {"id": "5-6-7-8", "name": "Jane Doe"},
+                    ],
+                },
+                {
+                    "model_class": Pet,
+                    "records": [
+                        {"id": "a-b-c-d", "name": "Fido", "owner_id": "1-2-3-4"},
+                        {"id": "e-f-g-h", "name": "Spot", "owner_id": "1-2-3-4"},
+                        {"id": "i-j-k-l", "name": "Puss in Boots", "owner_id": "5-6-7-8"},
+                    ],
+                },
+            ],
+        }
+    )
+
+    if __name__ == "__main__":
+        cli()
+    ```
+
+    With readable_parent_columns set in the Pet.owner_id column, and owner set in the list configuration,
+    The owner id and name are included in the `owner` key of the returned Pet dictionary:
+
+    ```bash
+    $ ./test.py  | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": [
+            {
+                "id": "a-b-c-d",
+                "name": "Fido",
+                "owner": {
+                    "id": "1-2-3-4",
+                    "name": "John Doe"
+                }
+            },
+            {
+                "id": "i-j-k-l",
+                "name": "Puss in Boots",
+                "owner": {
+                    "id": "5-6-7-8",
+                    "name": "Jane Doe"
+                }
+            },
+            {
+                "id": "e-f-g-h",
+                "name": "Spot",
+                "owner": {
+                    "id": "1-2-3-4",
+                    "name": "John Doe"
+                }
+            }
+        ],
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    """
+    readable_parent_columns = configs.ReadableModelColumns("parent_model_class")
+
+    """
+    The type of join to use when searching on the parent.
+    """
+    join_type = configs.Select(["LEFT", "INNER", "RIGHT"], default="LEFT")
+
+    """
+    Any additional conditions to place on the parent table when finding related records.
+
+    where should be a list containing a combination of conditions-as-strings, queries built from the columns
+    themselves, or callable functions which accept the model and apply filters.  This is primarily used in
+    input validation to exclude values as allowed parents.
+    """
+    where = configs.Conditions()
+
+    input_output = InputOutput()
+    wants_n_plus_one = True
+    _allowed_search_operators = ["="]
+    _descriptor_config_map = None
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        parent_model_class,
+        readable_parent_columns: list[str] = [],
+        join_type: str | None = None,
+        where: typing.condition | list[typing.condition] = [],
+        default: str | None = None,
+        setable: str | Callable | None = None,
+        is_readable: bool = True,
+        is_writeable: bool = True,
+        is_searchable: bool = True,
+        is_temporary: bool = False,
+        validators: typing.validator | list[typing.validator] = [],
+        on_change_pre_save: typing.action | list[typing.action] = [],
+        on_change_post_save: typing.action | list[typing.action] = [],
+        on_change_save_finished: typing.action | list[typing.action] = [],
+        created_by_source_type: str = "",
+        created_by_source_key: str = "",
+        created_by_source_strict: bool = True,
+    ):
+        pass
+
+    @property
+    def parent_model(self) -> Model:
+        parents = self.di.build(self.parent_model_class, cache=True)
+        if not self.where:
+            return parents
+
+        return self.apply_wheres(parents)
+
+    def apply_wheres(self, parents: Model) -> Model:
+        if not self.where:
+            return parents
+
+        for index, where in enumerate(self.where):
+            if callable(where):
+                parents = self.di.call_function(where, model=parents, **self.input_output.get_context_for_callables())
+                if not validations.is_model(parents):
+                    raise ValueError(
+                        f"Configuration error for {self.model_class.__name__}.{self.name}: when 'where' is a callable, it must return a model class, but when the callable in where entry #{index + 1} was called, it returned something else."
+                    )
+            else:
+                parents = parents.where(where)
+        return parents
+
+    @property
+    def parent_columns(self) -> dict[str, Any]:
+        return self.parent_model_class.get_columns()
+
+    def input_error_for_value(self, value: str, operator: str | None = None) -> str:
+        parent_check = super().input_error_for_value(value)
+        if parent_check:
+            return parent_check
+        parent_model = self.parent_model
+        matching_parents = parent_model.where(f"{parent_model.id_column_name}={value}")
+        matching_parents = self.apply_wheres(matching_parents)
+        matching_parents = matching_parents.where_for_request_all(
+            matching_parents,
+            self.input_output,
+            routing_data=self.input_output.routing_data,
+            authorization_data=self.input_output.authorization_data,
+        )
+        if not len(matching_parents):
+            return f"Invalid selection for {self.name}: record does not exist"
+        return ""
+
+    def n_plus_one_add_joins(self, model: Model, column_names: list[str] = []) -> Model:
+        """Add any additional joins to solve the N+1 problem."""
+        if not column_names:
+            column_names = self.readable_parent_columns
+        if not column_names:
+            return model
+
+        model = self.add_join(model)
+        alias = self.join_table_alias()
+        parent_id_column_name = self.parent_model.id_column_name
+        select_parts = [f"{alias}.{column_name} AS {alias}_{column_name}" for column_name in column_names]
+        if parent_id_column_name not in column_names:
+            select_parts.append(f"{alias}.{parent_id_column_name} AS {alias}_{parent_id_column_name}")
+        return model.select(", ".join(select_parts))
+
+    def add_join(self, model: Model) -> Model:
+        parent_table = self.parent_model.destination_name()
+        alias = self.join_table_alias()
+
+        if model.is_joined(parent_table, alias=alias):
+            return model
+
+        join_type = "LEFT " if self.join_type == "LEFT" else ""
+        own_table_name = model.destination_name()
+        parent_id_column_name = self.parent_model.id_column_name
+        return model.join(
+            f"{join_type}JOIN {parent_table} as {alias} on {alias}.{parent_id_column_name}={own_table_name}.{self.name}"
+        )
+
+    def join_table_alias(self) -> str:
+        return self.parent_model.destination_name() + "_" + self.name
+
+    def is_allowed_operator(self, operator, relationship_reference=None):
+        """Proces user data to decide if the end-user is specifying an allowed operator."""
+        if not relationship_reference:
+            return "="
+        parent_columns = self.parent_columns
+        if relationship_reference not in self.parent_columns:
+            raise ValueError(
+                "I was asked to search on a related column that doens't exist.  This shouldn't have happened :("
+            )
+        return self.parent_columns[relationship_reference].is_allowed_operator(operator)
+
+    def check_search_value(self, value, operator=None, relationship_reference=None):
+        if not relationship_reference:
+            return self.input_error_for_value(value, operator=operator)
+        parent_columns = self.parent_columns
+        if relationship_reference not in self.parent_columns:
+            raise ValueError(
+                "I was asked to search on a related column that doens't exist.  This shouldn't have happened :("
+            )
+        return self.parent_columns[relationship_reference].check_search_value(value, operator=operator)
+
+    def is_allowed_search_operator(self, operator: str, relationship_reference: str = "") -> bool:
+        if not relationship_reference:
+            return operator in self._allowed_search_operators
+        parent_columns = self.parent_columns
+        if relationship_reference not in self.parent_columns:
+            raise ValueError(
+                "I was asked to check search operators on a related column that doens't exist.  This shouldn't have happened :("
+            )
+        return self.parent_columns[relationship_reference].is_allowed_search_operator(
+            operator, relationship_reference=relationship_reference
+        )
+
+    def allowed_search_operators(self, relationship_reference: str = ""):
+        if not relationship_reference:
+            return self._allowed_search_operators
+        parent_columns = self.parent_columns
+        if relationship_reference not in self.parent_columns:
+            raise ValueError(
+                "I was asked for allowed search operators on a related column that doens't exist.  This shouldn't have happened :("
+            )
+        return self.parent_columns[relationship_reference].allowed_search_operators()
+
+    def add_search(self, model: Model, value: str, operator: str = "", relationship_reference: str = "") -> Model:
+        if not relationship_reference:
+            return super().add_search(model, value, operator=operator)
+
+        if relationship_reference not in self.parent_columns:
+            raise ValueError(
+                "I was asked to search on a related column that doens't exist.  This shouldn't have happened :("
+            )
+
+        model = self.add_join(model)
+        related_column = self.parent_columns[relationship_reference]
+        alias = self.join_table_alias()
+        return model.where(related_column.build_condition(value, operator=operator, column_prefix=f"{alias}."))
+
+    def documentation(
+        self, name: str | None = None, example: str | None = None, value: str | None = None
+    ) -> list[AutoDocSchema]:
+        columns = self.parent_columns
+        parent_id_column_name = self.parent_model.id_column_name
+        parent_properties = [columns[parent_id_column_name].documentation()]
+        parent_id_doc = AutoDocString(name if name is not None else self.name)
+
+        readable_parent_columns = self.readable_parent_columns
+        if not readable_parent_columns:
+            return [parent_id_doc]
+
+        for column_name in readable_parent_columns:
+            if column_name == parent_id_column_name:
+                continue
+            parent_properties.append(columns[column_name].documentation())
+
+        return [
+            parent_id_doc,
+            AutoDocObject(
+                self.model_column_name,
+                parent_properties,
+            ),
+        ]

clearskies/columns/belongs_to_model.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Self, overload
+
+from clearskies import configs, decorators
+from clearskies.column import Column
+from clearskies.columns.belongs_to_id import BelongsToId
+from clearskies.functional import validations
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class BelongsToModel(Column):
+    """Return the model object for a belongs to relationship."""
+
+    """ The name of the belongs to column we are connected to. """
+    belongs_to_column_name = configs.ModelColumn(required=True)
+
+    is_temporary = configs.boolean.Boolean(default=True)
+    _descriptor_config_map = None
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        belongs_to_column_name: str,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class: type, name: str) -> None:
+        """Finalize and check the configuration."""
+        getattr(self.__class__, "belongs_to_column_name").set_model_class(model_class)
+        self.model_class = model_class
+        self.name = name
+        self.finalize_and_validate_configuration()
+
+        # finally, let the belongs to column know about us and make sure it's the right thing.
+        belongs_to_column = getattr(model_class, self.belongs_to_column_name)
+        if not isinstance(belongs_to_column, BelongsToId):
+            raise ValueError(
+                f"Error with configuration for {model_class.__name__}.{name}, which is a BelongsToModel.  It needs to point to a belongs to column, and it was told to use {model_class.__name__}.{self.belongs_to_column_name}, but this is not a BelongsToId column."
+            )
+        belongs_to_column.model_column_name = name
+
+    @overload
+    def __get__(self, model: None, cls: type[Model]) -> Self:
+        pass
+
+    @overload
+    def __get__(self, model: Model, cls: type[Model]) -> Model:
+        pass
+
+    def __get__(self, model, cls):
+        if model is None:
+            self.model_class = cls
+            return self  # type:  ignore
+
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            model.get_columns()
+
+        belongs_to_column = getattr(model.__class__, self.belongs_to_column_name)
+        parent_id = getattr(model, self.belongs_to_column_name)
+        parent_class = belongs_to_column.parent_model_class
+        parent_model = self.di.build(parent_class, cache=False)
+        if not parent_id:
+            return parent_model.empty()
+
+        parent_id_column_name = parent_model.id_column_name
+        join_alias = belongs_to_column.join_table_alias()
+        raw_data = model.get_raw_data()
+
+        # sometimes the model is loaded via the N+1 functionality, in which case the data will already exist
+        # in model.data but hiding under a different name.
+        if raw_data.get(f"{join_alias}.{parent_id_column_name}"):
+            parent_data = {parent_id_column_name: raw_data[f"{join_alias}_{parent_id_column_name}"]}
+            for column_name in belongs_to_column.readable_parent_columns:
+                select_alias = f"{join_alias}_{column_name}"
+                parent_data[column_name] = raw_data[select_alias] if select_alias in raw_data else None
+            return parent_model.model(parent_data)
+
+        return parent_model.find(f"{parent_id_column_name}={parent_id}")
+
+    def __set__(self, model: Model, value: Model) -> None:
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            model.get_columns()
+
+        setattr(model, self.belongs_to_column_name, getattr(value, value.id_column_name))
+
+    def pre_save(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        # if we have a model coming in then we want to extract the id.  Either way, the model id needs to go to the
+        # belongs_to_id column, which is the only one that is actually saved.
+        if self.name in data:
+            value = data[self.name]
+            data[self.belongs_to_column_name] = (
+                getattr(value, value.id_column_name) if validations.is_model(value) else value
+            )
+        return super().pre_save(data, model)
+
+    def add_join(self, model: Model) -> Model:
+        return getattr(model.__class__, self.belongs_to_column_name).add_join(model)
+
+    def join_table_alias(self) -> str:
+        return getattr(self.model_class, self.belongs_to_column_name).join_table_alias()
+
+    def add_search(self, model: Model, value: str, operator: str = "", relationship_reference: str = "") -> Model:
+        return getattr(self.model_class, self.belongs_to_column_name).add_search(
+            model, value, operator, relationship_reference=relationship_reference
+        )
+
+    def to_json(self, model: Model) -> dict[str, Any]:
+        """Convert the column into a json-friendly representation."""
+        belongs_to_column = getattr(model.__class__, self.belongs_to_column_name)
+        if not belongs_to_column.readable_parent_columns:
+            raise ValueError(
+                f"Configuration error for {model.__class__.__name__}: I can't convert to JSON unless you set readable_parent_columns on my parent attribute, {model.__class__.__name__}.{self.belongs_to_column_name}."
+            )
+
+        # otherwise return an object with the readable parent columns
+        columns = belongs_to_column.parent_columns
+        parent = getattr(model, self.name)
+        json: dict[str, Any] = OrderedDict()
+        for column_name in belongs_to_column.readable_parent_columns:
+            json = {**json, **columns[column_name].to_json(parent)}  # type: ignore
+        return {
+            self.name: json,
+        }