clear-skies 1.22.10__py3-none-any.whl → 2.0.23__py3-none-any.whl

clearskies/columns/timestamp.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any, Callable, Self, overload
+
+from clearskies import configs, decorators
+from clearskies.columns.datetime import Datetime
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+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
+
+    @decorators.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: 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 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, 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:
+        # 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:
+        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,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from clearskies import configs, decorators
+from clearskies.columns.datetime import Datetime
+from clearskies.di import inject
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+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 = inject.Now()
+
+    @decorators.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: typing.action | list[typing.action] = [],
+        on_change_post_save: typing.action | list[typing.action] = [],
+        on_change_save_finished: typing.action | list[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,83 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from clearskies import configs, decorators, di
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+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 = di.inject.Uuid()
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        is_readable: bool = True,
+        is_searchable: bool = True,
+        is_temporary: bool = False,
+        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] = [],
+    ):
+        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

clearskies/configs/README.md

@@ -0,0 +1,105 @@
+# About
+
+There are all sorts of things in clearskies that need to be configured - handlers, columns, models, etc...  `configurable.Configurable` works together with the config classes to make this happen.  The idea is that something that needs to be configured extends `Configurable` and then declares configs as properties.  A simple example:
+
+```python
+class ConfigurableThing(configurable.Configurable):
+    my_name = config.String(required=True)
+    is_required = config.Boolean(default=False)
+    some_option = config.Select(allowed_values=["option 1", "option 2", "option 3"])
+```
+
+We've declared three configuration options for our `ConfigurableThing` class:
+
+ 1. `my_name` which is a string and must be set
+ 2. `is_required` which is a boolean and defaults to `False`
+ 3. `some_option` which is a string and must be one of `[None, "option 1", "option 2", "option 3"]`
+
+However, our example above is missing one important thing: actually setting these values.  They act like standard descriptors, so with just the above code you could:
+
+```python
+configruable_thing = ConfigurableThing()
+configruable_thing.my_name = "Jane Doe"
+configruable_thing.is_required = True
+configruable_thing.some_option = "option 2"
+```
+
+Typically though you need a well defined way to set these values **AND** the class must call `super().finalize_and_validate_configuration()` once the configuration is set.  This is because many of the validations are only possible after all the configs are set, so the configurable class treats the process of setting the configuration as a one-time, monolithic process: you set the configs, validate everything, and then use the config.  It's *NOT* the goal to continually change the configuration for an object after creation.  The simplest way to do this would be in the constructor:
+
+```python
+class ConfigurableThing(configurable.Configurable):
+    my_name = config.String(required=True)
+    is_required = config.Boolean(default=False)
+    some_option = config.Select(allowed_values=["option 1", "option 2", "option 3"])
+
+    def __init__(self,
+        my_name: str,
+        is_required: bool=False,
+        some_option: str=None,
+    ):
+        self.my_name = my_name
+        self.is_required = is_required
+        self.some_option = some_option
+
+        super().finalize_and_validate_configuration()
+```
+
+However, this doesn't always work because your class may be constructed via the dependency injection system.  In this case, the constructor must be reserved for injecting the necessary dependencies.  In addition, the object won't be constructed directly via code, so it's not possible to specify the configuration options there.  In this case, config values can be shifted to the `configure` method and you can use a binding config:
+
+```python
+class ConfigurableThing(configurable.Configurable):
+    my_name = config.String(required=True)
+    is_required = config.Boolean(default=False)
+    some_option = config.Select(allowed_values=["option 1", "option 2", "option 3"])
+
+    def __init__(self, some_dependency, other_dependency):
+        self.some_dependency = some_dependency
+        self.other_dependency = other_dependency
+
+    def configure(self,
+        my_name: str,
+        is_required: bool=False,
+        some_option: str=None,
+    ):
+        self.my_name = my_name
+        self.is_required = is_required
+        self.some_option = some_option
+
+        super().finalize_and_validate_configuration()
+
+context = clearskies.contexts.cli(
+    SomeApplication,
+    bindings={
+        "configurable_thing": clearskies.bindings.Binding(ConfigurableThing, my_name="hey", is_required=Flase, some_option="option 2"),
+    }
+)
+```
+
+Note that we've lost our strong typing when creating the binding, but that can be fixed by extending the binding config:
+
+```python
+class ConfigurableThing:
+    """ See above """
+
+class ConfigurableThingBinding(clearskies.bindings.Binding):
+    def __init__(
+        self,
+        my_name: str,
+        is_required: bool=False,
+        some_option: str=None,
+    ):
+        self.object_class = ConfigurableThing
+        self.args = [my_name]
+        self.kwargs = {"is_required": is_required, "some_option": some_option}
+
+context = clearskies.contexts.cli(
+    SomeApplication,
+    bindings={
+        "configurable_thing": ConfigurableThingBinding("hey", some_option="option 3")
+    }
+)
+```
+
+The primary example of classes that implement this pattern are the column config classes (`clearskies.columns.*`, but excluding `clearskies.columns.implementors`).  In this case the config and implementation are completely separated, so the configuration is set in the constructor instead of a separate `configure` method.
+
+Validators, actions, and handlers also use the above config pattern, but those use the `Binding` pattern and so make use of a `configure` method.

