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

clearskies/configs/timezone.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import datetime
+
+from clearskies.configs import config
+
+
+class Timezone(config.Config):
+    def __set__(self, instance, value: datetime.timezone | None):
+        if value and not isinstance(value, datetime.timezone):
+            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 timezone (datetime.timezone)."
+            )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> datetime.timezone:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/url.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from clearskies.configs import string
+from clearskies.functional import routing
+
+
+class Url(string.String):
+    def __set__(self, instance, value: str):
+        if value is None:
+            return
+
+        if not isinstance(value, str):
+            error_prefix = self._error_prefix(instance)
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a url parameter"
+            )
+        value = value.strip("/")
+
+        if value:
+            try:
+                routing.extract_url_parameter_name_map(value)
+            except ValueError as e:
+                error_prefix = self._error_prefix(instance)
+                raise ValueError(f"{error_prefix} {e}")
+        instance._set_config(self, value)

clearskies/configs/validators.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies import typing
+
+
+class Validators(config.Config):
+    """
+    Validator config.
+
+    A config that accepts various things that are accepted as validators in model columns:
+
+     1. An instance of clearskies.validators.Validator
+     2. A list of clearskies.validators.Validator
+
+    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.validator | list[typing.validator],
+    ):
+        if not isinstance(value, list):
+            value = [value]
+
+        for index, item in enumerate(value):
+            if hasattr(item, "additional_write_columns") and hasattr(item, "check"):
+                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 Validator is required"
+            )
+
+        instance._set_config(self, [*value])
+
+    def __get__(self, instance, parent) -> list[typing.validator]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/configs/writeable_model_column.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from clearskies.configs import model_column
+
+
+class WriteableModelColumn(model_column.ModelColumn):
+    def get_allowed_columns(self, model_class, column_configs):
+        return [name for (name, column) in column_configs.items() if column.is_writeable]
+
+    def my_description(self):
+        return "writeable column"

clearskies/configs/writeable_model_columns.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from clearskies.configs import model_columns
+
+
+class WriteableModelColumns(model_columns.ModelColumns):
+    def get_allowed_columns(self, model_class, column_configs):
+        return [name for (name, column) in column_configs.items() if column.is_writeable]
+
+    def my_description(self):
+        return "writeable column"

clearskies/configurable.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from clearskies.configs import config
+
+
+class Configurable:
+    _config: dict[str, Any] | None = None
+    _descriptor_config_map: dict[int, str] | None = None
+
+    def _set_config(self, descriptor, value):
+        if not self._config:
+            self._config = {}
+
+        self._config[self._descriptor_to_name(descriptor)] = value
+
+    def _get_config(self, descriptor):
+        if not self._config:
+            self._config = {}
+
+        name = self._descriptor_to_name(descriptor)
+        if name not in self._config:
+            raise KeyError(f"Attempt to fetch a config value named '{name}' but no value has been set for this config")
+        return self._config[name]
+
+    @classmethod
+    def _get_config_object(cls, attribute_name):
+        return getattr(cls, attribute_name)
+
+    @classmethod
+    def get_descriptor_config_map(cls):
+        if cls._descriptor_config_map:
+            return cls._descriptor_config_map
+
+        descriptor_config_map = {}
+        for attribute_name in dir(cls):
+            descriptor = getattr(cls, attribute_name)
+            if not isinstance(descriptor, config.Config):
+                continue
+
+            descriptor_config_map[id(descriptor)] = attribute_name
+
+        cls._descriptor_config_map = descriptor_config_map
+        return cls._descriptor_config_map
+
+    def _descriptor_to_name(self, descriptor):
+        descriptor_config_map = self.get_descriptor_config_map()
+        if id(descriptor) not in descriptor_config_map:
+            raise ValueError(
+                f"The reason behind this error is kinda long and complicated, but doens't really matter.  To make it go away, just add `_descriptor_config_map = None` to the definition of {self.__class__.__name__}"
+            )
+        return descriptor_config_map[id(descriptor)]
+
+    def finalize_and_validate_configuration(self):
+        my_class = self.__class__
+        if not self._config:
+            self._config = {}
+
+        # now it's time to check for required values and provide defaults
+        attribute_names = self.get_descriptor_config_map().values()
+        for attribute_name in attribute_names:
+            config = getattr(my_class, attribute_name)
+            if attribute_name not in self._config:
+                self._config[attribute_name] = config.default
+
+            if config.required and self._config.get(attribute_name) is None:
+                raise ValueError(
+                    f"Missing required configuration property '{attribute_name}' for class '{my_class.__name__}'"
+                )
+
+        # loop through a second time to have the configs check their values
+        # we do this as a separate step because we want to make sure required and default
+        # values are specified before we have the configs do their validation.
+        for attribute_name in attribute_names:
+            getattr(my_class, attribute_name).finalize_and_validate_configuration(self)
+            if attribute_name not in self._config:
+                self._config[attribute_name] = None

clearskies/contexts/__init__.py

@@ -1,11 +1,11 @@
-from .build_context import build_context
-from .cli import cli
-from .test import test
-from .wsgi import wsgi
+from clearskies.contexts.cli import Cli
+from clearskies.contexts.context import Context
+from clearskies.contexts.wsgi import Wsgi
+from clearskies.contexts.wsgi_ref import WsgiRef
 
 __all__ = [
-    "build_context",
-    "cli",
-    "test",
-    "wsgi",
+    "Cli",
+    "Context",
+    "Wsgi",
+    "WsgiRef",
 ]

clearskies/contexts/cli.py

@@ -1,44 +1,130 @@
-from ..authentication import public
-from ..input_outputs import CLI as CLIInputOutput
-from ..input_outputs import exceptions
-from .build_context import build_context
-from .context import Context
-
-
-class CLI(Context):
-    def __init__(self, di):
-        super().__init__(di)
-
-    def finalize_handler_config(self, config):
-        return {
-            "authentication": public(),
-            **config,
-        }
-
-    def __call__(self):
-        if self.handler is None:
-            raise ValueError("Cannot execute CLI context without first configuring it")
-
-        try:
-            return self.handler(self.di.build(CLIInputOutput))
-        except exceptions.CLINotFound:
-            print("help (aka 404 not found)!")
-
-
-def cli(
-    application,
-    di_class=None,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        CLI,
-        application,
-        di_class=di_class,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
+from clearskies.contexts.context import Context
+from clearskies.input_outputs import Cli as CliInputOutput
+
+
+class Cli(Context):
+    """
+    Run an application via a CLI command.
+
+    This context converts a clearskies application into a CLI command.  Here's a simple example:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+
+    def my_function():
+        return "Hello World!"
+
+
+    cli = clearskies.contexts.Cli(my_function)
+    cli()
+    ```
+
+    Which you can then run as expected:
+
+    ```
+    $ ./example.py
+    Hello World!
+    ```
+
+    Routing is still supported, with routes and route parameters becoming CLI args:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+
+    def my_function(name):
+        return f"Hello {name}!"
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            my_function,
+            url="/hello/:name",
+            return_standard_response=False,
+        )
     )
+    cli()
+    ```
+
+    With a url of `/hello/:name` you would invoke like so:
+
+    ```
+    ./example.py hello Bob
+    Hello Bob!
+    ```
+
+    If the endpoint expects a request method you can provide it by setting the `-X` or `--request_method=`
+    kwargs.  So for tihs example:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+
+    def my_function(name):
+        return f"Hello {name}!"
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            my_function,
+            url="/hello/:name",
+            request_methods=["POST"],
+        )
+    )
+    cli()
+    ```
+
+    And then calling it successfully:
+
+    ```
+    ./example.py hello Bob --request_method=POST
+
+    ./example.py hello Bob -X POST
+    ```
+
+    You can pass data as a json string with the -d flag or set individual named arguments.  The following
+    example just reflects the request data back to the client:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+
+    def my_function(request_data):
+        return request_data
+
+
+    cli = clearskies.contexts.Cli(
+        clearskies.endpoints.Callable(
+            my_function,
+        )
+    )
+    cli()
+    ```
+
+    And these three calls are identical:
+
+    ```
+    ./example.py -d '{"hello": "world"}'
+
+    echo '{"hello": "world"}' | ./test.py
+
+    ./test.py --hello=world
+    ```
+
+    Although note that the first two are going to be preferred over the third, simply because with the
+    third there's simply no way to specify the type of a variable.  As a result, you may run into issues
+    with strict type checking on endpoints.
+
+    ### Context Callables
+
+    When using the Cli context, an additional named argument is made available to any callables invoked by clearskies:
+    `sys_argv`.  This contains `sys.argv`.
+    """
+
+    def __call__(self):  # type: ignore
+        return self.execute_application(CliInputOutput())

clearskies/contexts/context.py

@@ -1,62 +1,99 @@
-from ..handlers import callable as callable_module
+from __future__ import annotations
+
+import datetime
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies import exceptions
+from clearskies.di import Di
+from clearskies.di.additional_config import AdditionalConfig
+from clearskies.input_outputs import InputOutput, Programmatic
+
+if TYPE_CHECKING:
+    from clearskies.endpoint import Endpoint
+    from clearskies.endpoint_group import EndpointGroup
 
 
 class Context:
-    di = None
-    handler = None
-
-    def __init__(self, di):
-        self.di = di
-
-    def configure(self, application):
-        self.handler = self.extract_handler(application)
-
-    def bind(self, key, value):
-        self.di.bind(key, value)
-
-    def build(self, key):
-        return self.di.build(key)
-
-    def mock_class(self, class_or_name, replacement):
-        self.di.mock_class(class_or_name, replacement)
-
-    def extract_handler(self, application):
-        """
-        This accepts the application passed in to the context and returns the handler
-
-        Most importantly, it doesn't technically have to be an application: if passed a simple function
-        it will assume you mean to use the callable handler, and if passed a dictionary with 'handler_class'
-        and 'handler_config' keys, it will build a handler from that.
-        """
-        # applications will have a handler_class property
-        if hasattr(application, "handler_class"):
-            handler = self.di.build(application.handler_class, cache=False)
-            handler.configure(self.finalize_handler_config(application.handler_config))
-            return handler
-
-        # check for a dictionary with the same thing (in case the developer doesn't want to bother with
-        # an application
-        if hasattr(application, "__getitem__") and "handler_class" in application:
-            if not "handler_config" in application:
-                raise ValueError(
-                    "context was passed a dictionary-like object with 'handler_class', but not "
-                    + "'handler_config'.  Both are required to execute the handler"
+    """Context: a flexible way to connect applications to hosting strategies."""
+
+    di: Di = None  # type: ignore
+
+    """
+    The application to execute.
+
+    This can be a callable, an endpoint, or an endpoint group.  If passed a callable, the callable can request any
+    standard or defined dependencies and should return the desired response.  It can also raise any exception from
+    exceptions.
+    """
+    application: Callable | Endpoint | EndpointGroup = None  # type: ignore
+
+    def __init__(
+        self,
+        application: Callable | Endpoint | EndpointGroup,
+        classes: type | list[type] = [],
+        modules: ModuleType | list[ModuleType] = [],
+        bindings: dict[str, Any] = {},
+        additional_configs: AdditionalConfig | list[AdditionalConfig] = [],
+        class_overrides: dict[type, Any] = {},
+        overrides: dict[str, type] = {},
+        now: datetime.datetime | None = None,
+        utcnow: datetime.datetime | None = None,
+    ):
+        self.di = Di(
+            classes=classes,
+            modules=modules,
+            bindings=bindings,
+            additional_configs=additional_configs,
+            class_overrides=class_overrides,
+            overrides=overrides,
+            now=now,
+            utcnow=utcnow,
+        )
+        self.application = application
+
+    def execute_application(self, input_output: InputOutput):
+        self.di.add_binding("input_output", input_output)
+        self.di.add_class_override(InputOutput, input_output)
+
+        if hasattr(self.application, "injectable_properties"):
+            self.application.injectable_properties(self.di)
+            return self.application(input_output)
+        elif callable(self.application):
+            try:
+                return input_output.respond(
+                    self.di.call_function(self.application, **input_output.get_context_for_callables())
                 )
-            handler = self.di.build(application["handler_class"], cache=False)
-            handler.configure(self.finalize_handler_config(application["handler_config"]))
-            return handler
-
-        # if we get a callable, then use the callable handler class
-        if callable(application):
-            handler = self.di.build(callable_module.Callable, cache=False)
-            handler.configure(self.finalize_handler_config({"callable": application}))
-            return handler
-
-        raise ValueError(
-            "The context received an object it did not know how to handle!  You should pass in either an instance "
-            + "of clearskies.Application, a dictionary with 'handler_class' and 'handler_config' keys, or a "
-            + "function/lambda to be executed"
+            except exceptions.ClientError as e:
+                return input_output.respond(str(e), 400)
+            except exceptions.Authentication as e:
+                return input_output.respond(str(e), 401)
+            except exceptions.Authorization as e:
+                return input_output.respond(str(e), 403)
+            except exceptions.NotFound as e:
+                return input_output.respond(str(e), 404)
+            except exceptions.MovedPermanently as e:
+                return input_output.respond(str(e), 302)
+            except exceptions.MovedTemporarily as e:
+                return input_output.respond(str(e), 307)
+
+    def __call__(
+        self,
+        url: str = "",
+        request_method: str = "GET",
+        body: str | dict[str, Any] | list[Any] = "",
+        query_parameters: dict[str, str] = {},
+        request_headers: dict[str, str] = {},
+    ):
+        return self.execute_application(
+            Programmatic(
+                url=url,
+                request_method=request_method,
+                body=body,
+                query_parameters=query_parameters,
+                request_headers=request_headers,
+            )
         )
 
-    def finalize_handler_config(self, config):
-        return config
+    def build(self, thing: Any, cache: bool = False) -> Any:
+        return self.di.build(thing, cache=cache)

clearskies/contexts/wsgi.py

@@ -1,33 +1,79 @@
-from ..input_outputs import WSGI as WSGIInputOutput
-from .build_context import build_context
-from .context import Context
-
-
-class WSGI(Context):
-    def __init__(self, di):
-        super().__init__(di)
-
-    def __call__(self, env, start_response):
-        if self.handler is None:
-            raise ValueError("Cannot execute WSGI context without first configuring it")
-
-        return self.handler(WSGIInputOutput(env, start_response))
-
-
-def wsgi(
-    application,
-    di_class=None,
-    bindings=None,
-    binding_classes=None,
-    binding_modules=None,
-    additional_configs=None,
-):
-    return build_context(
-        WSGI,
-        application,
-        di_class=None,
-        bindings=bindings,
-        binding_classes=binding_classes,
-        binding_modules=binding_modules,
-        additional_configs=additional_configs,
-    )
+from __future__ import annotations
+
+from clearskies.contexts.context import Context
+from clearskies.input_outputs import Wsgi as WsgiInputOutput
+
+
+class Wsgi(Context):
+    """
+    Connect your application to a WSGI server.
+
+    The Wsgi context is used to connect a clearskies application to a WSGI server of your choice.  As with all
+    contexts, you first create it and pass in the application (a callable, endpoint, or endpoint group) as well
+    as any dependency injection parameters.  Then, you call the context from inside of the function invoked by
+    your WSGI server, passing along the `environment` and `start_response` variables, and returning the response
+    from the context.  Here's a simple example:
+
+    ```
+    import clearskies
+
+
+    def hello_world():
+        return "Hello World!"
+
+
+    wsgi = clearskies.contexts.Wsgi(hello_world)
+
+
+    def application(environment, start_response):
+        return wsgi(environment, start_response)
+    ```
+
+    You would then launch your WSGI server.  For instance, here's how to launch it with uwsgi, which automatically
+    looks for a function called `application` and treats that as the WSGI starting point:
+
+    ```
+    uwsgi --http :9090 --wsgi-file test.py
+    ```
+
+    You could then:
+
+    ```
+    curl 'http://localhost:9090'
+    ```
+
+    And see the response from this "hello world" app.  Note than in the above example I create the context outside
+    of the application function.  Of course, you can do the opposite:
+
+    ```
+    import clearskies
+
+
+    def hello_world():
+        return "Hello World!"
+
+
+    def application(environment, start_response):
+        wsgi = clearskies.contexts.Wsgi(hello_world)
+        return wsgi(environment, start_response)
+    ```
+
+    The difference is that most wsgi servers will cache any objects created outside of the handler function (e.g. `application`
+    in this case).  When you first create the context clearskies will configure and validate any endpoints attached.
+    Also, it will create an instance of the dependency injection container and cache it.  If the context object is created
+    outside of the handler, and the server caches objects in this csae, then this validation will only happen once and
+    the DI cache will store objects in between HTTP calls.  If you create your context inside the handler function, then
+    you'll end up with an empty cache everytime and you'll have slower responses because of clearskies checking the
+    application configuration everytime.  Note that the DI system for clearskies grants you full cache control, so
+    by and large it's normal and expected that you'll persist the cache between requests by creating the context outside
+    of any handler functions.
+
+    ### Context for Callables
+
+    When using this context, one additional named property becomes available to any callables invoked by clearskies:
+    `wsgi_environment`.  This contains the environment object passed in by the WSGI server to clearskies.
+
+    """
+
+    def __call__(self, env, start_response):  # type: ignore
+        return self.execute_application(WsgiInputOutput(env, start_response))