clear-skies 1.22.30__py3-none-any.whl → 2.0.0__py3-none-any.whl

clearskies/columns/phone.py

@@ -0,0 +1,158 @@
+import re
+from typing import Any, Callable
+
+import clearskies.typing
+from clearskies import configs, parameters_to_properties
+from clearskies.columns.string import String
+
+
+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
+
+    @parameters_to_properties.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: 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 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,91 @@
+from typing import Callable
+
+import clearskies.typing
+from clearskies import configs, parameters_to_properties
+from clearskies.columns.string import String
+
+
+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
+
+    @parameters_to_properties.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: 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 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,98 @@
+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:
+        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 type(value) != str else ""

clearskies/columns/timestamp.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any, Callable, Self, Type, overload
+
+import clearskies.parameters_to_properties
+import clearskies.typing
+from clearskies import configs
+from clearskies.columns.datetime import Datetime
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class Timestamp(Datetime):
+    """
+    A timestamp column.
+
+    The difference between this and the datetime column is that this stores the datetime
+    as a standard unix timestamp - the number of seconds since the unix epoch.
+
+    Also, this **always** assumes the timezone for the timestamp is UTC
+
+    ```python
+    import datetime
+    import clearskies
+
+
+    class Pet(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        last_fed = clearskies.columns.Timestamp()
+
+
+    def demo_timestamp(utcnow: datetime.datetime, pets: Pet) -> dict[str, str | int]:
+        pet = pets.create({
+            "name": "Spot",
+            "last_fed": utcnow,
+        })
+        return {
+            "last_fed": pet.last_fed.isoformat(),
+            "raw_data": pet.get_raw_data()["last_fed"],
+        }
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            demo_timestamp,
+        ),
+        classes=[Pet],
+    )
+    cli()
+    ```
+
+    And when invoked it returns:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {"last_fed": "2025-05-18T19:14:56+00:00", "raw_data": 1747595696},
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+
+    Note that if you pull the column from the model in the usual way (e.g. `pet.last_fed` you get a timestamp,
+    but if you check the raw data straight out of the backend (e.g. `pet.get_raw_data()["last_fed"]`) it's an
+    integer.
+    """
+
+    # whether or not to include the microseconds in the timestamp
+    include_microseconds = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    @clearskies.parameters_to_properties.parameters_to_properties
+    def __init__(
+        self,
+        include_microseconds: bool = False,
+        default: datetime.datetime | None = None,
+        setable: datetime.datetime | Callable[..., datetime.datetime] | 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 from_backend(self, value) -> datetime.datetime | None:
+        mult = 1000 if self.include_microseconds else 1
+        if not value:
+            date = None
+        elif isinstance(value, str):
+            if not value.isdigit():
+                raise ValueError(
+                    f"Invalid data was found in the backend for model {self.model_class.__name__} and column {self.name}: a string value was found that is not a timestamp.  It was '{value}'"
+                )
+            date = datetime.datetime.fromtimestamp(int(value) / mult, datetime.timezone.utc)
+        elif isinstance(value, int) or isinstance(value, float):
+            date = datetime.datetime.fromtimestamp(value / mult, datetime.timezone.utc)
+        else:
+            if not isinstance(value, datetime.datetime):
+                raise ValueError(
+                    f"Invalid data was found in the backend for model {self.model_class.__name__} and column {self.name}: the value was neither an integer, float, string, or datetime object"
+                )
+            date = value
+        return date.replace(tzinfo=datetime.timezone.utc) if date else None
+
+    def to_backend(self, data: dict[str, Any]) -> dict[str, Any]:
+        if not self.name in data or isinstance(data[self.name], int) or data[self.name] == None:
+            return data
+
+        value = data[self.name]
+        if isinstance(value, str):
+            if not value.isdigit():
+                raise ValueError(
+                    f"Invalid data was sent to the backend for model {self.model_class.__name__} and column {self.name}: a string value was found that is not a timestamp. It was '{value}'"
+                )
+            value = int(value)
+        elif isinstance(value, datetime.datetime):
+            value = value.timestamp()
+        else:
+            raise ValueError(
+                f"Invalid data was sent to the backend for model {self.model_class.__name__} and column {self.name}: the value was neither an integer, a string, nor a datetime object"
+            )
+
+        return {**data, self.name: int(value)}
+
+    @overload
+    def __get__(self, instance: None, cls: type) -> Self:
+        pass
+
+    @overload
+    def __get__(self, instance: Model, cls: type) -> datetime.datetime:
+        pass
+
+    def __get__(self, instance, cls):
+        return super().__get__(instance, cls)
+
+    def __set__(self, instance, value: datetime.datetime) -> None:
+        instance._next_data[self.name] = value
+
+    def input_error_for_value(self, value: str, operator: str | None = None) -> str:
+        if not isinstance(value, int):
+            return f"'{self.name}' must be an integer"
+        return ""
+
+    def values_match(self, value_1, value_2):
+        """Compare two values to see if they are the same."""
+        return value_1 == value_2

clearskies/columns/updated.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any
+
+import clearskies.di
+import clearskies.parameters_to_properties
+import clearskies.typing
+from clearskies import configs
+from clearskies.columns.datetime import Datetime
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class Updated(Datetime):
+    """
+    The updated column records the time that a record is created or updated.
+
+    Note that this will always populate the column anytime the model is created or updated.
+    You don't have to provide the timestamp yourself and you should never expose it as
+    a writeable column through an endpoint (in fact, you can't).
+
+    ```python
+    import clearskies
+    import time
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        created = clearskies.columns.Created()
+        updated = clearskies.columns.Updated()
+
+
+    def test_updated(my_models: MyModel) -> MyModel:
+        my_model = my_models.create({"name": "Jane"})
+        updated_column_after_create = my_model.updated
+
+        time.sleep(2)
+
+        my_model.save({"name": "Susan"})
+
+        return {
+            "updated_column_after_create": updated_column_after_create.isoformat(),
+            "updated_column_at_end": my_model.updated.isoformat(),
+            "difference_in_seconds": (my_model.updated - updated_column_after_create).total_seconds(),
+        }
+
+
+    cli = clearskies.contexts.Cli(clearskies.endpoints.Callable(test_updated), classes=[MyModel])
+    cli()
+    ```
+
+    And when invoked:
+
+    ```bash
+    $ ./test.py | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "updated_column_after_create": "2025-05-18T19:28:46+00:00",
+            "updated_column_at_end": "2025-05-18T19:28:48+00:00",
+            "difference_in_seconds": 2.0
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+
+    Note that the `updated` column was set both when the record was first created and when it was updated,
+    so there is a two second difference between them (since we slept for two seconds).
+
+    """
+
+    """
+    Created fields are never writeable because they always set the created time automatically.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    now = clearskies.di.inject.Now()
+
+    @clearskies.parameters_to_properties.parameters_to_properties
+    def __init__(
+        self,
+        in_utc: bool = True,
+        date_format: str = "%Y-%m-%d %H:%M:%S",
+        backend_default: str = "0000-00-00 00:00:00",
+        is_readable: bool = True,
+        is_searchable: bool = True,
+        is_temporary: bool = False,
+        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] = [],
+    ):
+        pass
+
+    def pre_save(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        now = self.now
+        if self.timezone_aware:
+            now = now.astimezone(self.timezone)
+        data = {**data, self.name: now}
+        if self.on_change_pre_save:
+            data = self.execute_actions_with_data(self.on_change_pre_save, model, data)
+        return data

clearskies/columns/uuid.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import clearskies.di
+import clearskies.parameters_to_properties
+import clearskies.typing
+from clearskies import configs
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class Uuid(String):
+    """
+    Populates the column with a UUID upon record creation.
+
+    This column really just has a very specific purpose: ids!
+
+    When used, it will automatically populate the column with a random UUID upon record creation.
+    It is not a writeable column, which means that you cannot expose it for write operations via an endpoint.
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            MyModel,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name"],
+        ),
+    )
+    wsgi()
+    ```
+
+    and when invoked:
+
+    ```bash
+    $ curl http://localhost:8080 -d '{"name": "John Doe"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "d4f23106-b48a-4dc5-9bf6-df61f6ca54f7",
+            "name": "John Doe"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    uuid = clearskies.di.inject.Uuid()
+
+    @clearskies.parameters_to_properties.parameters_to_properties
+    def __init__(
+        self,
+        is_readable: bool = True,
+        is_searchable: bool = True,
+        is_temporary: bool = False,
+        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] = [],
+    ):
+        pass
+
+    def pre_save(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        if model:
+            return data
+        data = {**data, self.name: str(self.uuid.uuid4())}
+        if self.on_change_pre_save:
+            data = self.execute_actions_with_data(self.on_change_pre_save, model, data)
+        return data