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

clearskies/columns/many_to_many_ids_with_data.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Self, overload
+
+import clearskies.decorators
+import clearskies.typing
+from clearskies import configs
+from clearskies.columns.many_to_many_ids import ManyToManyIds
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class ManyToManyIdsWithData(ManyToManyIds):
+    """
+    A column to represent a many-to-many relationship with information stored in the relationship itself.
+
+    This is an extention of the many-to-many column, but with one important addition: data about the
+    relationship is stored in the pivot table.  This creates some differences, which are best
+    explained by example:
+
+    ```python
+    import clearskies
+
+
+    class ThingyWidgets(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        # these could also be belongs to relationships, but the pivot model
+        # is rarely used directly, so I'm being lazy to avoid having to use
+        # model references.
+        thingy_id = clearskies.columns.String()
+        widget_id = clearskies.columns.String()
+        name = clearskies.columns.String()
+        kind = clearskies.columns.String()
+
+
+    class Thingy(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+
+    class Widget(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        thingy_ids = clearskies.columns.ManyToManyIdsWithData(
+            related_model_class=Thingy,
+            pivot_model_class=ThingyWidgets,
+            readable_pivot_column_names=["id", "thingy_id", "widget_id", "name", "kind"],
+        )
+        thingies = clearskies.columns.ManyToManyModels("thingy_ids")
+        thingy_widgets = clearskies.columns.ManyToManyPivots("thingy_ids")
+
+
+    def my_application(widgets: Widget, thingies: Thingy):
+        thing_1 = thingies.create({"name": "Thing 1"})
+        thing_2 = thingies.create({"name": "Thing 2"})
+        thing_3 = thingies.create({"name": "Thing 3"})
+        widget = widgets.create({
+            "name": "Widget 1",
+            "thingy_ids": [
+                {"thingy_id": thing_1.id, "name": "Widget Thing 1", "kind": "Special"},
+                {"thingy_id": thing_2.id, "name": "Widget Thing 2", "kind": "Also Special"},
+            ],
+        })
+
+        return widget
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            my_application,
+            model_class=Widget,
+            return_records=True,
+            readable_column_names=["id", "name", "thingy_widgets"],
+        ),
+        classes=[Widget, Thingy, ThingyWidgets],
+    )
+
+    if __name__ == "__main__":
+        cli()
+    ```
+
+    As with setting ids in the ManyToManyIds class, any items left out will result in the relationship
+    (including all its related data) being removed.  An important difference with the ManyToManyWithData
+    column is the way you specify which record is being connected.  This is easy for the ManyToManyIds column
+    because all you provide is the id from the related model.  When working with the ManyToManyWithData
+    column, you provide a dictionary for each relationship (so you can provide the data that goes in the
+    pivot model).  To let it know what record is being connected, you therefore explicitly provide
+    the id from the related model in a dictionary key with the name of the related model id column in
+    the pivot (e.g. `{"thingy_id": id}` in the first example.  However, if there are unique columns in the
+    related model, you can provide those instead.  If you execute the above example you'll get:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "c4be91a8-85a1-4e29-994a-327f59e26ec7",
+            "name": "Widget 1",
+            "thingy_widgets": [
+                {
+                    "id": "3a8f6f14-9657-49d8-8844-0db3452525fe",
+                    "thingy_id": "db292ebc-7b2b-4306-aced-8e6d073ec264",
+                    "widget_id": "c4be91a8-85a1-4e29-994a-327f59e26ec7",
+                    "name": "Widget Thing 1",
+                    "kind": "Special",
+                },
+                {
+                    "id": "480a0192-70d9-4363-a669-4a59f0b56730",
+                    "thingy_id": "d469dbe9-556e-46f3-bc48-03f8cb8d8e44",
+                    "widget_id": "c4be91a8-85a1-4e29-994a-327f59e26ec7",
+                    "name": "Widget Thing 2",
+                    "kind": "Also Special",
+                },
+            ],
+        },
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+    """
+
+    """ The list of columns in the pivot model that can be set when saving data from an endpoint. """
+    setable_column_names = configs.WriteableModelColumns("pivot_model_class")
+
+    """ The list of columns in the pivot model that will be included when returning records from an endpoint. """
+    readable_pivot_column_names = configs.ReadableModelColumns("pivot_model_class")
+
+    """
+    Complicated, but probably should be false.
+
+    Sometimes you have to provide data from the related model class in your save data so that
+    clearskies can find the right record.  Normally, this lookup column is not persisted to the
+    pivot table, because it is assumed to only exist in the related table.  In some cases though,
+    you may want it in both, in which case you can set this to true.
+    """
+    persist_unique_lookup_column_to_pivot_table = configs.Boolean(default=False)
+
+    default = configs.ListAnyDict(default=None)  #  type: ignore
+    setable = configs.ListAnyDictOrCallable(default=None)  #  type: ignore
+    _descriptor_config_map = None
+
+    @clearskies.decorators.parameters_to_properties
+    def __init__(
+        self,
+        related_model_class,
+        pivot_model_class,
+        own_column_name_in_pivot: str = "",
+        related_column_name_in_pivot: str = "",
+        readable_related_columns: list[str] = [],
+        readable_pivot_column_names: list[str] = [],
+        setable_column_names: list[str] = [],
+        persist_unique_lookup_column_to_pivot_table: bool = False,
+        default: list[dict[str, Any]] = [],
+        setable: list[dict[str, Any]] | Callable[..., list[dict[str, Any]]] = [],
+        is_readable: bool = True,
+        is_writeable: 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
+
+    @overload
+    def __get__(self, instance: None, cls: type[Model]) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: Model, cls: type[Model]) -> list[Any]:
+        pass
+
+    def __get__(self, instance, cls):
+        return super().__get__(instance, cls)
+
+    def __set__(self, instance, value: list[dict[str, Any]]) -> None:  # type: ignore
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            instance.get_columns()
+
+        instance._next_data[self.name] = value
+
+    def post_save(self, data, model, id):
+        # if our incoming data is not in the data array or is None, then nothing has been set and we do not want
+        # to make any changes
+        if self.name not in data or data[self.name] is None:
+            return data
+
+        # figure out what ids need to be created or deleted from the pivot table.
+        if not model:
+            old_ids = set()
+        else:
+            old_ids = set(self.__get__(model, model.__class__))
+
+        # this is trickier for many-to-many-with-data compared to many-to-many.  We're generally
+        # expecting data[self.name] to be a list of dictionaries.  For each entry, we need to find
+        # the corresponding entry in the pivot table to decide if we need to delete, create, or update.
+        # However, since we have a dictionary there are a variety of ways that we can connect to
+        # an entry in the related table - either related id or any unique column from the related
+        # table.  Technically we might also specify a pivot id, but we're generally trying to be
+        # transparent to those, so let's ignore that one.
+        related_column_name_in_pivot = self.related_column_name_in_pivot
+        own_column_name_in_pivot = self.own_column_name_in_pivot
+        unique_related_columns = {
+            column.name: column.name for column in self.related_columns.values() if column.is_unique
+        }
+        related_model = self.related_model
+        pivot_model = self.pivot_model
+        # minor cheating
+        if hasattr(pivot_model.backend, "create_table"):
+            pivot_model.backend.create_table(pivot_model)
+        new_ids = set()
+        for pivot_record in data[self.name]:
+            # first we need to identify which related column this belongs to.
+            related_column_id = None
+            # if they provide the related column id in the pivot data then we're good
+            if related_column_name_in_pivot in pivot_record:
+                related_column_id = pivot_record[related_column_name_in_pivot]
+            elif len(unique_related_columns):
+                for pivot_column, pivot_value in pivot_record.items():
+                    if pivot_column not in unique_related_columns:
+                        continue
+                    related = related_model.find(f"{pivot_column}={pivot_value}")
+                    related_column_id = getattr(related, related.id_column_name)
+                    if related_column_id:
+                        # remove this column from the data - it was used to lookup the right
+                        # record, but mostly won't exist in the model, unless we've been instructed
+                        # to keep it
+                        if not self._config.get("persist_unique_lookup_column_to_pivot_table"):  # type: ignore
+                            del pivot_record[pivot_column]
+                        break
+            if not related_column_id:
+                column_list = "'" + "', '".join(list(unique_related_columns.keys())) + "'"
+                raise ValueError(
+                    f"Missing data for {self.name}: Unable to match related record for a record in the many-to-many relationship: you must provide either '{related_column_name_in_pivot}' with the id column for the related table, or a value from one of the unique columns: {column_list}"
+                )
+            pivot = (
+                pivot_model.where(f"{related_column_name_in_pivot}={related_column_id}")
+                .where(f"{own_column_name_in_pivot}={id}")
+                .first()
+            )
+            new_ids.add(related_column_id)
+            # this will either update or create accordingly
+            pivot.save(
+                {
+                    **pivot_record,
+                    related_column_name_in_pivot: related_column_id,
+                    own_column_name_in_pivot: id,
+                }
+            )
+
+        # the above took care of isnerting and updating active records.  Now we need to delete
+        # records that are no longer needed.
+        to_delete = old_ids - new_ids
+        if to_delete:
+            for model_to_delete in pivot_model.where(
+                f"{related_column_name_in_pivot} IN (" + ",".join(map(str, to_delete)) + ")"
+            ):
+                model_to_delete.delete()
+
+        return data

