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

clearskies/columns/belongs_to_self.py

@@ -0,0 +1,105 @@
+from typing import Callable
+
+import clearskies.decorators
+import clearskies.typing
+from clearskies.columns.belongs_to_id import BelongsToId
+
+
+class BelongsToSelf(BelongsToId):
+    """
+    This is a standard BelongsToId column except it's used in cases where the model relates to itself.
+
+    This exists because a model can't refer to itself inside it's own class definition.  There are
+    workarounds, but having this class is usually quicker for the developer.
+
+    The only difference between this and BelongsToId is that you don't have to provide the parent class.
+
+    See also HasManySelf
+
+    ```python
+    from typing import Any
+
+    import clearskies
+
+
+    class Category(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        parent_id = clearskies.columns.BelongsToSelf()
+        parent = clearskies.columns.BelongsToModel("parent_id")
+        children = clearskies.columns.HasManySelf()
+
+
+    def test_self_relationship(categories: Category) -> dict[str, Any]:
+        root = categories.create({"name": "Root"})
+        sub = categories.create({"name": "Sub", "parent": root})
+        subsub_1 = categories.create({"name": "Sub Sub 1", "parent": sub})
+        subsub_2 = categories.create({"name": "Sub Sub 2", "parent_id": sub.id})
+
+        return {
+            "root_from_child": subsub_1.parent.parent.name,
+            "subsubs_from_sub": [subsub.name for subsub in sub.children],
+        }
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(test_self_relationship),
+        classes=[Category],
+    )
+
+    if __name__ == "__main__":
+        cli()
+    ```
+
+    Which when invoked returns:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {"root_from_child": "Root", "subsubs_from_sub": ["Sub Sub 1", "Sub Sub 2"]},
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+    """
+
+    _descriptor_config_map = None
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        readable_parent_columns: list[str] = [],
+        join_type: str | None = None,
+        where: clearskies.typing.condition | list[clearskies.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: clearskies.typing.validator | list[clearskies.typing.validator] = [],
+        on_change_pre_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_post_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_save_finished: clearskies.typing.action | list[clearskies.typing.action] = [],
+        created_by_source_type: str = "",
+        created_by_source_key: str = "",
+        created_by_source_strict: bool = True,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class, name) -> None:
+        """
+        Finalize and check the configuration.
+
+        This is an external trigger called by the model class when the model class is ready.
+        The reason it exists here instead of in the constructor is because some columns are tightly
+        connected to the model class, and can't validate configuration until they know what the model is.
+        Therefore, we need the model involved, and the only way for a property to know what class it is
+        in is if the parent class checks in (which is what happens here).
+        """
+        self.parent_model_class = model_class
+        super().finalize_configuration(model_class, name)