clearskies/configs/__init__.py

@@ -0,0 +1,170 @@
+"""
+This module helps classes declare their configuration parameters via properties.
+
+To use it, the class needs to include the clearskies.configs.Confirgurable in its parent chain and
+then create properties as needed using the various classes in the clearskies.configs module.  Each
+class represents a specific "kind" of configuration, has typing declared to help while writing code,
+and runtime checks to verify configs while the application is (preferably) booting.
+
+Each config accepts a `required` and `default` kwarg to assist with validation/construction of
+the configuration
+
+Data is stored in the `_config` property on the instance.
+
+Usage:
+
+```python
+from clearskies import configs
+
+
+class MyConfigurableClass(configs.Configurable):
+    name = configs.String()
+    age = configs.Integer(required=True)
+    property_with_default = configs.String(default="some value")
+
+    def __init__(self, name, age, optional=None):
+        self.name = name
+        self.age = age
+
+        # always call this after saving the confiuration values to the properties.
+        # It will fill in default values for any properties that have a default and
+        # are none, and it will raise a ValueError if there is a required property
+        # that does not have a value.
+        self.finalize_and_validate_configuration()
+
+
+configured_thingie = MyConfigurableClass("Bob", 18)
+print(configured_thingie.age)  # prints: 18
+print(configured_thingie.property_with_default)  # prints: some value
+
+invalid_thingie = MyConfigurableClass(18, 20)  # raises a TypeError
+
+also_invalid = MyConfigurableClass("", 18)  # raises a ValueError
+```
+
+Finally, parameters_to_properties is a decorator that will take any parameters passed into the
+decorated function and assign them as instance properties.  You can use this to skip some code,
+especially if you have a lot of configuration parameters.  In the above example, you could simplify
+it as:
+
+```python
+from clearskies import configs
+
+
+class MyConfigurableClass(configs.Configurable):
+    name = configs.String()
+    age = configs.Integer(required=True)
+    property_with_default = configs.String(default="some value")
+
+    @clearskies.decorators()
+    def __init__(self, name: str, age: int, optional: string = None):
+        self.finalize_and_validate_configuration()
+```
+
+"""
+
+from .actions import Actions
+from .any import Any
+from .any_dict import AnyDict
+from .any_dict_or_callable import AnyDictOrCallable
+from .authentication import Authentication
+from .authorization import Authorization
+from .boolean import Boolean
+from .boolean_or_callable import BooleanOrCallable
+from .callable_config import Callable
+from .columns import Columns
+from .conditions import Conditions
+from .config import Config
+from .datetime import Datetime
+from .datetime_or_callable import DatetimeOrCallable
+from .email import Email
+from .email_list import EmailList
+from .email_list_or_callable import EmailListOrCallable
+from .email_or_email_list_or_callable import EmailOrEmailListOrCallable
+from .endpoint import Endpoint
+from .endpoint_list import EndpointList
+from .float import Float
+from .float_or_callable import FloatOrCallable
+from .headers import Headers
+from .integer import Integer
+from .integer_or_callable import IntegerOrCallable
+from .joins import Joins
+from .list_any_dict import ListAnyDict
+from .list_any_dict_or_callable import ListAnyDictOrCallable
+from .model_class import ModelClass
+from .model_column import ModelColumn
+from .model_columns import ModelColumns
+from .model_destination_name import ModelDestinationName
+from .model_to_id_column import ModelToIdColumn
+from .readable_model_column import ReadableModelColumn
+from .readable_model_columns import ReadableModelColumns
+from .schema import Schema
+from .searchable_model_columns import SearchableModelColumns
+from .security_headers import SecurityHeaders
+from .select import Select
+from .select_list import SelectList
+from .string import String
+from .string_dict import StringDict
+from .string_list import StringList
+from .string_list_or_callable import StringListOrCallable
+from .string_or_callable import StringOrCallable
+from .timedelta import Timedelta
+from .timezone import Timezone
+from .url import Url
+from .validators import Validators
+from .writeable_model_column import WriteableModelColumn
+from .writeable_model_columns import WriteableModelColumns
+
+__all__ = [
+    "Actions",
+    "Any",
+    "AnyDict",
+    "AnyDictOrCallable",
+    "Authentication",
+    "Authorization",
+    "Boolean",
+    "BooleanOrCallable",
+    "Callable",
+    "Columns",
+    "Conditions",
+    "Config",
+    "Datetime",
+    "DatetimeOrCallable",
+    "Email",
+    "EmailList",
+    "EmailListOrCallable",
+    "EmailOrEmailListOrCallable",
+    "Endpoint",
+    "EndpointList",
+    "Float",
+    "FloatOrCallable",
+    "Headers",
+    "Joins",
+    "Integer",
+    "IntegerOrCallable",
+    "ListAnyDict",
+    "ListAnyDictOrCallable",
+    "ModelClass",
+    "ModelColumn",
+    "ModelColumns",
+    "ModelToIdColumn",
+    "ModelDestinationName",
+    "ReadableModelColumn",
+    "ReadableModelColumns",
+    "Schema",
+    "SearchableModelColumns",
+    "SecurityHeaders",
+    "Select",
+    "SelectList",
+    "String",
+    "StringDict",
+    "StringList",
+    "StringListOrCallable",
+    "StringOrCallable",
+    "Timedelta",
+    "Timezone",
+    "Url",
+    "Validators",
+    "WriteableModelColumn",
+    "WriteableModelColumns",
+]

clearskies/configs/actions.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies import action
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class Actions(config.Config):
+    """
+    Action config.
+
+    A config that accepts various things that are accepted as actions in model lifecycle hooks:
+
+     1. A callable (which should accept `model` as a parameter)
+     2. An instance of clearskies.actions.Action
+     3. A list containing any combination of the above
+
+    Incoming values are normalized to a list so that a list always comes out even if a non-list is provided.
+    """
+
+    def __set__(self, instance, value: typing.action | list[typing.action]):
+        if not isinstance(value, list):
+            value = [value]
+
+        for index, item in enumerate(value):
+            if callable(item) or isinstance(item, action.Action):
+                continue
+
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{item.__class__.__name__}' for item #{index + 1} when a callable or Action is required"
+            )
+
+        instance._set_config(self, [*value])
+
+    def __get__(self, instance, parent) -> list[typing.action]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/any.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any as AnyType
+
+from clearskies.configs import config
+
+
+class Any(config.Config):
+    def __set__(self, instance, value: AnyType):
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> AnyType:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)