clear-skies 2.0.27__py3-none-any.whl

clearskies/columns/category_tree_descendants.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from clearskies.columns import CategoryTreeChildren
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class CategoryTreeDescendants(CategoryTreeChildren):
+    """
+    Return all descendants from a category tree column.
+
+    See the CategoryTree column for usage examples.
+
+    The descendants are the recursive children of a given category.  So, given the following tree:
+
+    ```
+    Root/
+    ├─ Sub/
+    │  ├─ Sub Sub/
+    │  │  ├─ Sub Sub Sub/
+    ├─ Another Child/
+
+    The descendants of `Root` are `["Sub", "Sub Sub", "Sub Sub Sub", "Another Child"]`.
+    """
+
+    _descriptor_config_map = None
+
+    @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, model, cls):
+        if model is None:
+            self.model_class = cls
+            return self  # type:  ignore
+
+        # this makes sure we're initialized
+        if "name" not in self._config:  # type: ignore
+            model.get_columns()
+
+        return self.relatives(model, include_all=True)

clearskies/columns/created.py

@@ -0,0 +1,92 @@
+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 Created(Datetime):
+    """
+    The created column records the time that a record is created.
+
+    This will always populate the column when the model is first created.  If you attempt to set a value
+    to this column on create then it will be overwritten.
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        created = clearskies.columns.Created()
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            lambda my_models: my_models.create({"name": "An Example"}),
+            model_class=MyModel,
+            readable_column_names=["id", "name", "created"],
+        ),
+        classes=[MyModel],
+    )
+    cli()
+    ```
+
+    And if you execute this you'll see that the `created` column was automatically populated:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "c54d74ac-5282-439e-af4f-23efb9ba96d4",
+            "name": "An Example",
+            "created": "2025-05-09T19:58:43+00:00",
+        },
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+    """
+
+    """
+    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,
+        date_format: str = "%Y-%m-%d %H:%M:%S",
+        in_utc: bool = True,
+        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]:
+        if model:
+            return data
+        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/created_by_authorization_data.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class CreatedByAuthorizationData(String):
+    """
+    This column will automatically take data from the authorization data attached to a request and store it in the model upon creation.
+
+    If authorization data isn't available from the context being executed, then you may end up with an error
+    (depending on the context).  This is a good thing if you are trying to consistely provide audit information,
+    but may be a problem if your model creation needs to happen more flexibly.  Obviously, a pre-requisite for using this
+    class is to have an authentication class attached to your endpoint which populates the authorization data.
+
+    NOTE: columns generally also have the `created_by_source_type` and `created_by_source_key` properties that perform
+    this exact same function.  Why do we have those properties and this column?  This column works well if we have
+    some simple string values that we want to always pull from the authorization data (email, for instance).  The
+    properties work better if you need to pull authorization data but it's not just a string type.  An example might
+    be if you wanted to pull the user id out of the authorziation data to populate a `BelongsToId` column.  You wouldn't
+    use this column because it can't provide all the functionality related to `BelongsToId`, so instead you would
+    use the `BelongsToId` column and set `created_by_source_type` to `authorization_data` and `created_by_source_key` to `user_id`.
+    Example usage:
+
+    ```python
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        organization_id = clearskies.columns.CreatedByAuthorizationData("organization_id")
+
+
+    class MyAuthentication(clearskies.authentication.Authentication):
+        def authenticate(self, input_output) -> bool:
+            # Authenticate the user!
+            #
+            # This is where you would normally authenticate the user and provide any data about them to the
+            # authorization system.  This might mean validating a JWT and then providing the claims as authorization data,
+            # or looking up a session id and providing the session data to the authorization system.  In this case,
+            # we're just going to return a fixed id for our organization.
+            input_output.authorization_data = {
+                "organization_id": "my-super-awesome-organization",
+            }
+            return True
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Create(
+            MyModel,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name", "organization_id"],
+            authentication=MyAuthentication(),
+        ),
+        classes=[MyModel],
+    )
+    cli()
+    ```
+
+    And running this will give you something like:
+
+    ```json
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "49816ea4-0956-461e-abd4-03dbde845ba9",
+            "name": "Bob",
+            "organization_id": "my-super-awesome-organization",
+        },
+        "pagination": {},
+        "input_errors": {},
+    }
+    ```
+    """
+
+    """
+    The key inside the authorization data that should be pulled into the column value when the record is created
+    """
+    authorization_data_key_name = configs.String(required=True)
+
+    """
+    Whether or not to throw an error if the key is not present in the authorization data.
+    """
+    strict = configs.Boolean(default=True)
+
+    """
+    Since this column is always populated automatically, it is never directly writeable.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    _allowed_search_operators = ["=", "in", "is not null", "is null", "like"]
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        authorization_data_key_name: str,
+        strict: bool = True,
+        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] = [],
+    ):
+        self.created_by_source_key = authorization_data_key_name
+        self.created_by_source_type = "authorization_data"

