clear-skies 2.0.27__py3-none-any.whl

clearskies/columns/many_to_many_models.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Self, overload
+
+from clearskies import configs, decorators
+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.columns.many_to_many_ids_with_data import ManyToManyIdsWithData
+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
+
+    @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, ManyToManyIdsWithData)):
+            raise ValueError(
+                f"Error with configuration for {model_class.__name__}.{name}, which is a {many_to_many_column.__class__.__name__} 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()
+
+        if self.name in instance._transformed_data:
+            return instance._transformed_data[self.name]
+
+        children = self.many_to_many_column.get_related_models(instance)
+
+        instance._transformed_data[self.name] = children
+        return children
+
+    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 isinstance(value, Model) 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 not isinstance(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,132 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any, Self, overload
+
+from clearskies import configs, decorators
+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
+
+    @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: Column = self.many_to_many_column
+        own_column_name_in_pivot = many_to_many_column._config.get("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)

clearskies/columns/phone.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class Phone(String):
+    """
+    A string column that stores a phone number.
+
+    The main difference between this and a plain string column is that this will validate that the string contains
+    a phone number (containing only digits, dashes, spaces, plus sign, and parenthesis) of the appropriate length.
+    When persisting the value to the backend, this column removes all non-digit characters.
+
+    If you also set the usa_only flag to true then it will also validate that it is a valid US number containing
+    9 digits and, optionally, a leading `1`.  Example:
+
+    ```python
+    import clearskies
+
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        phone = clearskies.columns.Phone(usa_only=True)
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            User,
+            writeable_column_names=["name", "phone"],
+            readable_column_names=["id", "name", "phone"],
+        ),
+    )
+    wsgi()
+    ```
+
+    Which you can invoke:
+
+    ```bash
+    $ curl http://localhost:8080 -d '{"name":"John Doe", "phone": "+1 (555) 451-1234"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "e2b4bdad-b70f-4d44-a94c-0e265868b4d2",
+            "name": "John Doe",
+            "phone": "15554511234"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl http://localhost:8080 -d '{"name":"John Doe", "phone": "555 451-1234"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "aea34022-4b75-4eed-ac92-65fa4f4511ae",
+            "name": "John Doe",
+            "phone": "5554511234"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+
+    $ curl http://localhost:8080 -d '{"name":"John Doe", "phone": "555 451-12341"}' | jq
+    {
+        "status": "input_errors",
+        "error": "",
+        "data": [],
+        "pagination": {},
+        "input_errors": {
+            "phone": "Invalid phone number"
+        }
+    }
+
+    $ curl http://localhost:8080 -d '{"name":"John Doe", "phone": "1-2-3-4 asdf"}' | jq
+    {
+        "status": "input_errors",
+        "error": "",
+        "data": [],
+        "pagination": {},
+        "input_errors": {
+            "phone": "Invalid phone number"
+        }
+    }
+    ```
+    """
+
+    """ Whether or not to allow non-USA numbers. """
+    usa_only = configs.Boolean(default=True)
+    _descriptor_config_map = None
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        usa_only: bool = True,
+        default: str | None = None,
+        setable: str | Callable[..., str] | 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
+
+    def to_backend(self, data: dict[str, Any]) -> dict[str, Any]:
+        if not data.get(self.name):
+            return data
+
+        # phone numbers are stored as only digits.
+        return {**data, **{self.name: re.sub(r"\D", "", data[self.name])}}
+
+    def input_error_for_value(self, value: str, operator: str | None = None) -> str:
+        if type(value) != str:
+            return f"Value must be a string for {self.name}"
+
+        # we'll allow spaces, dashes, parenthesis, dashes, and plus signs.
+        # if there is anything else then it's not a valid phone number.
+        # However, we don't do more detailed validation, because I'm too lazy to
+        # figure out what is and is not a valid phone number, especially when
+        # you get to the world of international numbers.
+        if re.search(r"[^\d \-()+]", value):
+            return "Invalid phone number"
+
+        # for some final validation (especially US numbers) work only with the digits.
+        value = re.sub(r"\D", "", value)
+
+        if len(value) > 15:
+            return "Invalid phone number"
+
+        # we can't be too short unless we're doing a fuzzy search
+        if len(value) < 10 and operator and operator.lower() != "like":
+            return "Invalid phone number"
+
+        if self.usa_only:
+            if len(value) > 11:
+                return "Invalid phone number"
+            if value[0] == "1" and len(value) != 11:
+                return "Invalid phone number"
+            if value[0] != "1" and len(value) != 10:
+                return "Invalid phone number"
+
+        return ""

clearskies/columns/select.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class Select(String):
+    """
+    A string column but, when writeable via an endpoint, only specific values are allowed.
+
+    Note: the allowed values are case sensitive.
+
+    ```python
+    import clearskies
+
+
+    class Order(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        total = clearskies.columns.Float()
+        status = clearskies.columns.Select(["Open", "Processing", "Shipped", "Complete"])
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            Order,
+            writeable_column_names=["total", "status"],
+            readable_column_names=["id", "total", "status"],
+        ),
+    )
+    wsgi()
+    ```
+
+    And when invoked:
+
+    ```bash
+    $ curl http://localhost:8080 -d '{"total": 125, "status": "Open"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "22f2c950-6519-4d8e-9084-013455449b07",
+            "total": 125.0,
+            "status": "Open"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl http://localhost:8080 -d '{"total": 125, "status": "huh"}' | jq
+    {
+        "status": "input_errors",
+        "error": "",
+        "data": [],
+        "pagination": {},
+        "input_errors": {
+            "status": "Invalid value for status"
+        }
+    }
+    ```
+    """
+
+    """ The allowed values. """
+    allowed_values = configs.StringList(required=True)
+    _descriptor_config_map = None
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        allowed_values: list[str],
+        default: str | None = None,
+        setable: str | Callable[..., str] | 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
+
+    def input_error_for_value(self, value: str, operator: str | None = None) -> str:
+        return f"Invalid value for {self.name}" if value not in self.allowed_values else ""

clearskies/columns/string.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from clearskies.column import Column
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class String(Column):
+    """
+    A simple string column.
+
+    ```python
+    import clearskies
+
+
+    class Pet(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            Pet,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name"],
+        ),
+    )
+    wsgi()
+    ```
+
+    And when invoked:
+
+    ```bash
+    $ curl http://localhost:8080 -d '{"name": "Spot"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "e5b8417f-91bc-4fe5-9b64-04f571a7b10a",
+            "name": "Spot"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    $ curl http://localhost:8080 -d '{"name": 10}' | jq
+    {
+        "status": "input_errors",
+        "error": "",
+        "data": [],
+        "pagination": {},
+        "input_errors": {
+            "name": "value should be a string"
+        }
+    }
+
+    ```
+    """
+
+    _allowed_search_operators = ["<=>", "!=", "<=", ">=", ">", "<", "=", "in", "is not null", "is null", "like"]
+    _descriptor_config_map = None
+
+    @overload
+    def __get__(self, instance: None, cls: type[Model]) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: Model, cls: type[Model]) -> str:
+        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()
+
+        if self.name not in instance._data:
+            return None  # type: ignore
+
+        if self.name not in instance._transformed_data:
+            instance._transformed_data[self.name] = self.from_backend(instance._data[self.name])
+
+        return instance._transformed_data[self.name]
+
+    def __set__(self, instance: Model, value: str) -> 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 "value should be a string" if not isinstance(value, str) else ""