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

clearskies/autodoc/formats/oai3_json/schema/object.py

@@ -1,10 +1,19 @@
+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):
-        schema = {
+        schema: dict[str, Any] = {
             "type": "object",
         }
 

clearskies/autodoc/request/__init__.py

@@ -1,5 +1,6 @@
 from .header import Header
 from .json_body import JSONBody
+from .parameter import Parameter
 from .request import Request
 from .url_parameter import URLParameter
 from .url_path import URLPath
@@ -7,6 +8,7 @@ from .url_path import URLPath
 __all__ = [
     "Header",
     "JSONBody",
+    "Parameter",
     "Request",
     "URLParameter",
     "URLPath",

clearskies/autodoc/request/header.py

@@ -1,8 +1,6 @@
-class Header:
+from .parameter import Parameter
+
+
+class Header(Parameter):
     location = "header"
     in_body = False
-
-    def __init__(self, definition, description="", required=False):
-        self.definition = definition
-        self.description = description
-        self.required = required

clearskies/autodoc/request/json_body.py

@@ -1,8 +1,6 @@
-class JSONBody:
+from .parameter import Parameter
+
+
+class JSONBody(Parameter):
     location = "json_body"
     in_body = True
-
-    def __init__(self, definition, description="", required=False):
-        self.definition = definition
-        self.description = description
-        self.required = required

clearskies/autodoc/request/parameter.py

@@ -0,0 +1,8 @@
+class Parameter:
+    location = ""
+    in_body = False
+
+    def __init__(self, definition, description="", required=False):
+        self.definition = definition
+        self.description = description
+        self.required = required

clearskies/autodoc/request/request.py

@@ -1,14 +1,26 @@
+import re
+from typing import Any
+
+
 class Request:
-    description = None
-    relative_path = None
-    request_methods = None
-    parameters = None
+    description: str = ""
+    relative_path: str = ""
+    request_methods: list[str] = []
+    parameters: list[Any] = []
     responses = None
     root_properties = None
 
     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("/")

clearskies/autodoc/request/url_parameter.py

@@ -1,8 +1,6 @@
-class URLParameter:
+from .parameter import Parameter
+
+
+class URLParameter(Parameter):
     location = "url_parameter"
     in_body = False
-
-    def __init__(self, definition, description="", required=False):
-        self.definition = definition
-        self.description = description
-        self.required = required

clearskies/autodoc/request/url_path.py

@@ -1,8 +1,6 @@
-class URLPath:
+from .parameter import Parameter
+
+
+class URLPath(Parameter):
     location = "url_path"
     in_body = False
-
-    def __init__(self, definition, description="", required=False):
-        self.definition = definition
-        self.description = description
-        self.required = required

clearskies/autodoc/schema/__init__.py

@@ -2,7 +2,7 @@ from .array import Array
 from .base64 import Base64
 from .boolean import Boolean
 from .date import Date
-from .datetime import DateTime
+from .datetime import Datetime
 from .double import Double
 from .enum import Enum
 from .integer import Integer
@@ -10,6 +10,7 @@ from .long import Long
 from .number import Number
 from .object import Object
 from .password import Password
+from .schema import Schema
 from .string import String
 
 __all__ = [
@@ -17,7 +18,7 @@ __all__ = [
     "Base64",
     "Boolean",
     "Date",
-    "DateTime",
+    "Datetime",
     "Double",
     "Enum",
     "Integer",
@@ -25,5 +26,6 @@ __all__ = [
     "Number",
     "Object",
     "Password",
+    "Schema",
     "String",
 ]

clearskies/autodoc/schema/array.py

@@ -1,11 +1,10 @@
-class Array:
-    name = None
-    value = None
+from .schema import Schema
+
+
+class Array(Schema):
     item_definition = None
     _type = "array"
-    _format = ""
 
     def __init__(self, name, item_definition, value=None):
-        self.name = name
-        self.value = value
+        super().__init__(name, example=None, value=value)
         self.item_definition = item_definition

clearskies/autodoc/schema/boolean.py

@@ -1,11 +1,5 @@
-class Boolean:
-    name = None
-    example = None
-    value = None
-    _type = "boolean"
-    _format = ""
+from .schema import Schema
+
 
-    def __init__(self, name, example=None, value=None):
-        self.name = name
-        self.example = example
-        self.value = value
+class Boolean(Schema):
+    _type = "boolean"

clearskies/autodoc/schema/date.py

@@ -3,6 +3,3 @@ from .string import String
 
 class Date(String):
     _format = "date"
-
-    def __init__(self, name, example=None, value=None):
-        super().__init__(name, example=example, value=value)

clearskies/autodoc/schema/datetime.py

@@ -1,8 +1,5 @@
 from .string import String
 
 
-class DateTime(String):
+class Datetime(String):
     _format = "date-time"
-
-    def __init__(self, name, example=None, value=None):
-        super().__init__(name, example=example, value=value)

clearskies/autodoc/schema/double.py

@@ -3,6 +3,3 @@ from .number import Number
 
 class Double(Number):
     _format = "double"
-
-    def __init__(self, name, example=None, value=None):
-        super().__init__(name, example=example, value=value)

clearskies/autodoc/schema/enum.py

@@ -1,5 +1,7 @@
-class Enum:
-    name = None
+from .schema import Schema
+
+
+class Enum(Schema):
     values = None
     value_type = None
     example = None

clearskies/autodoc/schema/integer.py

@@ -1,11 +1,6 @@
-class Integer:
-    name = None
-    example = None
-    value = None
+from .schema import Schema
+
+
+class Integer(Schema):
     _type = "integer"
     _format = "int32"
-
-    def __init__(self, name, example=None, value=None):
-        self.name = name
-        self.example = example
-        self.value = value

clearskies/autodoc/schema/long.py

@@ -3,6 +3,3 @@ from .integer import Integer
 
 class Long(Integer):
     _format = "int64"
-
-    def __init__(self, name, example=None, value=None):
-        super().__init__(name, example=example, value=value)

clearskies/autodoc/schema/number.py

@@ -1,11 +1,6 @@
-class Number:
-    name = None
-    example = None
-    value = None
+from .schema import Schema
+
+
+class Number(Schema):
     _type = "number"
     _format = "float"
-
-    def __init__(self, name, example=None, value=None):
-        self.name = name
-        self.example = example
-        self.value = value

clearskies/autodoc/schema/object.py

@@ -1,15 +1,13 @@
-class Object:
-    name = None
+from .schema import Schema
+
+
+class Object(Schema):
     children = None
-    value = None
-    example = None
     model_name = None
     _type = "object"
     _format = ""
 
     def __init__(self, name, children, value=None, example=None, model_name=None):
-        self.name = name
+        super().__init__(name, example=example, value=value)
         self.children = children
-        self.value = value
-        self.example = example
         self.model_name = model_name

clearskies/autodoc/schema/password.py

@@ -3,6 +3,3 @@ from .string import String
 
 class Password(String):
     _format = "password"
-
-    def __init__(self, name, example=None, value=None):
-        super().__init__(name, example=example, value=value)

clearskies/autodoc/schema/schema.py

@@ -0,0 +1,11 @@
+class Schema:
+    name: str
+    example = None
+    value = None
+    _type = "string"
+    _format = ""
+
+    def __init__(self, name, example=None, value=None):
+        self.name = name
+        self.example = example
+        self.value = value

clearskies/autodoc/schema/string.py

@@ -1,11 +1,5 @@
-class String:
-    name = None
-    example = None
-    value = None
-    _type = "string"
-    _format = ""
+from .schema import Schema
 
-    def __init__(self, name, example=None, value=None):
-        self.name = name
-        self.example = example
-        self.value = value
+
+class String(Schema):
+    pass

clearskies/backends/__init__.py

@@ -1,26 +1,65 @@
-from .. import binding_config
-from .api_backend import ApiBackend
-from .cursor_backend import CursorBackend
-from .example_backend import ExampleBackend
-from .file_backend import FileBackend
-from .json_backend import JsonBackend
-from .memory_backend import MemoryBackend
-from .restful_api_advanced_search_backend import RestfulApiAdvancedSearchBackend
-from .secrets_backend import SecretsBackend
+"""
+The backend system provides a layer of abstraction between a clearskies model and the place where it stores its data.
 
+## Motivation
 
-def example_backend(data):
-    return binding_config.BindingConfig(ExampleBackend, data=data)
+The goal of the backend system is to create a standard way to interact with external systems, whether those are
+databases, APIs, cloud resources, etc...  For comparison, models in other frameworks typically interact exclusively
+with SQL databases.  Therefore, building integrations with other data stores or 3rd party systems requires the
+creation of bespoke SDKs, which results in time spent integrating and learning how to use them.  Clearskies models
+work with different backends to normalize the process of integrating with data stores and external systems.
+This ability to switch backends turns the models, in essence, into a standardized SDK.  The details of how to
+interact with some other system are abstracted away into the backend, and then developers can interact with the
+system using models in the standard way.
+
+Of course, no abstraction layer is perfect, and not all datastores can fit into the backend system provided by
+clearskies.  That's okay!  Like every abstraction layer in clearskies, you should use it when it works for
+you and forget about it otherwise.  So, for instance, it is not possible to build arbitrarily complex SQL
+queries with the query system provided by models, but you can always inject the cursor and use it directly.
+If some arbitrary data store just works in a completely different way, such that the backend system doesn't
+work for it, it's still fine to build an SDK the "old school" way and use it in a clearskies application.
+
+## Backends
+
+There are four primary kinds of backends built into clearskies, with a few sub-types.  Those are:
+
+ 1. CursorBackend: Store data in an SQL-like database
+ 2. MemoryBackend: Store data in-memory
+ 3. ApiBackend: Use an API to fetch and store data
+    1. ApiGetOnlyBackend: Only supports fetching individual records from the API by id.
+    2. RestfulApiAdvancedSearchBackend: Automatically integrates with APIs built using clearskies.endpoints.RestfulApi
+ 4. SecretsBackend - Store data directly in a secrets manager
+
+See the documentation for each backend to understand how to configure and use it.  In all cases though, you specify
+the backend by instantiating the backend and attaching it to the model class via the `backend` attribute:
+
+```python
+import clearskies
+
+
+class MyModel(clearskies.model):
+    backend = clearskies.backends.MemoryBackend()
+```
+"""
+
+# from .api_backend import ApiBackend
+# from .api_get_only_backend import ApiGetOnlyBackend
+from clearskies.backends.api_backend import ApiBackend
+from clearskies.backends.backend import Backend
+from clearskies.backends.cursor_backend import CursorBackend
+from clearskies.backends.memory_backend import MemoryBackend
+
+# from .memory_backend import MemoryBackend
+# from .restful_api_advanced_search_backend import RestfulApiAdvancedSearchBackend
+# from .secrets_backend import SecretsBackend
 
 
 __all__ = [
     "ApiBackend",
+    # "ApiGetOnlyBackend",
+    "Backend",
     "CursorBackend",
-    "ExampleBackend",
-    "example_backend",
-    "FileBackend",
-    "JsonBackend",
     "MemoryBackend",
-    "RestfulApiAdvancedSearchBackend",
-    "SecretsBackend",
+    # "RestfulApiAdvancedSearchBackend",
+    # "SecretsBackend",
 ]