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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: clear-skies
-Version: 2.0.2
+Version: 2.0.4
 Summary: A framework for building backends in the cloud
 License: MIT
 Author: Conor Mancone
@@ -32,15 +32,5 @@ Description-Content-Type: text/markdown
 
 clearskies is a very opinionated Python framework intended for developing microservices in the cloud via declarative programming principles.  It is mainly intended for backend services and so is designed for RESTful API endpoints, queue listeners, scheduled tasks, and the like.
 
-## Installation, Documentation, and Usage
-
-To install:
-
-```bash
-pip3 install clear-skies
-```
-
-Documentation is under construction here:
-
 [https://clearskies.info](https://clearskies.info)
 

{clear_skies-2.0.2 → clear_skies-2.0.4}/README.md

@@ -2,14 +2,4 @@
 
 clearskies is a very opinionated Python framework intended for developing microservices in the cloud via declarative programming principles.  It is mainly intended for backend services and so is designed for RESTful API endpoints, queue listeners, scheduled tasks, and the like.
 
-## Installation, Documentation, and Usage
-
-To install:
-
-```bash
-pip3 install clear-skies
-```
-
-Documentation is under construction here:
-
 [https://clearskies.info](https://clearskies.info)

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/__init__.py

@@ -10,6 +10,7 @@ from . import (
     endpoints,
     exceptions,
     functional,
+    input_outputs,
     query,
     # secrets,
     security_headers,
@@ -39,6 +40,7 @@ __all__ = [
     "Configurable",
     "contexts",
     "di",
+    "input_outputs",
     "End",
     "Endpoint",
     "EndpointGroup",

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/autodoc/formats/oai3_json/__init__.py

@@ -1,7 +1,7 @@
-from .oai3_json import OAI3JSON
+from .oai3_json import Oai3Json
 from .oai3_schema_resolver import OAI3SchemaResolver
 
 __all__ = [
     "OAI3SchemaResolver",
-    "OAI3JSON",
+    "Oai3Json",
 ]

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/autodoc/formats/oai3_json/oai3_json.py

@@ -4,7 +4,7 @@ from typing import Any
 from .request import Request
 
 
-class OAI3JSON:
+class Oai3Json:
     requests: Any = None
     formatted: Any = None
     models: Any = None
@@ -67,7 +67,7 @@ class OAI3JSON:
             path_data = request.convert()
             for request_method, path_doc in path_data.items():
                 if request_method in paths[absolute_path]:
-                    raise ValueError(f"Two routes had the same path and method: {absolute_path} - {request_method}")
+                    continue
                 paths[absolute_path][request_method] = path_doc
 
         data: dict[str, Any] = {

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/autodoc/formats/oai3_json/schema/object.py

@@ -4,6 +4,12 @@ from typing import Any
 class Object:
     def __init__(self, schema, oai3_schema_resolver):
         self.schema = schema
+        # shhhh
+        self.schema.children = [
+            child[0] if (isinstance(child, tuple) or isinstance(child, list)) else child
+            for child in self.schema.children
+        ]
+
         self.oai3_schema_resolver = oai3_schema_resolver
 
     def convert(self, include_required=False):

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/autodoc/request/request.py

@@ -1,3 +1,4 @@
+import re
 from typing import Any
 
 
@@ -12,6 +13,14 @@ class Request:
     def __init__(
         self, description, responses, relative_path="", request_methods="GET", parameters=None, root_properties=None
     ):
+        # clearskies supports path parameters via {parameter} and :parameter but we want to normalize to {paramter} for
+        # autodoc purposes
+        if ":" in relative_path:
+            relative_path = "/" + relative_path.strip("/") + "/"
+            for match in re.findall("/(:[^/]+)/", relative_path):
+                name = match[1:]
+                relative_path = relative_path.replace(f"/:{name}/", "/{" + name + "}/")
+
         self.description = description
         self.responses = responses
         self.relative_path = relative_path.lstrip("/")

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/backends/backend.py

@@ -10,7 +10,7 @@ from clearskies.autodoc.schema import Schema as AutoDocSchema
 
 class Backend(ABC):
     """
-    Conecting models to their data since 2020!
+    Connecting models to their data since 2020!.
 
     The backend system acts as a flexible layer between models and their data sources.  By changing the backend attached to a model,
     you change where the model fetches and saves data.  This might be a database, an in-memory data store, a dynamodb table,

{clear_skies-2.0.2 → clear_skies-2.0.4}/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.4/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.4}/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.4/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.4}/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.4}/src/clearskies/di/di.py

@@ -15,6 +15,7 @@ import clearskies.secrets
 from clearskies.di.additional_config import AdditionalConfig
 from clearskies.di.additional_config_auto_import import AdditionalConfigAutoImport
 from clearskies.environment import Environment
+from clearskies.exceptions import MissingDependency
 from clearskies.functional import string
 
 
@@ -83,6 +84,7 @@ class Di:
     | connection_details   | -                                                       | A dictionary containing credentials that pymysql should use when connecting to a database |
     | connection           | -                                                       | A pymysql connection object                                                               |
     | cursor               | -                                                       | A pymysql cursor object                                                                   |
+    | endpoint_groups      | -                                                       | The list of endpoint groups handling the request                                          |
 
     Note: for dependencies with an injection name but no injection type, this means that to inject those values you
     must name your argument with the given injection name.  In all of the above cases though you can still add type
@@ -635,7 +637,7 @@ class Di:
             return self._prepared[name]
 
         context_note = f" for {context}" if context else ""
-        raise ValueError(
+        raise MissingDependency(
             f"I was asked to build {name}{context_note} but there is no added class, configured binding, "
             + f"or a corresponding 'provide_{name}' method for this name."
         )
@@ -966,3 +968,6 @@ class Di:
         import akeyless  # type: ignore
 
         return akeyless
+
+    def provide_endpoint_groups(self):
+        return []

{clear_skies-2.0.2 → clear_skies-2.0.4}/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)
@@ -1261,8 +1261,9 @@ class Endpoint(
     ) -> list[schema.Schema]:
         if schema is None:
             schema = self.model_class
-        if column_names is None and self.readable_column_names:
-            readable_column_names: list[str] = self.readable_column_names
+        readable_column_names = [*column_names]
+        if not readable_column_names and self.readable_column_names:
+            readable_column_names: list[str] = self.readable_column_names  # type: ignore
         properties = []
 
         columns = schema.get_columns()
@@ -1289,16 +1290,19 @@ class Endpoint(
 
         model_name = string.camel_case_to_snake_case(schema.__name__)
         columns = schema.get_columns()
-        return [
-            autodoc.request.JSONBody(
-                columns[column_name].documentation(name=self.auto_case_column_name(column_name, True)),
-                description=f"Set '{column_name}' for the {model_name}",
-                required=columns[column_name].is_required,
+        parameters = []
+        for column_name in column_names:
+            columns[column_name].injectable_properties(self.di)
+            parameters.append(
+                autodoc.request.JSONBody(
+                    columns[column_name].documentation(name=self.auto_case_column_name(column_name, True)),
+                    description=f"Set '{column_name}' for the {model_name}",
+                    required=columns[column_name].is_required,
+                )
             )
-            for column_name in column_names
-        ]
+        return parameters  # type: ignore
 
-    def standard_url_request_parameters(self) -> list[Parameter]:
+    def documentation_url_parameters(self) -> list[Parameter]:
         parameter_names = routing.extract_url_parameter_name_map(self.url.strip("/"))
         return [
             autodoc.request.URLPath(

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoint_group.py

@@ -230,6 +230,8 @@ class EndpointGroup(
     """
     endpoints = clearskies.configs.EndpointList()
 
+    internal_casing = clearskies.configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
+    external_casing = clearskies.configs.Select(["snake_case", "camelCase", "TitleCase"], default="snake_case")
     response_headers = clearskies.configs.StringListOrCallable(default=[])
     authentication = clearskies.configs.Authentication(default=Public())
     authorization = clearskies.configs.Authorization(default=Authorization())
@@ -238,6 +240,8 @@ class EndpointGroup(
     cors_header: SecurityHeader = None  # type: ignore
     has_cors: bool = False
     endpoints_initialized = False
+    external_casing = "snake_case"
+    internal_casing = "snake_case"
 
     @clearskies.decorators.parameters_to_properties
     def __init__(
@@ -246,6 +250,8 @@ class EndpointGroup(
         url: str = "",
         response_headers: list[str | Callable[..., list[str]]] = [],
         security_headers: list[SecurityHeader] = [],
+        internal_casing: str = "snake_case",
+        external_casing: str = "snake_case",
         authentication: Authentication = Public(),
         authorization: Authorization = Authorization(),
     ):
@@ -273,6 +279,11 @@ class EndpointGroup(
             if self.url.strip("/"):
                 endpoint.add_url_prefix(self.url)
 
+    def add_url_prefix(self, prefix: str) -> None:
+        self.url = (prefix.rstrip("/") + "/" + self.url.lstrip("/")).lstrip("/")
+        for endpoint in self.endpoints:
+            endpoint.add_url_prefix(self.url)
+
     def matches_request(self, input_output: InputOutput, allow_partial=True) -> bool:
         """Whether or not we can handle an incoming request based on URL and request method."""
         expected_url = self.url.strip("/")
@@ -303,8 +314,25 @@ class EndpointGroup(
             return self.error(input_output, "Not Found", 404)
 
         self.add_response_headers(input_output)
+
+        # "register" ourself with the DI system
+        current_endpoint_groups = self.di.build_from_name("endpoint_groups", cache=True)
+        current_endpoint_groups.append(self)
+        self.di.add_binding("endpoint_groups", current_endpoint_groups)
+
         return endpoint(input_output)
 
     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 all_endpoints(self) -> list[Endpoint]:
+        """Returns the full (recursive) list of all endpoints associated with this endpoint group"""
+        all_endpoints: list[Endpoint] = []
+        for endpoint in self.endpoints:
+            if hasattr(endpoint, "all_endpoints"):
+                all_endpoints = [*all_endpoints, *endpoint.all_endpoints()]
+            else:
+                all_endpoints.append(endpoint)
+
+        return all_endpoints

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/__init__.py

@@ -6,6 +6,7 @@ from clearskies.endpoints.get import Get
 from clearskies.endpoints.health_check import HealthCheck
 from clearskies.endpoints.list import List
 from clearskies.endpoints.restful_api import RestfulApi
+from clearskies.endpoints.schema import Schema
 from clearskies.endpoints.simple_search import SimpleSearch
 from clearskies.endpoints.update import Update
 
@@ -18,6 +19,7 @@ __all__ = [
     "HealthCheck",
     "List",
     "RestfulApi",
+    "Schema",
     "SimpleSearch",
     "Update",
 ]

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/callable.py

@@ -359,7 +359,7 @@ class Callable(Endpoint):
                 request_methods=self.request_methods,
                 parameters=[
                     *self.documentation_request_parameters(),
-                    *self.standard_url_parameters(),
+                    *self.documentation_url_parameters(),
                 ],
                 root_properties={
                     "security": self.documentation_request_security(),

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/create.py

@@ -155,7 +155,11 @@ class Create(Endpoint):
         )
 
         authentication = self.authentication
-        standard_error_responses = [self.documentation_input_error_response()]
+        # Many swagger UIs will only allow one response per status code, and we use the same status code (200)
+        # for both a success response and an input error response.  This could be fixed by changing the status
+        # code for input error responses, but there's not actually a great HTTP status code for that, so :shrug:
+        # standard_error_responses = [self.documentation_input_error_response()]
+        standard_error_responses = []
         if not getattr(authentication, "is_public", False):
             standard_error_responses.append(self.documentation_access_denied_response())
             if getattr(authentication, "can_authorize", False):
@@ -176,7 +180,7 @@ class Create(Endpoint):
                 request_methods=self.request_methods,
                 parameters=[
                     *self.documentation_request_parameters(),
-                    *self.standard_url_parameters(),
+                    *self.documentation_url_parameters(),
                 ],
                 root_properties={
                     "security": self.documentation_request_security(),
@@ -187,7 +191,6 @@ class Create(Endpoint):
     def documentation_request_parameters(self) -> list[autodoc.request.Parameter]:
         return [
             *self.standard_json_request_parameters(self.model_class),
-            *(self.standard_url_request_parameters() if self.include_routing_data_in_request_data else []),
         ]
 
     def documentation_models(self) -> dict[str, autodoc.schema.Schema]:

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/delete.py

@@ -127,7 +127,7 @@ class Delete(Get):
                 relative_path=self.url,
                 request_methods=self.request_methods,
                 parameters=[
-                    *self.documentation_routing_parameters(),
+                    *self.documentation_url_parameters(),
                 ],
                 root_properties={
                     "security": self.documentation_request_security(),

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/get.py

@@ -231,7 +231,7 @@ class Get(Endpoint):
         )
 
         authentication = self.authentication
-        standard_error_responses = [self.documentation_input_error_response()]
+        standard_error_responses = []
         if not getattr(authentication, "is_public", False):
             standard_error_responses.append(self.documentation_access_denied_response())
             if getattr(authentication, "can_authorize", False):
@@ -251,8 +251,7 @@ class Get(Endpoint):
                 relative_path=self.url,
                 request_methods=self.request_methods,
                 parameters=[
-                    *self.documentation_routing_parameters(),
-                    *self.standard_url_parameters(),
+                    *self.documentation_url_parameters(),
                 ],
                 root_properties={
                     "security": self.documentation_request_security(),
@@ -260,9 +259,6 @@ class Get(Endpoint):
             ),
         ]
 
-    def documentation_routing_parameters(self) -> list[autodoc.request.Parameter]:
-        return self.standard_url_request_parameters()
-
     def documentation_models(self) -> dict[str, autodoc.schema.Schema]:
         output_schema = self.output_schema if self.output_schema else self.model_class
         schema_model_name = string.camel_case_to_snake_case(output_schema.__name__)

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/health_check.py

@@ -162,7 +162,6 @@ class HealthCheck(Endpoint):
 
     def documentation(self) -> list[autodoc.request.Request]:
         output_schema = self.model_class
-        nice_model = string.camel_case_to_words(output_schema.__name__)
         output_autodoc = (autodoc.schema.Object(self.auto_case_internal_column_name("data"), children=[]),)
 
         description = self.description if self.description else "Health Check"
@@ -177,5 +176,8 @@ class HealthCheck(Endpoint):
                 ],
                 relative_path=self.url,
                 request_methods=self.request_methods,
+                parameters=[
+                    *self.documentation_url_parameters(),
+                ],
             ),
         ]

{clear_skies-2.0.2 → clear_skies-2.0.4}/src/clearskies/endpoints/list.py

@@ -476,6 +476,7 @@ class List(Endpoint):
             *self.documentation_url_sort_parameters(),
             *self.documentation_url_search_parameters(),
             *self.documentation_json_search_parameters(),
+            *self.documentation_url_parameters(),
         ]
 
     def documentation_models(self) -> dict[str, autodoc.schema.Schema]: