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

clearskies/di/inject/__init__.py

@@ -0,0 +1,23 @@
+from clearskies.di.inject.by_class import ByClass
+from clearskies.di.inject.by_name import ByName
+from clearskies.di.inject.di import Di
+from clearskies.di.inject.environment import Environment
+from clearskies.di.inject.input_output import InputOutput
+from clearskies.di.inject.now import Now
+from clearskies.di.inject.requests import Requests
+from clearskies.di.inject.secrets import Secrets
+from clearskies.di.inject.utcnow import Utcnow
+from clearskies.di.inject.uuid import Uuid
+
+__all__ = [
+    "ByClass",
+    "ByName",
+    "Di",
+    "Environment",
+    "InputOutput",
+    "Now",
+    "Requests",
+    "Secrets",
+    "Utcnow",
+    "Uuid",
+]

clearskies/di/inject/akeyless_sdk.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from types import ModuleType
+
+from clearskies.di.injectable import Injectable
+
+
+class AkeylessSDK(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> ModuleType:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("akeyless_sdk", cache=self.cache)

clearskies/di/inject/by_class.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.di.injectable import Injectable
+
+
+class ByClass(Injectable):
+    def __init__(self, cls: type, cache: bool = True):
+        if not isinstance(cls, type):
+            raise TypeError(
+                f"I expected a class for the first argument to clearskies.di.inject.ByClass, but I received an object of type '{cls.__class__.__name__}' instead."
+            )
+        self.cls = cls
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> Any:
+        if instance is None:
+            return self  # type: ignore
+
+        self.initiated_guard(instance)
+        if self.cls in self._di._class_overrides_by_class:
+            return self._di.build_class(self._di._class_overrides_by_class[self.cls], cache=self.cache)
+        return self._di.build_class(self.cls, cache=self.cache)

clearskies/di/inject/by_name.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.di.injectable import Injectable
+
+
+class ByName(Injectable):
+    def __init__(self, name: str, cache: bool = True):
+        if not isinstance(name, str):
+            raise TypeError(
+                f"I expected a string for the first argument to clearskies.di.inject.ByName, but I received an object of type '{name.__class__.__name__}' instead."
+            )
+        self.name = name
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> Any:
+        if instance is None:
+            return self  # type: ignore
+
+        self.initiated_guard(instance)
+        return self._di.build_from_name(self.name, cache=self.cache)

clearskies/di/inject/di.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.di.injectable import Injectable
+
+
+class Di(Injectable):
+    def __init__(self):
+        pass
+
+    def __get__(self, instance, parent) -> Any:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di

clearskies/di/inject/environment.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from clearskies.di.injectable import Injectable
+from clearskies.environment import Environment as EnvironmentDependency
+
+
+class Environment(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> EnvironmentDependency:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("environment", cache=self.cache)

clearskies/di/inject/input_output.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.di.injectable import Injectable
+
+if TYPE_CHECKING:
+    from clearskies.input_outputs.input_output import InputOutput as InputOuputDependency
+
+
+class InputOutput(Injectable):
+    def __init__(self):
+        pass
+
+    def __get__(self, instance, parent) -> InputOuputDependency:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("input_output", cache=True)

clearskies/di/inject/now.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import datetime
+
+from clearskies.di.injectable import Injectable
+
+
+class Now(Injectable):
+    def __init__(self, cache: bool = False):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> datetime.datetime:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("now", cache=self.cache)

clearskies/di/inject/requests.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import requests
+
+from clearskies.di.injectable import Injectable
+
+
+class Requests(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> requests.Session:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("requests", cache=self.cache)

clearskies/di/inject/secrets.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from clearskies.di.injectable import Injectable
+from clearskies.secrets.secrets import Secrets as SecretsHelper
+
+
+class Secrets(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> SecretsHelper:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("secrets", cache=self.cache)

clearskies/di/inject/utcnow.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import datetime
+
+from clearskies.di.injectable import Injectable
+
+
+class Utcnow(Injectable):
+    def __init__(self, cache: bool = False):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> datetime.datetime:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("utcnow", cache=self.cache)

clearskies/di/inject/uuid.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import types
+
+from clearskies.di.injectable import Injectable
+
+
+class Uuid(Injectable):
+    def __init__(self, cache: bool = True):
+        self.cache = cache
+
+    def __get__(self, instance, parent) -> types.ModuleType:
+        if instance is None:
+            return self  # type: ignore
+        self.initiated_guard(instance)
+        return self._di.build_from_name("uuid", cache=self.cache)  # type: ignore

clearskies/di/injectable.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Injectable(ABC):
+    _di: Any = None
+
+    def initiated_guard(self, instance):
+        if self._di:
+            return
+
+        reference = instance.__class__.__name__ + "."
+        my_id = id(self)
+        cls = instance.__class__
+        for attribute_name in dir(instance):
+            if id(getattr(cls, attribute_name)) != my_id:
+                continue
+            reference += attribute_name
+        raise ValueError(
+            f"There was an attempt to get a value out of '{reference}' but the injectable hasn't been properly "
+            + "initialized.  This usually means that objects are being created outside of the normal Di system. "
+            + "This most often happens when working with classes that are both configurable and have injectables: "
+            + "in this case, your class can't make use of any injectables in the __init__ function, as the injectables "
+            + "will only be provided later.  Any use of injectables must be deferred until after object creation."
+        )
+
+    def set_di(self, di):
+        self._di = di
+
+    @abstractmethod
+    def __get__(self, instance, parent):
+        pass

clearskies/di/injectable_properties.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self
+
+from clearskies.di.injectable import Injectable
+
+if TYPE_CHECKING:
+    from clearskies.di import Di
+
+
+class InjectableProperties:
+    """
+    Fetch dependencies via properties rather than constructor arguments.
+
+    This class allows you to specify dependencies by setting them as class properties instead of constructor
+    arguments.  This is common in clearskies as it helps make easily reusable classes - configuration can
+    go in the constructor of the class, allowing the developer to directly instantiate it, and then the DI system
+    will come by afterwards and provide the necessary dependencies.
+
+    After adding InjectableProperties as a parent of your class, you have two ways to specify your dependencies:
+
+     1. By using the classes in the `clearskies.di.inject.*`module.
+     2. By directly attaching objects which also use the `InjectableProperties` class.
+
+    The following table shows the dependencies that can be injected as properties via the clearskies.di.inject module:
+
+    | Class                            | Type                                 | Result                                          |
+    |----------------------------------|--------------------------------------|-------------------------------------------------|
+    | clearskies.di.inject.ByClass     | N/A                                  | The specified class will be built               |
+    | clearskies.di.inject.ByName      | N/A                                  | The specified dependnecy name will be built     |
+    | clearskies.di.inject.Cursor      | N/A                                  | The PyMySQL cursor                              |
+    | clearskies.di.inject.Di          | N/A                                  | The dependency injection container itself       |
+    | clearskies.di.inject.Environment | clearskies.Environment               | The environment helper                          |
+    | clearskies.di.inject.InputOutput | clearskies.input_outputs.InputOutput | The InputOutput object for the current request  |
+    | clearskies.di.inject.Now         | datetime.datetime                    | The current time (no timezone)                  |
+    | clearskies.di.inject.Requests    | requests.Session                     | A requests session                              |
+    | clearskies.di.inject.Utcnow      | datetime.datetime                    | The current time (tzinfo=datetime.timezone.utc) |
+
+    Note: now/utcnow are not cached, so you'll get the current time everytime you get a value out of the class property,
+    unless a specific time has been set on the dependency injection container.
+
+    Here's an example:
+
+    ```python
+    import clearskies
+    import time
+    import clearskies.decorators
+
+
+    class MyOtherThing(clearskies.di.InjectableProperties):
+        now = clearskies.di.inject.Now()
+
+
+    class ReusableClass(clearskies.Configurable, clearskies.di.InjectableProperties):
+        my_int = clearskies.configs.Integer(required=True)
+        some_number = clearskies.di.inject.ByName("some_number")
+        my_other_thing = clearskies.di.inject.ByClass(MyOtherThing)
+
+        @clearskies.decorators.parameters_to_properties
+        def __init__(self, my_int: int):
+            self.finalize_and_validate_configuration()
+
+        def my_value(self) -> int:
+            return self.my_int * self.some_number
+
+
+    class MyClass(clearskies.di.InjectableProperties):
+        reusable = ReusableClass(5)
+
+
+    class MyOtherClass(clearskies.di.InjectableProperties):
+        reusable = ReusableClass(10)
+
+
+    di = clearskies.di.Di(
+        bindings={
+            "some_number": 10,
+        }
+    )
+
+    my_class = di.build(MyClass)
+    print(my_class.reusable.my_value())  # prints 50
+
+    my_other_class = di.build(MyOtherClass)
+    print(my_other_class.reusable.my_value())  # prints 100
+
+    start = my_class.reusable.my_other_thing.now
+    time.sleep(1)
+    stop = my_class.reusable.my_other_thing.now
+    print((stop - start).seconds)  # prints 1
+    ```
+    """
+
+    _injectables_loaded: str = ""
+
+    @classmethod
+    def injectable_properties(cls, di: Di):
+        # you would think that I would be able to just use a simple true/false flag attached to the class,
+        # but I'm having this weird issue where (when I tried that) the flag was being shared between classes.
+        # It shouldn't happen like that, but it is, so there is probably something subtle going on that I
+        # haven't figured out yet, but this also works identitally, so :shrug:.
+        # Also, keep track of the id of DI.  We use class level caching but tests often use multiple DI containers
+        # in one run, which means that we need to re-inject dependencies if we get a new DI container
+        cache_name = str(cls) + str(id(di))
+        if cache_name == cls._injectables_loaded:
+            return
+
+        injectable_descriptors: list[Any] = []
+        injectable_properties: list[Self] = []
+        for attribute_name in dir(cls):
+            # Per the docs above, we want to inject properties for one of two things: the injectables from clearskies.di.inject,
+            # and any object that itself extends this class.  This is mildly tricky because the injectables are descriptors, and
+            # so we get them using getattr on the class, while if it's not a descriptor, then we want to use getattr on self.
+            # The important part here is that we modify descriptors at the class level, so the actual injected values have to
+            # be stored in self, and not in the descriptor object.  When it's not a descriptor, then we can modify the object
+            # directly (since we're operating at the object level, not class level).  Either way, while we go, let's keep track
+            # of what our dependencies are and which ones are cached, so we only have to list the objects attributes the first time.
+            attribute = getattr(cls, attribute_name)
+
+            if di.has_class_override(attribute.__class__):
+                setattr(cls, attribute_name, di.get_override_by_class(attribute))
+                continue
+
+            if issubclass(attribute.__class__, Injectable):
+                attribute.set_di(di)
+                continue
+
+            if hasattr(attribute, "injectable_properties"):
+                attribute.injectable_properties(di)
+
+        cls._injectables_loaded = cache_name

clearskies/end.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from clearskies import typing
+    from clearskies.input_outputs import InputOutput
+
+from clearskies import configs, configurable, di, exceptions
+from clearskies.authentication import Authorization, Public
+from clearskies.functional import string
+
+
+class End(
+    ABC,
+    configurable.Configurable,
+    di.InjectableProperties,
+):
+    """
+    DRY for endpoint and endpoint groups.
+
+    This class is just here to hold some common functionality between Endpoints and EndpointGroups.
+    The two classes have plenty of overlap but are different enough that I don't want either to inherit
+    from the other.
+    """
+
+    di = di.inject.Di()
+
+    url = configs.String(required=False, default="")
+
+    authentication = configs.Authentication(default=None)
+
+    authorization = configs.Authorization(default=None)
+
+    internal_casing = configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
+    external_casing = configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
+    response_headers = configs.StringListOrCallable(default=[])
+    authentication = configs.Authentication(default=Public())
+    authorization = configs.Authorization(default=Authorization())
+    security_headers = configs.SecurityHeaders(default=[])
+
+    cors_header: SecurityHeader = None  # type: ignore
+    has_cors: bool = False
+
+    def add_url_prefix(self, prefix: str) -> None:
+        self.url = (prefix.rstrip("/") + "/" + self.url.lstrip("/")).lstrip("/")
+
+    def top_level_authentication_and_authorization(self, input_output: InputOutput) -> None:
+        """
+        Handle authentication and authorization for this endpoint.
+
+        In the event of an AuthN/AuthZ issue, raise an exception.  Otherwise, return None
+        """
+        if not self.authentication:
+            return
+        try:
+            if not self.authentication.authenticate(input_output):
+                raise exceptions.Authentication("Not Authenticated")
+        except exceptions.ClientError as client_error:
+            raise exceptions.Authentication(str(client_error))
+        if self.authorization:
+            try:
+                if not self.authorization.gate(input_output.authorization_data, input_output):
+                    raise exceptions.Authorization("Not Authorized")
+            except exceptions.ClientError as client_error:
+                raise exceptions.Authorization(str(client_error))
+
+    def __call__(self, input_output: InputOutput) -> Any:
+        """
+        Execute the endpoint.
+
+        This function mostly just checks AuthN/AuthZ and then passes along control to the handle method.
+        It also checks for all the appropriate exceptions from clearskies.exceptions and turns those into the
+        expected response.  As a result, when building a new endpoint, you normally modify the handle method
+        rather than this one.
+        """
+        # these two configs can have arbitrary classes attached, which may use injectable properties.  Because they are
+        # hiding in configs, the system for automatically discovering these won't work, so we have to manually check them.
+        # We can't do this in the constructor because self.di hasn't been populated yet, and we can't do this in
+        # our own injectable_properties class method because we need to operate at the instance level
+        for config_name in ["authentication", "authorization"]:
+            config = getattr(self, config_name)
+            if config and hasattr(config, "injectable_properties"):
+                config.injectable_properties(self.di)
+
+        response = self.populate_routing_data(input_output)
+        if response:
+            return response
+
+        # catch everything when we do an AuthN/AuthZ check because we allow custom-defined classes,
+        # and this gives more flexibility (or possibly forgiveness) for how they raise exceptions.
+        try:
+            self.top_level_authentication_and_authorization(input_output)
+        except exceptions.Authentication as auth_error:
+            return self.error(input_output, str(auth_error), 401)
+        except exceptions.Authorization as auth_error:
+            return self.error(input_output, str(auth_error), 403)
+        except exceptions.NotFound as not_found:
+            return self.error(input_output, str(not_found), 404)
+        except exceptions.MovedPermanently as redirect:
+            return self.redirect(input_output, str(redirect), 302)
+        except exceptions.MovedTemporarily as redirect:
+            return self.redirect(input_output, str(redirect), 307)
+
+        try:
+            response = self.handle(input_output)
+        except exceptions.ClientError as client_error:
+            return self.error(input_output, str(client_error), 400)
+        except exceptions.InputErrors as input_errors:
+            return self.input_errors(input_output, input_errors.errors)
+        except exceptions.Authentication as auth_error:
+            return self.error(input_output, str(auth_error), 401)
+        except exceptions.Authorization as auth_error:
+            return self.error(input_output, str(auth_error), 403)
+        except exceptions.NotFound as auth_error:
+            return self.error(input_output, str(auth_error), 404)
+        except exceptions.MovedPermanently as redirect:
+            return self.redirect(input_output, str(redirect), 302)
+        except exceptions.MovedTemporarily as redirect:
+            return self.redirect(input_output, str(redirect), 307)
+
+        return response
+
+    def populate_routing_data(self, input_output: InputOutput) -> Any:
+        raise NotImplementedError()
+
+    def add_response_headers(self, input_output: InputOutput) -> None:
+        if self.response_headers:
+            if callable(self.response_headers):
+                response_headers = self.di.call_function(
+                    self.response_headers, **input_output.get_context_for_callables()
+                )
+            else:
+                response_headers = self.response_headers
+
+            for index, response_header in enumerate(response_headers):
+                if not isinstance(response_header, str):
+                    raise TypeError(
+                        f"Invalid response header in entry #{index + 1}: the header should be a string, but I was given a type of '{response_header.__class__.__name__}' instead."
+                    )
+                parts = response_header.split(":", 1)
+                if len(parts) != 2:
+                    raise ValueError(
+                        f"Invalid response header in entry #{index + 1}: the header should be a string in the form of 'key: value' but the given header did not have a colon to separate key and value."
+                    )
+                input_output.response_headers.add(parts[0], parts[1])
+        for security_header in self.security_headers:
+            security_header.set_headers_for_input_output(input_output)
+
+    def respond(self, input_output: InputOutput, response: typing.response, status_code: int) -> Any:
+        self.add_response_headers(input_output)
+        return input_output.respond(response, status_code)
+
+    def respond_json(self, input_output: InputOutput, response_data: dict[str, Any], status_code: int) -> Any:
+        if "content-type" not in input_output.response_headers:
+            input_output.response_headers.add("content-type", "application/json")
+        return self.respond(input_output, self.normalize_response(response_data), status_code)
+
+    def normalize_response(self, response_data: dict[str, Any]) -> dict[str, Any]:
+        if "status" not in response_data:
+            raise ValueError("Huh, status got left out somehow")
+        return {
+            self.auto_case_internal_column_name("status"): self.auto_case_internal_column_name(response_data["status"]),
+            self.auto_case_internal_column_name("error"): response_data.get("error", ""),
+            self.auto_case_internal_column_name("data"): response_data.get("data", []),
+            self.auto_case_internal_column_name("pagination"): self.normalize_pagination(
+                response_data.get("pagination", {})
+            ),
+            self.auto_case_internal_column_name("input_errors"): response_data.get("input_errors", {}),
+        }
+
+    def normalize_pagination(self, pagination: dict[str, Any]) -> dict[str, Any]:
+        # pagination isn't always relevant so if it is completely empty then leave it that way
+        if not pagination:
+            return pagination
+        return {
+            self.auto_case_internal_column_name("number_results"): pagination.get("number_results", 0),
+            self.auto_case_internal_column_name("limit"): pagination.get("limit", 0),
+            self.auto_case_internal_column_name("next_page"): {
+                self.auto_case_internal_column_name(key): value
+                for (key, value) in pagination.get("next_page", {}).items()
+            },
+        }
+
+    def auto_case_internal_column_name(self, column_name: str) -> str:
+        if self.external_casing:
+            return string.swap_casing(column_name, "snake_case", self.external_casing)
+        return column_name
+
+    def auto_case_column_name(self, column_name: str, internal_to_external: bool) -> str:
+        if not self.internal_casing:
+            return column_name
+        if internal_to_external:
+            return string.swap_casing(
+                column_name,
+                self.internal_casing,
+                self.external_casing,
+            )
+        return string.swap_casing(
+            column_name,
+            self.external_casing,
+            self.internal_casing,
+        )
+
+    def error(self, input_output: InputOutput, message: str, status_code: int) -> Any:
+        """Return a client-side error (e.g. 400)."""
+        return self.respond_json(input_output, {"status": "client_error", "error": message}, status_code)
+
+    def input_errors(self, input_output: InputOutput, errors: dict[str, str], status_code: int = 200) -> Any:
+        """Return input errors to the client."""
+        return self.respond_json(input_output, {"status": "input_errors", "input_errors": errors}, status_code)
+
+    def redirect(self, input_output: InputOutput, location: str, status_code: int) -> Any:
+        """Return a redirect response (e.g. 302)."""
+        return self.respond_json(input_output, {"status": "redirect", "location": location}, status_code)
+
+    def handle(self, input_output: InputOutput) -> Any:
+        raise NotImplementedError()