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

clearskies/columns/uuid.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import clearskies.decorators
+import clearskies.di
+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.decorators.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

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,162 @@
+"""
+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()
+```
+
+"""
+
+import inspect
+
+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 .endpoint import Endpoint
+from .endpoint_list import EndpointList
+from .float import Float
+from .float_or_callable import FloatOrCallable
+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",
+    "Endpoint",
+    "EndpointList",
+    "Float",
+    "FloatOrCallable",
+    "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,13 @@
+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)

clearskies/configs/any_dict.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from clearskies.configs import config
+
+
+class AnyDict(config.Config):
+    def __set__(self, instance, value: dict[str, Any]):
+        if not isinstance(value, dict):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a dictionary."
+            )
+        for key in value.keys():
+            if not isinstance(key, str):
+                error_prefix = self._error_prefix(instance)
+                raise TypeError(f"{error_prefix} attempt to set a dictionary with a non-string key.")
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> dict[str, Any]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/any_dict_or_callable.py

@@ -0,0 +1,23 @@
+from typing import Any, Callable
+
+from clearskies.configs import config
+
+
+class AnyDictOrCallable(config.Config):
+    def __set__(self, instance, value: dict[str, Any] | Callable[..., dict[str, Any]]):
+        if not isinstance(value, dict) and not callable(value):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a dictionary or a callable."
+            )
+        if isinstance(value, dict):
+            for key, val in value.items():
+                if not isinstance(key, str):
+                    error_prefix = self._error_prefix(instance)
+                    raise TypeError(f"{error_prefix} attempt to set a dictionary with a non-string key.")
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> dict[str, Any] | Callable[..., dict[str, Any]]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/authentication.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies.authentication import Authentication as AuthenticationType
+
+
+class Authentication(config.Config):
+    def __set__(self, instance, value: AuthenticationType):
+        if not hasattr(value, "authenticate"):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to parameter that requires an instance of clearskies.authentication.Authentication."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> AuthenticationType:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/authorization.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies.authentication import Authorization as AuthorizationType
+
+
+class Authorization(config.Config):
+    def __set__(self, instance, value: AuthorizationType):
+        if not hasattr(value, "gate"):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to parameter that requires an instance of clearskies.authentication.Authorization."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> AuthorizationType:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/boolean.py

@@ -0,0 +1,16 @@
+from clearskies.configs import config
+
+
+class Boolean(config.Config):
+    def __set__(self, instance, value: bool):
+        if not isinstance(value, bool):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a boolean."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> bool:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/boolean_or_callable.py

@@ -0,0 +1,18 @@
+from typing import Callable
+
+from clearskies.configs import config
+
+
+class BooleanOrCallable(config.Config):
+    def __set__(self, instance, value: bool | Callable[..., bool]):
+        if not isinstance(value, bool) and not callable(value):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a boolean or a callable."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> bool | Callable[..., bool]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/callable_config.py

@@ -0,0 +1,18 @@
+from typing import Callable as CallableType
+
+from clearskies.configs import config
+
+
+class Callable(config.Config):
+    def __set__(self, instance, value: CallableType):
+        if not callable(value):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a Callable."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> CallableType | None:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/columns.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies.column import Column
+
+
+class Columns(config.Config):
+    """This is for a configuration that should be a dictionary of columns with the key being the column name."""
+
+    def __set__(self, instance, value: dict[str, Column]):
+        if value is None:
+            return
+
+        if not isinstance(value, dict):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a dictionary with columns"
+            )
+        for index, item in enumerate(value.values()):
+            if not hasattr(item, "on_change_pre_save"):
+                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}.  A column was expected."
+                )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> dict[str, Column]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/conditions.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class Conditions(config.Config):
+    def __set__(self, instance, value: typing.condition | list[typing.condition]):
+        if not isinstance(value, list):
+            value = [value]
+
+        for index, item in enumerate(value):
+            if callable(item) or isinstance(item, str) or hasattr(item, "_raw_condition"):
+                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 string, condition, callable is required"  # type: ignore
+            )
+
+        instance._set_config(self, [*value])
+
+    def __get__(self, instance, parent) -> list[typing.condition]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/config.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+
+class Config:
+    def __init__(self, required: bool = False, default: Any = None):
+        self.required = required
+        self.default = default
+
+    def _error_prefix(self, instance) -> str:
+        name = instance._descriptor_to_name(self)
+        class_name = instance.__class__.__name__
+        return f"Error with '{class_name}.{name}':"
+
+    def finalize_and_validate_configuration(self, instance):
+        if self.default:
+            try:
+                instance._get_config(self)
+            except KeyError:
+                instance._set_config(self.default)
+
+        if self.required and instance._get_config(self) is None:
+            name = instance._descriptor_to_name(self)
+            prefix = self._error_prefix(instance)
+            raise ValueError("{prefix} {name} is a required configuration setting, but no value was set")

clearskies/configs/datetime.py

@@ -0,0 +1,18 @@
+import datetime
+
+from clearskies.configs import config
+
+
+class Datetime(config.Config):
+    def __set__(self, instance, value: datetime.datetime):
+        if not isinstance(value, datetime.datetime):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a datetime object."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> datetime.datetime:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)