clearskies/columns/boolean.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Self, overload
+
+import clearskies.configs.actions
+import clearskies.decorators
+import clearskies.typing
+from clearskies import configs
+from clearskies.autodoc.schema import Boolean as AutoDocBoolean
+from clearskies.autodoc.schema import Schema as AutoDocSchema
+from clearskies.column import Column
+from clearskies.query import Condition
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class Boolean(Column):
+    """Represents a column with a true/false type."""
+
+    """
+    Actions to trigger when the column changes to True
+    """
+    on_true = clearskies.configs.actions.Actions(default=[])
+
+    """
+    Actions to trigger when the column changes to False
+    """
+    on_false = clearskies.configs.actions.Actions(default=[])
+
+    """
+    The class to use when documenting this column
+    """
+    auto_doc_class: type[AutoDocSchema] = AutoDocBoolean
+
+    _allowed_search_operators = ["="]
+    default = configs.Boolean()  #  type: ignore
+    setable = configs.BooleanOrCallable()  #  type: ignore
+    _descriptor_config_map = None
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        default: bool | None = None,
+        setable: bool | Callable[..., bool] | None = None,
+        is_readable: bool = True,
+        is_writeable: bool = True,
+        is_searchable: bool = True,
+        is_temporary: bool = False,
+        validators: clearskies.typing.validator | list[clearskies.typing.validator] = [],
+        on_change_pre_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_post_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_save_finished: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_true: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_false: clearskies.typing.action | list[clearskies.typing.action] = [],
+        created_by_source_type: str = "",
+        created_by_source_key: str = "",
+        created_by_source_strict: bool = True,
+    ):
+        pass
+
+    def from_backend(self, value) -> bool:
+        if value == "0":
+            return False
+        return bool(value)
+
+    def to_backend(self, data):
+        if self.name not in data:
+            return data
+
+        return {**data, self.name: bool(data[self.name])}
+
+    @overload
+    def __get__(self, instance: None, cls: type[Model]) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: Model, cls: type[Model]) -> bool:
+        pass
+
+    def __get__(self, instance, cls):
+        return super().__get__(instance, cls)
+
+    def __set__(self, instance, value: bool) -> None:
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            instance.get_columns()
+
+        instance._next_data[self.name] = value
+
+    def input_error_for_value(self, value: str, operator: str | None = None) -> str:
+        return f"{self.name} must be a boolean" if type(value) != bool else ""
+
+    def build_condition(self, value: str, operator: str | None = None, column_prefix: str = ""):
+        condition_value = "1" if value else "0"
+        if not operator:
+            operator = "="
+        return f"{column_prefix}{self.name}{operator}{condition_value}"
+
+    def save_finished(self, model: Model) -> None:
+        """Make any necessary changes needed after a save has completely finished."""
+        super().save_finished(model)
+
+        if (not self.on_true and not self.on_false) or not model.was_changed(self.name):
+            return
+
+        if getattr(model, self.name) and self.on_true:
+            self.execute_actions(self.on_true, model)
+        if not getattr(model, self.name) and self.on_false:
+            self.execute_actions(self.on_false, model)
+
+    def equals(self, value: bool) -> Condition:
+        return super().equals(value)

