clear-skies 2.0.2__tar.gz → 2.0.3__tar.gz

{clear_skies-2.0.2 → clear_skies-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: clear-skies
-Version: 2.0.2
+Version: 2.0.3
 Summary: A framework for building backends in the cloud
 License: MIT
 Author: Conor Mancone

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/columns/belongs_to_id.py

@@ -356,11 +356,11 @@ class BelongsToId(String):
         parent_model = self.parent_model
         matching_parents = parent_model.where(f"{parent_model.id_column_name}={value}")
         matching_parents = self.apply_wheres(matching_parents)
-        matching_parents = matching_parents.where_for_request(
+        matching_parents = matching_parents.where_for_request_all(
             matching_parents,
-            self.input_output.routing_data,
-            self.input_output.authorization_data,
             self.input_output,
+            routing_data=self.input_output.routing_data,
+            authorization_data=self.input_output.authorization_data,
         )
         if not len(matching_parents):
             return f"Invalid selection for {self.name}: record does not exist"

clear_skies-2.0.3/src/clearskies/contexts/cli.py

@@ -0,0 +1,117 @@
+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.
+    """
+
+    def __call__(self):  # type: ignore
+        return self.execute_application(CliInputOutput())

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/contexts/context.py

@@ -48,6 +48,7 @@ class Context:
             bindings=bindings,
             additional_configs=additional_configs,
             class_overrides=class_overrides,
+            overrides=overrides,
             now=now,
             utcnow=utcnow,
         )

clear_skies-2.0.3/src/clearskies/contexts/wsgi.py

@@ -0,0 +1,76 @@
+import datetime
+from types import ModuleType
+from typing import Any, Callable
+from wsgiref.simple_server import make_server
+from wsgiref.util import setup_testing_defaults
+
+import clearskies.endpoint
+import clearskies.endpoint_group
+from clearskies.contexts.context import Context
+from clearskies.di import AdditionalConfig
+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.
+
+    """
+
+    def __call__(self, env, start_response):  # type: ignore
+        return self.execute_application(WsgiInputOutput(env, start_response))

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/contexts/wsgi_ref.py

@@ -14,6 +14,35 @@ from clearskies.input_outputs import Wsgi as WsgiInputOutput
 class WsgiRef(Context):
     """
     Use a built in WSGI server (for development purposes only).
+
+    This context will launch a built-in HTTP server for you, so you can run applications locally
+    without having to install extra dependencies.  Note that this server is not intended for production
+    usage, so this is best used for simple tests/demonstration purposes.  Unlike the WSGI context, where
+    you define the application handler and invoke the context from inside of it (passing along the
+    environment and start_response variables), in this case you simply directly invoke the context to
+    launch the server.  The default port is 8080:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+    def hello_world(name):
+        return f"Hello {name}!"
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Callable(
+            hello_world,
+            url="/hello/:name",
+        )
+    )
+    wsgi()
+    ```
+
+    And to invoke it:
+
+    ```
+    curl 'http://localhost:8080/hello/Friend'
+    ```
     """
 
     port: int = 8080

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/endpoint.py

@@ -963,11 +963,11 @@ class Endpoint(
                 model = self.di.call_function(where, model=model, **input_output.get_context_for_callables())
             else:
                 model = model.where(where)
-        model = model.where_for_request(
+        model = model.where_for_request_all(
             model,
+            input_output,
             input_output.routing_data,
             input_output.authorization_data,
-            input_output,
             overrides=self.column_overrides,
         )
         return self.authorization.filter_model(model, input_output.authorization_data, input_output)

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/input_outputs/cli.py

@@ -20,12 +20,13 @@ class Cli(InputOutput):
         super().__init__()
 
     def respond(self, response, status_code=200):
-        if status_code != 200:
-            sys.exit(response)
         if type(response) != str:
-            print(json.dumps(response))
+            final = json.dumps(response)
         else:
-            print(response)
+            final = response
+        if status_code != 200:
+            sys.exit(final)
+        print(final)
 
     def get_arguments(self):
         return sys.argv

{clear_skies-2.0.2 → clear_skies-2.0.3}/src/clearskies/model.py

@@ -983,6 +983,48 @@ class Model(Schema, InjectableProperties):
         It has no retrun value and is passed no data.  By the time this fires the model has already been
         updated with the new data.  You can decide on the necessary actions using the `was_changed` and
         the `previous_value` functions.
+
+        ```
+        from typing import Any, Self
+        import clearskies
+
+        class History(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            message = clearskies.columns.String()
+            created_at = clearskies.columns.Created(date_format="%Y-%m-%d %H:%M:%S.%f")
+
+        class User(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+            histories = clearskies.di.inject.ByClass(History)
+
+            id = clearskies.columns.Uuid()
+            age = clearskies.columns.Integer()
+            name = clearskies.columns.String()
+
+            def save_finished(self: Self) -> None:
+                if not self.was_changed("age"):
+                    return
+
+                self.histories.create({"message": f"My name is {self.name} and I am {self.age} years old"})
+
+        def my_application(users, histories):
+            jane = users.create({"name": "Jane"})
+            jane.save({"age": 25})
+            jane.save({"age": 26})
+            jane.save({"age": 30})
+
+            return [history.message for history in histories.sort_by("created_at", "ASC")]
+
+        cli = clearskies.contexts.Cli(
+            my_application,
+            classes=[User, History],
+        )
+        cli()
+        ```
         """
         pass
 
@@ -1004,18 +1046,86 @@ class Model(Schema, InjectableProperties):
         """Create a hook to extend so you can provide additional post-delete logic as needed."""
         pass
 
-    def where_for_request(
+    def where_for_request_all(
         self: Self,
-        models: Self,
+        model: Self,
+        input_output: Any,
         routing_data: dict[str, str],
         authorization_data: dict[str, Any],
-        input_output: Any,
         overrides: dict[str, Column] = {},
     ) -> Self:
-        """Create a hook to automatically apply filtering whenever the model makes an appearance in a get/update/list/search handler."""
+        """
+        A hook to automatically apply filtering whenever the model makes an appearance in a get/update/list/search handler.
+        """
         for column in self.get_columns(overrides=overrides).values():
-            models = column.where_for_request(models, routing_data, authorization_data, input_output)  # type: ignore
-        return models
+            models = column.where_for_request(model, input_output, routing_data, authorization_data)  # type: ignore
+        return self.where_for_request(
+            model, input_output, routing_data=routing_data, authorization_data=authorization_data, overrides=overrides
+        )
+
+    def where_for_request(
+        self: Self,
+        model: Self,
+        input_output: Any,
+        routing_data: dict[str, str],
+        authorization_data: dict[str, Any],
+        overrides: dict[str, Column] = {},
+    ) -> Self:
+        """
+        A hook to automatically apply filtering whenever the model makes an appearance in a get/update/list/search handler.
+
+        Note that this automatically affects the behavior of the various list endpoints, but won't be called when you create your
+        own queries directly.  Here's an example where the model restricts the list endpoint so that it only returns users with
+        an age over 18:
+
+        ```
+        from typing import Any, Self
+        import clearskies
+
+        class User(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+            id = clearskies.columns.Uuid()
+            name = clearskies.columns.String()
+            age = clearskies.columns.Integer()
+
+            def where_for_request(
+                self: Self,
+                model: Self,
+                input_output: Any,
+                routing_data: dict[str, str],
+                authorization_data: dict[str, Any],
+                overrides: dict[str, clearskies.Column] = {},
+            ) -> Self:
+                return model.where("age>=18")
+
+        list_users = clearskies.endpoints.List(
+            model_class=User,
+            readable_column_names=["id", "name", "age"],
+            sortable_column_names=["id", "name", "age"],
+            default_sort_column_name="name",
+        )
+
+        wsgi = clearskies.contexts.WsgiRef(
+            list_users,
+            classes=[User],
+            bindings={
+                "memory_backend_default_data": [
+                    {
+                        "model_class": User,
+                        "records": [
+                            {"id": "1-2-3-4", "name": "Bob", "age": 20},
+                            {"id": "1-2-3-5", "name": "Jane", "age": 17},
+                            {"id": "1-2-3-6", "name": "Greg", "age": 22},
+                        ],
+                    },
+                ]
+            },
+        )
+        wsgi()
+        ```
+        """
+        return model
 
     ##############################################################
     ### From here down is functionality related to list/search ###

clear_skies-2.0.2/src/clearskies/contexts/cli.py

@@ -1,11 +0,0 @@
-from clearskies.contexts.context import Context
-from clearskies.input_outputs import Cli as CliInputOutput
-
-
-class Cli(Context):
-    """
-    Run an application via a CLI command
-    """
-
-    def __call__(self):  # type: ignore
-        return self.execute_application(CliInputOutput())

clear_skies-2.0.2/src/clearskies/contexts/wsgi.py

@@ -1,20 +0,0 @@
-import datetime
-from types import ModuleType
-from typing import Any, Callable
-from wsgiref.simple_server import make_server
-from wsgiref.util import setup_testing_defaults
-
-import clearskies.endpoint
-import clearskies.endpoint_group
-from clearskies.contexts.context import Context
-from clearskies.di import AdditionalConfig
-from clearskies.input_outputs import Wsgi as WsgiInputOutput
-
-
-class Wsgi(Context):
-    """
-    Connect your application to a WSGI server.
-    """
-
-    def __call__(self, env, start_response):  # type: ignore
-        return self.execute_application(WsgiInputOutput(env, start_response))