clearskies/columns/many_to_many_models.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Callable, Self, overload
+
+import clearskies.decorators
+import clearskies.typing
+from clearskies import configs
+from clearskies.autodoc.schema import Array as AutoDocArray
+from clearskies.autodoc.schema import Object as AutoDocObject
+from clearskies.column import Column
+from clearskies.columns.many_to_many_ids import ManyToManyIds
+from clearskies.functional import string
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class ManyToManyModels(Column):
+    """
+    A companion for the ManyToManyIds column that returns the matching models instead of the ids.
+
+    See the example in the ManyToManyIds column to understand how to use it.
+    """
+
+    """ The name of the many-to-many column we are attached to. """
+    many_to_many_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,
+        many_to_many_column_name,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class: type, name: str) -> None:
+        """Finalize and check the configuration."""
+        getattr(self.__class__, "many_to_many_column_name").set_model_class(model_class)
+        self.model_class = model_class
+        self.name = name
+        self.finalize_and_validate_configuration()
+
+        # finally, make sure we're really pointed at a many-to-many column
+        many_to_many_column = getattr(model_class, self.many_to_many_column_name)
+        if not isinstance(many_to_many_column, ManyToManyIds):
+            raise ValueError(
+                f"Error with configuration for {model_class.__name__}.{name}, which is a ManyToManyModels column.  It needs to point to a ManyToManyIds column, and it was told to use {model_class.__name__}.{self.many_to_many_column_name}, but this is not a ManyToManyIds column."
+            )
+
+    @property
+    def pivot_model(self):
+        return self.di.build(self.many_to_many_column.pivot_model_class, cache=True)  # type: ignore
+
+    @property
+    def related_models(self):
+        return self.di.build(self.many_to_many_column.related_model_class, cache=True)  # type: ignore
+
+    @property
+    def related_columns(self):
+        return self.related_models.get_columns()
+
+    @property
+    def many_to_many_column(self) -> ManyToManyIds:
+        return getattr(self.model_class, self.many_to_many_column_name)
+
+    @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, instance, cls):
+        if instance is None:
+            self.model_class = cls
+            return self
+
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            instance.get_columns()
+
+        return self.many_to_many_column.get_related_models(instance)  # type: ignore
+
+    def __set__(self, instance, value: Model | list[Model] | list[dict[str, Any]]) -> None:
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            instance.get_columns()
+
+        # we allow a list of models or a model, but if it's a model it may represent a single record or a query.
+        # if it's a single record then we want to wrap it in a list so we can iterate over it.
+        if hasattr(value, "_data") and value._data:
+            value = []
+        many_to_many_column: ManyToManyIds = self.many_to_many_column  # type: ignore
+        related_model_class = many_to_many_column.related_model_class
+        related_id_column_name = related_model_class.id_column_name
+        record_ids = []
+        for index, record in enumerate(value):
+            if isinstance(record, dict):
+                if not record.get(related_id_column_name):
+                    raise KeyError(
+                        f"A list of dictionaries was set to '{self.model_class.__name__}.{self.name}', in which case each dictionary should contain the key '{related_id_column_name}', which should be the id of an entry for the '{related_model_class.__name__}' model.  However, no such key was found for entry #{index + 1}"
+                    )
+                record_ids.append(record[related_id_column_name])
+                continue
+
+            # if we get here then the entry should be a model for our related model class
+            if not isinstance(record, related_model_class):
+                raise TypeError(
+                    f"Models were sent to '{self.model_class.__name__}.{self.name}', in which case it should be a list of models of type {related_model_class.__name__}.  However, an object of type '{record.__class__.__name__}' was found for entry #{index + 1}"
+                )
+            record_ids.append(getattr(record, related_id_column_name))
+        setattr(instance, self.many_to_many_column_name, record_ids)
+
+    def add_search(self, model: Model, value: str, operator: str = "", relationship_reference: str = "") -> Model:
+        return self.many_to_many_column.add_search(  # type: ignore
+            model, value, operator, relationship_reference=relationship_reference
+        )  # type: ignore
+
+    def to_json(self, model: Model) -> dict[str, Any]:
+        records = []
+        many_to_many_column: ManyToManyIds = self.many_to_many_column  # type: ignore
+        columns = many_to_many_column.related_columns
+        related_id_column_name = many_to_many_column.related_model_class.id_column_name
+        for related in many_to_many_column.get_related_models(model):
+            json = OrderedDict()
+            if related_id_column_name not in many_to_many_column.readable_related_column_names:
+                json[related_id_column_name] = columns[related_id_column_name].to_json(related)
+            for column_name in many_to_many_column.readable_related_column_names:
+                column_data = columns[column_name].to_json(related)
+                if type(column_data) == dict:
+                    json = {**json, **column_data}  # type: ignore
+                else:
+                    json[column_name] = column_data
+            records.append(json)
+        return {self.name: records}
+
+    def documentation(self, name: str | None = None, example: str | None = None, value: str | None = None):
+        many_to_many_column = self.many_to_many_column  # type: ignore
+        columns = many_to_many_column.related_columns
+        related_id_column_name = many_to_many_column.related_model_class.id_column_name
+        related_properties = [columns[related_id_column_name].documentation()]
+
+        for column_name in many_to_many_column.readable_related_column_names:
+            related_docs = columns[column_name].documentation()
+            if type(related_docs) != list:
+                related_docs = [related_docs]
+            related_properties.extend(related_docs)
+
+        related_object = AutoDocObject(
+            string.title_case_to_nice(many_to_many_column.related_model_class.__name__),
+            related_properties,
+        )
+        return AutoDocArray(name if name is not None else self.name, related_object, value=value)

clearskies/columns/many_to_many_pivots.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Callable, Self, overload
+
+import clearskies.decorators
+import clearskies.typing
+from clearskies import configs
+from clearskies.autodoc.schema import Array as AutoDocArray
+from clearskies.autodoc.schema import Object as AutoDocObject
+from clearskies.column import Column
+from clearskies.columns.many_to_many_ids import ManyToManyIds
+from clearskies.functional import string
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class ManyToManyPivots(Column):
+    """
+    A companion for the ManyToManyIds column that returns the matching pivot models instead of the ids.
+
+    See ManyToManyIdsWithData for an example of how to use it (but note that it works just the same for the
+    ManyToManyIds column).
+    """
+
+    """ The name of the many-to-many column we are attached to. """
+    many_to_many_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,
+        many_to_many_column_name,
+    ):
+        pass
+
+    def finalize_configuration(self, model_class: type, name: str) -> None:
+        """Finalize and check the configuration."""
+        getattr(self.__class__, "many_to_many_column_name").set_model_class(model_class)
+        self.model_class = model_class
+        self.name = name
+        self.finalize_and_validate_configuration()
+
+        # finally, make sure we're really pointed at a many-to-many column
+        many_to_many_column = getattr(model_class, self.many_to_many_column_name)
+        if not isinstance(many_to_many_column, ManyToManyIds):
+            raise ValueError(
+                f"Error with configuration for {model_class.__name__}.{name}, which is a ManyToManyModels column.  It needs to point to a ManyToManyIds column, and it was told to use {model_class.__name__}.{self.many_to_many_column_name}, but this is not a ManyToManyIds column."
+            )
+
+    @property
+    def pivot_model(self) -> Model:
+        return self.di.build(self.many_to_many_column.pivot_model_class, cache=True)  # type: ignore
+
+    @property
+    def related_models(self) -> Model:
+        return self.di.build(self.many_to_many_column.related_model_class, cache=True)  # type: ignore
+
+    @property
+    def related_columns(self):
+        return self.related_models.get_columns()
+
+    @property
+    def many_to_many_column(self) -> ManyToManyIds:
+        return getattr(self.model_class, self.many_to_many_column_name)
+
+    @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, instance, cls):
+        if instance is None:
+            self.model_class = cls
+            return self
+
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            instance.get_columns()
+
+        many_to_many_column = self.many_to_many_column  # type: ignore
+        own_column_name_in_pivot = many_to_many_column._config("own_column_name_in_pivot")
+        my_id = getattr(instance, instance.id_column_name)
+        return [model for model in self.pivot_model.where(f"{own_column_name_in_pivot}={my_id}")]
+
+    def __set__(self, instance, value: Model | list[Model] | list[dict[str, Any]]) -> None:
+        raise NotImplementedError("Saving not supported for ManyToManyPivots")
+
+    def add_search(self, model: Model, value: str, operator: str = "", relationship_reference: str = "") -> Model:
+        raise NotImplementedError("Searching not supported for ManyToManyPivots")
+
+    def to_json(self, model: Model) -> dict[str, Any]:
+        records = []
+        many_to_many_column = self.many_to_many_column  # type: ignore
+        columns = many_to_many_column.pivot_columns
+        readable_column_names = many_to_many_column.readable_pivot_column_names
+        pivot_id_column_name = many_to_many_column.pivot_model_class.id_column_name
+        for pivot in many_to_many_column.get_pivot_models(model):
+            json = OrderedDict()
+            if pivot_id_column_name not in readable_column_names:
+                json[pivot_id_column_name] = columns[pivot_id_column_name].to_json(pivot)
+            for column_name in readable_column_names:
+                column_data = columns[column_name].to_json(pivot)
+                if type(column_data) == dict:
+                    json = {**json, **column_data}  # type: ignore
+                else:
+                    json[column_name] = column_data
+            records.append(json)
+        return {self.name: records}
+
+    def documentation(self, name: str | None = None, example: str | None = None, value: str | None = None):
+        many_to_many_column = self.many_to_many_column  # type: ignore
+        columns = many_to_many_column.pivot_columns
+        pivot_id_column_name = many_to_many_column.pivot_model_class.id_column_name
+        pivot_properties = [columns[pivot_id_column_name].documentation()]
+
+        for column_name in many_to_many_column.readable_pivot_column_names:
+            pivot_docs = columns[column_name].documentation()
+            if type(pivot_docs) != list:
+                pivot_docs = [pivot_docs]
+            pivot_properties.extend(pivot_docs)
+
+        pivot_object = AutoDocObject(
+            string.title_case_to_nice(many_to_many_column.pivot_model_class.__name__),
+            pivot_properties,
+        )
+        return AutoDocArray(name if name is not None else self.name, pivot_object, value=value)