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

clearskies/columns/belongs_to_self.py

@@ -1,105 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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

@@ -1,275 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,127 +0,0 @@
-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]