clearskies/columns/created_by_header.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class CreatedByHeader(String):
+    """
+    This column will automatically take data from the header attached to a request and store it in the model upon creation.
+
+    If header data isn't available from the context being executed, then you may end up with an error
+    (depending on the context).  This is a good thing if you are trying to consistely provide audit information,
+    but may be a problem if your model creation needs to happen more flexibly.
+
+    NOTE: columns generally also have the `created_by_source_type` and `created_by_source_key` properties that perform
+    this exact same function.  Why do we have those properties and this column?  This column works well if we have
+    some simple string values that we want to always pull from the header data.  The properties work better if you need to
+    pull header data but it's not just a string type.  An example might be if you wanted to pull the user id out of the
+    header data to populate a `BelongsToId` column.  You wouldn't use this column because it can't provide all the functionality
+    related to `BelongsToId`, so instead you would use the `BelongsToId` column and set `created_by_source_type` to `http_header` and
+    `created_by_source_key` to `user_id`.  Example usage:
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        custom_header = clearskies.columns.CreatedByHeader("my_custom_header")
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            MyModel,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name", "custom_header"],
+        ),
+        classes=[MyModel],
+    )
+    wsgi()
+    ```
+
+    If you invoked this:
+
+    ```bash
+    $ curl 'http://localhost:8080' -d '{"name":"Bob"}' -H 'my_custom_header: some header value' | jq
+
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "10459ee4-a75e-4fd1-9993-2feeea629144",
+            "name": "Bob",
+            "custom_header": "some header value"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    ```
+    """
+
+    """
+    The name of the header that this column should be populated from.
+    """
+    header_name = configs.String(required=True)
+
+    """
+    Whether or not to throw an error if the key is not present in the header data.
+    """
+    strict = configs.Boolean(default=True)
+
+    """
+    Since this column is always populated automatically, it is never directly writeable.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    _allowed_search_operators = ["=", "in", "is not null", "is null", "like"]
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        header_name: str,
+        strict: bool = True,
+        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] = [],
+    ):
+        self.created_by_source_key = header_name
+        self.created_by_source_type = "http_header"

clearskies/columns/created_by_ip.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+class CreatedByIp(String):
+    """
+    Return the ip address of the client when the record is created.
+
+    If the ip address isn't available from the context being executed, then you may end up with an error
+    (depending on the context).  This is a good thing if you are trying to consistely provide audit information,
+    but may be a problem if your model creation needs to happen more flexibly.  Example:
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        ip_address = clearskies.columns.CreatedByIp()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            MyModel,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name", "ip_address"],
+        ),
+        classes=[MyModel],
+    )
+    wsgi()
+    ```
+
+    And if you invoked this:
+
+    ```bash
+    $ curl 'http://localhost:8080' -d '{"name":"Bob"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "62e457fe-1680-4fa1-b4e3-0329f304fedb",
+            "name": "Bob",
+            "ip_address": "127.0.0.1"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+
+    ```
+    """
+
+    """
+    Since this column is always populated automatically, it is never directly writeable.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    _allowed_search_operators = ["=", "in", "is not null", "is null", "like"]
+
+    @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
+        input_output = self.di.build("input_output", cache=True)
+        data = {**data, self.name: input_output.get_client_ip()}
+        if self.on_change_pre_save:
+            data = self.execute_actions_with_data(self.on_change_pre_save, model, data)
+        return data

clearskies/columns/created_by_routing_data.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class CreatedByRoutingData(String):
+    """
+    This column will automatically take data from the route path in the request and store it in the model upon creation.
+
+    If routing data isn't available from the context being executed, then you may end up with an error
+    (depending on the context).  This is a good thing if you are trying to consistely provide audit information,
+    but may be a problem if your model creation needs to happen more flexibly.
+
+    NOTE: columns generally also have the `created_by_source_type` and `created_by_source_key` properties that perform
+    this exact same function.  Why do we have those properties and this column?  This column works well if we have
+    some simple string values that we want to always pull from the route path.  The properties work better if you need to
+    pull route data but it's not just a string type.  An example might be if you wanted to pull the user id out of the
+    route data to populate a `BelongsToId` column.  You wouldn't use this column because it can't provide all the functionality
+    related to `BelongsToId`, so instead you would use the `BelongsToId` column and set `created_by_source_type` to `routing_data` and
+    `created_by_source_key` to `user_id`.  Example usage:
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        organization_id = clearskies.columns.CreatedByRoutingData("organization_id")
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            MyModel,
+            url="/{organization_id}",
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name", "organization_id"],
+        ),
+        classes=[MyModel],
+    )
+    wsgi()
+    ```
+
+    And if you invoked this:
+
+    ```bash
+    $ curl 'http://localhost:8080/my-org-id' -d '{"name":"Bob"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "3643db8c-c9d4-47ee-a747-8922c59d9e7e",
+            "name": "Bob",
+            "organization_id": "my-org-id"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    """
+    The name of the route path to populate the column with.
+    """
+    routing_path_name = configs.String(required=True)
+
+    """
+    Whether or not to throw an error if the key is not present in the header data.
+    """
+    strict = configs.Boolean(default=True)
+
+    """
+    Since this column is always populated automatically, it is never directly writeable.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    _allowed_search_operators = ["=", "in", "is not null", "is null", "like"]
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        routing_path_name: str,
+        strict: bool = True,
+        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] = [],
+    ):
+        self.created_by_source_key = routing_path_name
+        self.created_by_source_type = "routing_data"

clearskies/columns/created_by_user_agent.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from clearskies import configs, decorators
+from clearskies.columns.string import String
+
+if TYPE_CHECKING:
+    from clearskies import Model, typing
+
+
+class CreatedByUserAgent(String):
+    """
+    This column will automatically take the user agent from the client and store it in the model upon creation.
+
+    If the user agent isn't available from the context being executed, then you may end up with an error
+    (depending on the context).  This is a good thing if you are trying to consistely provide audit information,
+    but may be a problem if your model creation needs to happen more flexibly.  Example:
+
+    ```python
+    import clearskies
+
+
+    class MyModel(clearskies.Model):
+        backend = clearskies.backends.MemoryBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+        user_agent = clearskies.columns.CreatedByUserAgent()
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Create(
+            MyModel,
+            writeable_column_names=["name"],
+            readable_column_names=["id", "name", "user_agent"],
+        ),
+        classes=[MyModel],
+    )
+    wsgi()
+    ```
+
+    And if you invoked this:
+
+    ```bash
+    $ curl 'http://localhost:8080' -d '{"name":"Bob"}' | jq
+    {
+        "status": "success",
+        "error": "",
+        "data": {
+            "id": "a66e5fa9-6377-4d3b-9d50-fc7feaed6d1a",
+            "name": "Bob",
+            "user_agent": "curl/8.5.0"
+        },
+        "pagination": {},
+        "input_errors": {}
+    }
+    ```
+    """
+
+    """
+    Since this column is always populated automatically, it is never directly writeable.
+    """
+    is_writeable = configs.Boolean(default=False)
+    _descriptor_config_map = None
+
+    _allowed_search_operators = ["=", "in", "is not null", "is null", "like"]
+
+    @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
+        input_output = self.di.build("input_output", cache=True)
+        data = {**data, self.name: input_output.request_headers.user_agent}
+        if self.on_change_pre_save:
+            data = self.execute_actions_with_data(self.on_change_pre_save, model, data)
+        return data