clearskies/columns/category_tree.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+import clearskies.decorators
+import clearskies.typing
+from clearskies import configs
+from clearskies.columns.belongs_to_id import BelongsToId
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class CategoryTree(BelongsToId):
+    """
+    The category tree helps you do quick lookups on a typical category tree.
+
+    It's a very niche tool.  In general, graph databases solve this problem better, but
+    it's not always worth the effort of spinning up a new kind of database.
+
+    This column needs a special tree table where it will pre-compute and store the
+    necessary information to perform quick lookups about relationships in a cateogry
+    tree.  So, imagine you have a table that represents a standard category heirarchy:
+
+    ```sql
+    CREATE TABLE categories (
+      id varchar(255),
+      parent_id varchar(255),
+      name varchar(255)
+    )
+
+    `parent_id`, in this case, would be a reference to the `categories` table itself -
+    hence the heirarchy.  This works fine  as a starting point but it gets tricky when you want to answer questions like
+    "what are all the parent categories of category X?" or "what are all the child categories of category Y?".
+    This column class solves that by building a tree table that caches this data as the categories are updated.
+    That table should look like this:
+
+    ```sql
+    CREATE TABLE category_tree (
+      id varchar(255),
+      parent_id varchar(255),
+      child_id varchar(255),
+      is_parent tinyint(1),
+      level tinyint(1),
+    )
+    ```
+
+    Then you would attach this column to your category model as a replacement for a typical BelongsToId relationship:
+
+    ```python
+    import clearskies
+
+    class Tree(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend(silent_on_missing_tables=True)
+
+        id = clearskies.columns.Uuid()
+        parent_id = clearskies.columns.String()
+        child_id = clearskies.columns.String()
+        is_parent = clearskies.columns.Boolean()
+        level = clearskies.columns.Integer()
+
+    class Category(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend(silent_on_missing_tables=True)
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        parent_id = clearskies.columns.CategoryTree(Tree)
+        parent = clearskies.columns.BelongsToModel("parent_id")
+        children = clearskies.columns.CategoryTreeChildren("parent_id")
+        descendants = clearskies.columns.CategoryTreeDescendants("parent_id")
+        ancestors = clearskies.columns.CategoryTreeAncestors("parent_id")
+
+    def test_category_tree(category: Category):
+        root_1 = category.create({"name": "Root 1"})
+        root_2 = category.create({"name": "Root 2"})
+        sub_1_root_1 = category.create({"name": "Sub 1 of Root 1", "parent_id": root_1.id})
+        sub_2_root_1 = category.create({"name": "Sub 2 of Root 1", "parent_id": root_1.id})
+        sub_sub = category.create({"name": "Sub Sub", "parent_id": sub_1_root_1.id})
+        sub_1_root_2 = category.create({"name": "Sub 1 of Root 2", "parent_id": root_2.id})
+
+        return {
+            "descendants_of_root_1": [descendant.name for descendant in root_1.descendants],
+            "children_of_root_1": [child.name for child in root_1.children],
+            "descendants_of_root_2": [descendant.name for descendant in root_2.descendants],
+            "ancestors_of_sub_sub": [ancestor.name for ancestor in sub_sub.ancestors],
+        }
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(test_category_tree),
+        classes=[Category, Tree],
+    )
+    cli()
+    ```
+
+    And if you invoke the above you will get:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "descendants_of_root_1": ["Sub 1 of Root 1", "Sub 2 of Root 1", "Sub Sub"],
+            "children_of_root_1": ["Sub 1 of Root 1", "Sub 2 of Root 1"],
+            "descendants_of_root_2": ["Sub 1 of Root 2"],
+            "ancestors_of_sub_sub": ["Root 1", "Sub 1 of Root 1"],
+        },
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+
+    In case it's not clear, the definition of these things are:
+
+     1. Descendants: All children under a given category (recursively).
+     2. Children: The direct descendants of a given category.
+     3. Ancestors: The parents of a given category, starting from the root category.
+     4. Parent: the immediate parent of the category.
+
+    """
+
+    """
+    The model class that will persist our tree data
+    """
+    tree_model_class = configs.ModelClass(required=True)
+
+    """
+    The column in the tree model that references the parent in the relationship
+    """
+    tree_parent_id_column_name = configs.ModelColumn("tree_model_class", default="parent_id")
+
+    """
+    The column in the tree model that references the child in the relationship
+    """
+    tree_child_id_column_name = configs.ModelColumn("tree_model_class", default="child_id")
+
+    """
+    The column in the tree model that denotes which node in the relationship represents the tree
+    """
+    tree_is_parent_column_name = configs.ModelColumn("tree_model_class", default="is_parent")
+
+    """
+    The column in the tree model that references the parent in a relationship
+    """
+    tree_level_column_name = configs.ModelColumn("tree_model_class", default="level")
+
+    """
+    The maximum expected depth of the tree
+    """
+    max_iterations = configs.Integer(default=100)
+
+    """
+    The strategy for loading relatives.
+
+    Choose whatever one actually works for your backend
+
+     * JOIN: use an actual `JOIN` (e.g. quick and efficient, but mostly only works for SQL backends).
+     * WHERE IN: Use a `WHERE IN` condition.
+     * INDIVIDUAL: Load each record separately.  Works for any backend but is also the slowest.
+    """
+    load_relatives_strategy = configs.Select(["join", "where_in", "individual"], default="join")
+
+    _descriptor_config_map = None
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        tree_model_class,
+        tree_parent_id_column_name: str = "parent_id",
+        tree_child_id_column_name: str = "child_id",
+        tree_is_parent_column_name: str = "is_parent",
+        tree_level_column_name: str = "level",
+        max_iterations: int = 100,
+        load_relatives_strategy: str = "join",
+        readable_parent_columns: list[str] = [],
+        join_type: str | None = None,
+        where: clearskies.typing.condition | list[clearskies.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: clearskies.typing.validator | list[clearskies.typing.validator] = [],
+        on_change_pre_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_post_save: clearskies.typing.action | list[clearskies.typing.action] = [],
+        on_change_save_finished: clearskies.typing.action | list[clearskies.typing.action] = [],
+        created_by_source_type: str = "",
+        created_by_source_key: str = "",
+        created_by_source_strict: bool = True,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class, name) -> None:
+        """
+        Finalize and check the configuration.
+
+        This is an external trigger called by the model class when the model class is ready.
+        The reason it exists here instead of in the constructor is because some columns are tightly
+        connected to the model class, and can't validate configuration until they know what the model is.
+        Therefore, we need the model involved, and the only way for a property to know what class it is
+        in is if the parent class checks in (which is what happens here).
+        """
+        self.parent_model_class = model_class
+        super().finalize_configuration(model_class, name)
+
+    @property
+    def tree_model(self):
+        return self.di.build(self.tree_model_class, cache=True)
+
+    def post_save(self, data: dict[str, Any], model: Model, id: int | str) -> None:
+        if not model.is_changing(self.name, data):
+            return
+
+        self.update_tree_table(model, id, model.latest(self.name, data))
+        return
+
+    def force_tree_update(self, model: Model):
+        self.update_tree_table(model, getattr(model, model.id_column_name), getattr(model, self.name))
+
+    def update_tree_table(self, model: Model, child_id: int | str, direct_parent_id: int | str) -> None:
+        tree_model = self.tree_model
+        parent_model = self.parent_model
+        tree_parent_id_column_name = self.tree_parent_id_column_name
+        tree_child_id_column_name = self.tree_child_id_column_name
+        tree_is_parent_column_name = self.tree_is_parent_column_name
+        tree_level_column_name = self.tree_level_column_name
+        max_iterations = self.max_iterations
+
+        # we're going to be lazy and just delete the data for the current record in the tree table,
+        # and then re-insert everything (but we can skip this if creating a new record)
+        if model:
+            for tree in tree_model.where(f"{tree_child_id_column_name}={child_id}"):
+                tree.delete()
+
+        # if we are a root category then we don't have a tree
+        if not direct_parent_id:
+            return
+
+        is_root = False
+        id_column_name = parent_model.id_column_name
+        next_parent = parent_model.find(f"{id_column_name}={direct_parent_id}")
+        tree = []
+        c = 0
+        while not is_root:
+            c += 1
+            if c > max_iterations:
+                self._circular(max_iterations)
+
+            tree.append(getattr(next_parent, next_parent.id_column_name))
+            if not getattr(next_parent, self.name):
+                is_root = True
+            else:
+                next_next_parent_id = getattr(next_parent, self.name)
+                next_parent = model.find(f"{id_column_name}={next_next_parent_id}")
+
+        tree.reverse()
+        for index, parent_id in enumerate(tree):
+            tree_model.create(
+                {
+                    tree_parent_id_column_name: parent_id,
+                    tree_child_id_column_name: child_id,
+                    tree_is_parent_column_name: 1 if parent_id == direct_parent_id else 0,
+                    tree_level_column_name: index,
+                }
+            )
+
+    def _circular(self, max_iterations):
+        raise ValueError(
+            f"Error for column {self.model_class.__name__}.{self.name}: "
+            + f"I've climbed through {max_iterations} parents and haven't found the root yet."
+            + "You may have accidentally created a circular cateogry tree.  If not, and your category tree "
+            + "really _is_ that deep, then adjust the 'max_iterations' configuration for this column accordingly. "
+        )

clearskies/columns/category_tree_ancestors.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from clearskies.columns.category_tree_children import CategoryTreeChildren
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class CategoryTreeAncestors(CategoryTreeChildren):
+    """
+    A column to fetch the ancestors from a category tree column.
+
+    See the CategoryTree column for usage examples.
+
+    The ancestors are all parents of a given category, starting from the root category and working
+    down to the direct parent.  So, given the following category tree:
+
+    ```
+    Root/
+    ├─ Sub/
+    │  ├─ Sub Sub/
+    │  │  ├─ Sub Sub Sub/
+    ├─ Another Child/
+    ```
+
+    The ancesotrs of `Sub Sub Sub` are `["Root", "Sub", "Sub Sub"]` while the ancestors of `Another Child`
+    are `["Root"]`
+    """
+
+    _descriptor_config_map = None
+
+    @overload
+    def __get__(self, instance: None, cls: type) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: Model, cls: type) -> 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()
+
+        return self.relatives(model, find_parents=True, include_all=True)

clearskies/columns/category_tree_children.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+import clearskies.decorators
+from clearskies import configs
+from clearskies.column import Column
+from clearskies.columns import CategoryTree
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class CategoryTreeChildren(Column):
+    """
+    Return the child categories from a category tree column.
+
+    See the CategoryTree column for usage examples.
+
+    The ancestors are all direct descendants of a given category.  So, given the following tree:
+
+    ```
+    Root/
+    ├─ Sub/
+    │  ├─ Sub Sub/
+    │  │  ├─ Sub Sub Sub/
+    ├─ Another Child/
+
+    The children of `Root` are `["Sub", "Another Child"]`.  The children of `Sub Sub` are `["Sub Sub Sub"]`.
+    """
+
+    """ The name of the category tree column we are connected to. """
+    category_tree_column_name = configs.ModelColumn(required=True)
+
+    is_writeable = configs.Boolean(default=False)
+    is_searchable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        category_tree_column_name: str,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class: type, name: str) -> None:
+        """Finalize and check the configuration."""
+        getattr(self.__class__, "category_tree_column_name").set_model_class(model_class)
+        self.model_class = model_class
+        self.name = name
+        self.finalize_and_validate_configuration()
+
+        # double check that we are pointed to a category tree column
+        category_tree_column = getattr(model_class, self.category_tree_column_name)
+        if not isinstance(category_tree_column, CategoryTree):
+            raise ValueError(
+                f"Error with configuration for {model_class.__name__}.{name}, which is a {self.__class__.__name__}.  It needs to point to a category tree column, and it was told to use {model_class.__name__}.{self.category_tree_column_name}, but this is not a CategoryTree column."
+            )
+
+    @overload
+    def __get__(self, instance: None, cls: type[Model]) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: 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()
+
+        return self.relatives(model)
+
+    def __set__(self, model: Model, value: Model) -> None:
+        raise ValueError(
+            f"Attempt to set a value to '{model.__class__.__name__}.{self.name}, but this column is not writeable"
+        )
+
+    def relatives(self, model: Model, include_all: bool = False, find_parents: bool = False) -> Model | list[Model]:
+        id_column_name = model.id_column_name
+        model_id = getattr(model, id_column_name)
+        model_table_name = model.destination_name()
+        category_tree_column = getattr(self.model_class, self.category_tree_column_name)
+        tree_table_name = category_tree_column.tree_model_class.destination_name()
+        parent_id_column_name = category_tree_column.tree_parent_id_column_name
+        child_id_column_name = category_tree_column.tree_child_id_column_name
+        is_parent_column_name = category_tree_column.tree_is_parent_column_name
+        level_column_name = category_tree_column.tree_level_column_name
+
+        if find_parents:
+            join_on = parent_id_column_name
+            search_on = child_id_column_name
+        else:
+            join_on = child_id_column_name
+            search_on = parent_id_column_name
+
+        # if we can join then use a join.
+        if category_tree_column.load_relatives_strategy:
+            relatives = category_tree_column.parent_model.join(
+                f"JOIN {tree_table_name} as tree on tree.{join_on}={model_table_name}.{id_column_name}"
+            )
+            relatives = relatives.where(f"tree.{search_on}={model_id}")
+            if not include_all:
+                relatives = relatives.where(f"tree.{is_parent_column_name}=1")
+            if find_parents:
+                relatives = relatives.sort_by(level_column_name, "asc", "tree")
+            return relatives
+
+        # joins only work for SQL-like backends.  Otherwise, we have to pull out our list of ids
+        branches = category_tree_column.tree_model.where(f"{search_on}={model_id}")
+        if not include_all:
+            branches = branches.where(f"{is_parent_column_name}=1")
+        if find_parents:
+            branches = branches.sort_by(level_column_name, "asc")
+        ids = [str(branch.get(join_on)) for branch in branches]
+
+        # Can we search with a WHERE IN() clause?  If the backend supports it, it is probably faster
+        if category_tree_column.load_relatives_strategy == "where_in":
+            return category_tree_column.parent_model.where(f"{id_column_name} IN ('" + "','".join(ids) + "')")
+
+        # otherwise we have to load each model individually which is SLOW....
+        return [category_tree_column.parent_model.find(f"{id_column_name}={id}") for id in ids]