future-framework 1.1.0__py3-none-any.whl

future/cli/stubs.py

@@ -0,0 +1,114 @@
+# File stubs for make:model / make:controller / make:middleware / make:plugin / make:task / make:seed.
+
+
+from pathlib import Path
+
+
+STUB_KINDS = {
+    "model": {
+        "directory": "app/models",
+        "suffix": "",
+        "template": '''from future.models import Model
+from datetime import datetime
+
+
+class {class_name}(Model):
+    __connection__ = "default"
+    # __table__ = "..."  # optional; otherwise tableized class name
+
+    id: str
+    name: str
+    created_at: datetime
+    updated_at: datetime
+''',
+    },
+    "controller": {
+        "directory": "app/controllers",
+        "suffix": "Controller",
+        "template": '''from future.controllers import Controller
+from future.response import Response
+
+
+class {class_name}(Controller):
+    async def index(self) -> Response:
+        return self.response.json({{"message": "{class_name}"}}, status=200)
+
+    async def show(self, id: str) -> Response:
+        return self.response.json({{"id": id}}, status=200)
+''',
+    },
+    "middleware": {
+        "directory": "app/middleware",
+        "suffix": "Middleware",
+        "template": '''from future.middleware import Middleware
+from future.response import Response
+from typing import Optional
+
+
+class {class_name}(Middleware):
+    name = "{class_name}"
+    priority = 0
+
+    async def before(self) -> Optional[Response]:
+        return None
+
+    async def after(self) -> Optional[Response]:
+        return None
+''',
+    },
+    "plugin": {
+        "directory": "app/plugins",
+        "suffix": "Plugin",
+        "template": '''from future.plugins import Plugin
+
+
+class {class_name}(Plugin):
+    pass
+''',
+    },
+    "task": {
+        "directory": "app/tasks",
+        "suffix": "",
+        "template": '''"""
+{class_name} task — pass to Lifespan cron_tasks via Task(..., func=run).
+"""
+
+
+def run():
+    pass
+''',
+    },
+    "seed": {
+        "directory": "database/seeds",
+        "suffix": "Seeder",
+        "template": '''from future.seeds.Seeder import Seeder
+
+
+class {class_name}(Seeder):
+    def run(self):
+        pass
+''',
+    },
+}
+
+
+class StubMaker:
+    def class_name(self, name, suffix):
+        if suffix and not name.endswith(suffix):
+            return f"{name}{suffix}"
+        return name
+
+    def make(self, kind, name):
+        if kind not in STUB_KINDS:
+            raise ValueError(f"Unknown stub kind: {kind}")
+        config = STUB_KINDS[kind]
+        class_name = self.class_name(name, config["suffix"])
+        directory = Path(config["directory"])
+        if not Path("app").is_dir() and not Path("database").is_dir():
+            raise FileNotFoundError("No app/ or database/ directory found. Run future init first.")
+        directory.mkdir(parents=True, exist_ok=True)
+        path = directory / f"{class_name}.py"
+        if path.exists():
+            raise FileExistsError(f"File already exists: {path}")
+        path.write_text(config["template"].format(class_name=class_name))
+        return str(path)

future/controllers/__init__.py

@@ -0,0 +1,4 @@
+from future.controllers.base import Controller
+from future.controllers.builtins import DebugController, WebSocketController, WelcomeController
+from future.controllers.graphql import GraphQLController
+from future.controllers.openapi import OpenAPIController

future/controllers/base.py

@@ -0,0 +1,8 @@
+from future.request import Request
+from future.response import Response
+
+
+class Controller:
+    def __init__(self, request: Request, response: Response) -> None:
+        self.request = request
+        self.response = response

future/controllers/builtins.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+from future.controllers.base import Controller
+from future.response import Response, WebSocketResponse
+
+
+class DebugController(Controller):
+    async def test(self) -> Response:
+        return self.response.text("lolok")
+
+    async def hello(self) -> Response:
+        return self.response.json({"message": "hi"})
+
+    async def test_data(self, data: Any) -> Response:
+        return self.response.text(f"data: {data}", status=200)
+
+    async def some_handler(self, **params: Any) -> Response:
+        return self.response.text(f"Handled with params: {params}", status=200)
+
+    async def ping(self) -> Response:
+        return self.response.text("Pong\n")
+
+    async def test2(self, data: Any) -> Response:
+        return self.response.text(str(data), status=200)
+
+    async def args(self, user_id: Any, arg2: Any) -> Response:
+        return self.response.text(f"{user_id=}, {arg2=}\n")
+
+
+class WelcomeController(Controller):
+    async def root(self) -> Response:
+        return self.response.text("✨ Welcome to Future! ✨")
+
+
+class WebSocketController(Controller):
+    """Controller for WebSocket endpoints."""
+
+    async def websocket_handler(self, **params: Any) -> WebSocketResponse:
+        """Echo WebSocket: greeting, then duplex Echo: <text> until disconnect."""
+        message = params.get("message", "Hello from WebSocket!")
+        return WebSocketResponse(self.request.receive, message=message)

future/controllers/graphql.py

@@ -0,0 +1,23 @@
+from future.controllers.base import Controller
+from future.graphql.schema import schema as demo_schema
+from future.response import Response
+
+
+class GraphQLController(Controller):
+    async def query(self) -> Response:
+        body = await self.request.json()
+        if not isinstance(body, dict):
+            return self.response.json({"errors": ["JSON body required"]}, status=400)
+        query = body.get("query")
+        if not query or not isinstance(query, str):
+            return self.response.json({"errors": ["query is required"]}, status=400)
+        variables = body.get("variables")
+        operation_name = body.get("operationName")
+        app = self.request.scope.get("app")
+        schema = (app.config.get("GRAPHQL_SCHEMA") if app and app.config else None) or demo_schema
+        result = await schema.execute(query, variable_values=variables, operation_name=operation_name)
+        payload = {"data": result.data}
+        if result.errors:
+            payload["errors"] = [str(error) for error in result.errors]
+            return self.response.json(payload, status=400)
+        return self.response.json(payload)

future/controllers/openapi.py

@@ -0,0 +1,224 @@
+from textwrap import dedent
+import json
+
+from future.controllers.base import Controller
+from future.openapi import get_openapi_config, get_spec, path_prefix
+from future.response import Response
+
+
+class OpenAPIController(Controller):
+    """Controller for OpenAPI documentation endpoints."""
+
+    async def openapi(self) -> Response:
+        """Serve the OpenAPI schema as JSON."""
+        spec = dict(get_spec())
+        scheme = self.request.scheme
+        host = self.request.host
+        port = f":{host.rsplit(':', 1)[1]}" if ":" in host else ""
+        paths = {}
+        for path, entry in (spec.get("paths") or {}).items():
+            item = dict(entry)
+            hosts = item.pop("x-future-hosts", None) or []
+            sub = item.pop("x-future-subdomain", None) or ""
+            if hosts:
+                item["servers"] = [{"url": f"{scheme}://{h}{port}", "description": sub or h} for h in hosts]
+            paths[path] = item
+        spec["paths"] = paths
+        # Scalar Test Request needs document-level servers or the URL bar is blank. List RouteGroup
+        # hosts first (other hosts before the docs Host) so subdomain APIs are the default selection.
+        if "servers" not in spec:
+            servers = []
+            seen = set()
+            for item in paths.values():
+                for server in item.get("servers") or []:
+                    url = server.get("url")
+                    if not url or url in seen:
+                        continue
+                    seen.add(url)
+                    servers.append(dict(server))
+            current = f"{scheme}://{host}"
+            if current not in seen:
+                servers.append({"url": current, "description": "Application"})
+            if not servers:
+                servers = [{"url": current, "description": "Application"}]
+            docs_host = host.rsplit(":", 1)[0] if ":" in host else host
+            other = [s for s in servers if s["url"].split("://", 1)[-1].split("/")[0].rsplit(":", 1)[0] != docs_host]
+            same = [s for s in servers if s["url"].split("://", 1)[-1].split("/")[0].rsplit(":", 1)[0] == docs_host]
+            spec["servers"] = other + same
+        return self.response.json(spec, status=200)
+
+    async def redoc(self) -> Response:
+        """Serve ReDoc HTML (OSS) or Redocly Reference Docs when license_key is set."""
+        spec = f"{path_prefix()}/openapi.json"
+        license_key = (get_openapi_config().get("redocly_license_key") or "").strip()
+        if license_key:
+            # Paid Redocly Reference Docs (includes Try it). Requires a valid license.
+            # https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js
+            key_js = json.dumps(license_key)
+            html = dedent(
+                f"""
+                <!DOCTYPE html>
+                <html>
+                <head>
+                    <title>Redocly Reference</title>
+                    <meta charset="utf-8"/>
+                    <meta name="viewport" content="width=device-width, initial-scale=1">
+                    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+                    <style>body {{ margin: 0; padding: 0; }}</style>
+                </head>
+                <body>
+                    <div id="redocly_container"></div>
+                    <script src="https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js"></script>
+                    <script>
+                        RedoclyReferenceDocs.init(
+                            {json.dumps(spec)},
+                            {{ licenseKey: {key_js} }},
+                            document.querySelector("#redocly_container")
+                        );
+                    </script>
+                </body>
+                </html>
+                """
+            )
+            return self.response.html(html)
+        html = dedent(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>Redoc</title>
+                <meta charset="utf-8"/>
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+                <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+            </head>
+            <body>
+                <redoc spec-url="{spec}"></redoc>
+                <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
+            </body>
+            </html>
+            """
+        )
+        return self.response.html(html)
+
+    async def swagger_config(self) -> Response:
+        """Serve Swagger configuration."""
+        swagger_config = {
+            "apisSorter": "alpha",
+            "operationsSorter": "alpha",
+            "docExpansion": "full",
+        }
+        return self.response.json(swagger_config, status=200)
+
+    async def swagger(self) -> Response:
+        """Serve Swagger UI HTML."""
+        base = path_prefix()
+        html = dedent(
+            f"""
+            <!DOCTYPE html>
+            <html lang="en">
+                <head>
+                    <meta charset="UTF-8">
+                    <meta name="viewport" content="width=device-width, initial-scale=1">
+                    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui.css">
+                    <title>OpenAPI Swagger</title>
+                    <style>
+                        body {{
+                            margin: 0;
+                            padding: 0;
+                        }}
+                    </style>
+                </head>
+                <body>
+                    <div id="openapi"></div>
+                    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui-bundle.js"></script>
+                    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js"></script>
+                    <script>
+                        window.addEventListener("load", function () {{
+                            if (typeof SwaggerUIBundle === "undefined") {{
+                                document.getElementById("openapi").textContent = "Failed to load Swagger UI (CDN blocked or offline).";
+                                return;
+                            }}
+                            SwaggerUIBundle({{
+                                url: "{base}/openapi.json",
+                                dom_id: "#openapi",
+                                configUrl: "{base}/swagger-config",
+                                deepLinking: true,
+                                presets: [
+                                    SwaggerUIBundle.presets.apis,
+                                    SwaggerUIStandalonePreset
+                                ],
+                                plugins: [
+                                    SwaggerUIBundle.plugins.DownloadUrl
+                                ],
+                                layout: "StandaloneLayout"
+                            }});
+                        }});
+                    </script>
+                </body>
+            </html>
+            """
+        )
+        return self.response.html(html)
+
+    async def scalar(self) -> Response:
+        """Serve Scalar API reference HTML."""
+        spec = f"{path_prefix()}/openapi.json"
+        scheme = self.request.scheme
+        host = self.request.host
+        port = f":{host.rsplit(':', 1)[1]}" if ":" in host else ""
+        path_servers = {}
+        for path, entry in (get_spec().get("paths") or {}).items():
+            hosts = entry.get("x-future-hosts") or []
+            if hosts:
+                path_servers[path] = f"{scheme}://{hosts[0]}{port}"
+        html = dedent(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>Scalar API Reference</title>
+                <meta charset="utf-8"/>
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+            </head>
+            <body>
+                <div id="app"></div>
+                <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+                <script>
+                    const pathServers = {json.dumps(path_servers)};
+                    Scalar.createApiReference("#app", {{
+                        url: {json.dumps(spec)},
+                        // Scalar's modal uses the global server; force RouteGroup host for send + URL bar.
+                        onBeforeRequest: ({{ requestBuilder }}) => {{
+                            const base = pathServers[requestBuilder.path.raw];
+                            if (base) {{
+                                requestBuilder.baseUrl = base;
+                            }}
+                        }},
+                    }});
+                </script>
+            </body>
+            </html>
+            """
+        )
+        return self.response.html(html)
+
+    async def rapidoc(self) -> Response:
+        """Serve RapiDoc HTML."""
+        spec = f"{path_prefix()}/openapi.json"
+        html = dedent(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>RapiDoc</title>
+                <meta charset="utf-8"/>
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+                <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+            </head>
+            <body>
+                <rapi-doc spec-url="{spec}" render-style="read" show-header="true" allow-try="true"></rapi-doc>
+            </body>
+            </html>
+            """
+        )
+        return self.response.html(html)

future/databases/Clickhouse.py

@@ -0,0 +1,176 @@
+from future.databases.Database import Database
+
+
+class Clickhouse(Database):
+    def __init__(self, host: str, port: int, username: str, password: str, database: str):
+        super().__init__(host, port, username, password, database)
+        self.client = None
+
+    def connect(self):
+        from clickhouse_driver import Client
+        self.client = Client(host=self.host, port=self.port, user=self.username, password=self.password, database=self.database)
+        return self.client
+
+    def disconnect(self):
+        self.client = None
+
+    def save(self, model):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        data = model.to_dict()
+        doc_id = data.get("id")
+        if doc_id is not None:
+            self.client.execute(f"ALTER TABLE `{table}` DELETE WHERE id = %(id)s", {"id": doc_id})
+        columns = list(data.keys())
+        col_sql = ", ".join(f"`{column}`" for column in columns)
+        self.client.execute(f"INSERT INTO `{table}` ({col_sql}) VALUES", [tuple(data[column] for column in columns)])
+        return {"status": "saved", "table": table, "id": doc_id}
+
+    def find(self, model, id):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        rows, columns = self.client.execute(f"SELECT * FROM `{table}` WHERE id = %(id)s LIMIT 1", {"id": id}, with_column_types=True)
+        if not rows:
+            return None
+        names = [column[0] for column in columns]
+        return model.__class__(**dict(zip(names, rows[0], strict=True)))
+
+    def all(self, model):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        rows, columns = self.client.execute(f"SELECT * FROM `{table}`", with_column_types=True)
+        names = [column[0] for column in columns]
+        return [model.__class__(**dict(zip(names, row, strict=True))) for row in rows]
+
+    def get(self, model, wheres, limit=None, orders=None):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        clauses = []
+        params = {}
+        for index, (column, operator, value) in enumerate(wheres):
+            if operator == "in":
+                values = list(value)
+                if not values:
+                    return []
+                keys = []
+                for item_index, item in enumerate(values):
+                    key = f"v{index}_{item_index}"
+                    keys.append(f"%({key})s")
+                    params[key] = item
+                clauses.append(f"`{column}` IN ({', '.join(keys)})")
+                continue
+            if operator == "like":
+                key = f"v{index}"
+                clauses.append(f"`{column}` LIKE %({key})s")
+                params[key] = value
+                continue
+            if operator not in ("=", ">", ">=", "<", "<=", "!="):
+                raise ValueError(f"Unsupported operator: {operator}")
+            key = f"v{index}"
+            clauses.append(f"`{column}` {operator} %({key})s")
+            params[key] = value
+        sql = f"SELECT * FROM `{table}`"
+        if clauses:
+            sql += f" WHERE {' AND '.join(clauses)}"
+        if orders:
+            sql += " ORDER BY " + ", ".join(f"`{column}` {direction}" for column, direction in orders)
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+        rows, columns = self.client.execute(sql, params, with_column_types=True)
+        names = [column[0] for column in columns]
+        return [model.__class__(**dict(zip(names, row, strict=True))) for row in rows]
+
+    def delete(self, model):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        doc_id = getattr(model, "id", None)
+        self.client.execute(f"ALTER TABLE `{table}` DELETE WHERE id = %(id)s", {"id": doc_id})
+        return {"status": "deleted", "table": table, "id": doc_id}
+
+    def update(self, model, changes):
+        if self.client is None:
+            self.connect()
+        table = model.tableize()
+        doc_id = getattr(model, "id", None)
+        if not changes:
+            return {"status": "noop", "table": table, "id": doc_id}
+        set_sql = ", ".join(f"`{column}` = %({column})s" for column in changes.keys())
+        params = dict(changes)
+        params["id"] = doc_id
+        self.client.execute(f"ALTER TABLE `{table}` UPDATE {set_sql} WHERE id = %(id)s", params)
+        return {"status": "updated", "table": table, "id": doc_id}
+
+    def schema_create(self, blueprint):
+        if self.client is None:
+            self.connect()
+        definitions = []
+        order_by = "tuple()"
+        for column in blueprint.columns:
+            if column.type == "string":
+                ch_type = "String"
+            elif column.type == "text":
+                ch_type = "String"
+            elif column.type == "integer":
+                ch_type = "Int64"
+            elif column.type == "float":
+                ch_type = "Float64"
+            elif column.type == "boolean":
+                ch_type = "UInt8"
+            elif column.type == "datetime":
+                ch_type = "DateTime"
+            else:
+                raise ValueError(f"Unsupported column type: {column.type}")
+            if column.is_nullable:
+                ch_type = f"Nullable({ch_type})"
+            definitions.append(f"`{column.name}` {ch_type}")
+            if column.is_primary:
+                order_by = f"`{column.name}`"
+        create_sql = f"CREATE TABLE IF NOT EXISTS `{blueprint.name}` ({', '.join(definitions)}) ENGINE = MergeTree() ORDER BY {order_by}"
+        self.client.execute(create_sql)
+        return {"status": "created", "table": blueprint.name}
+
+    def schema_drop(self, name):
+        if self.client is None:
+            self.connect()
+        self.client.execute(f"DROP TABLE IF EXISTS `{name}`")
+        return {"status": "dropped", "table": name}
+
+    def migrations_get(self):
+        if self.client is None:
+            self.connect()
+        self.client.execute("CREATE TABLE IF NOT EXISTS `migrations` (`name` String, `batch` Int32) ENGINE = MergeTree() ORDER BY (`batch`, `name`)")
+        rows = self.client.execute("SELECT name FROM migrations ORDER BY batch, name")
+        return [row[0] for row in rows]
+
+    def migrations_put(self, name, batch):
+        if self.client is None:
+            self.connect()
+        self.client.execute("CREATE TABLE IF NOT EXISTS `migrations` (`name` String, `batch` Int32) ENGINE = MergeTree() ORDER BY (`batch`, `name`)")
+        self.client.execute("INSERT INTO migrations (name, batch) VALUES", [(name, batch)])
+
+    def migrations_delete(self, name):
+        if self.client is None:
+            self.connect()
+        self.client.execute("ALTER TABLE migrations DELETE WHERE name = %(name)s", {"name": name})
+
+    def migrations_max_batch(self):
+        if self.client is None:
+            self.connect()
+        self.client.execute("CREATE TABLE IF NOT EXISTS `migrations` (`name` String, `batch` Int32) ENGINE = MergeTree() ORDER BY (`batch`, `name`)")
+        rows = self.client.execute("SELECT max(batch) FROM migrations")
+        if not rows or rows[0][0] is None:
+            return 0
+        return int(rows[0][0])
+
+    def migrations_batch_for(self, name):
+        if self.client is None:
+            self.connect()
+        rows = self.client.execute("SELECT batch FROM migrations WHERE name = %(name)s", {"name": name})
+        if not rows:
+            return None
+        return int(rows[0][0])

future/databases/Connections.py

@@ -0,0 +1,20 @@
+# Named connection registry (Masonite-style logic).
+# App config: DB = Connections().set_connection_details(DATABASES)
+# Models: Connections().get_connection(name)
+
+
+class Connections:
+    _connections = {}
+    _default = None
+
+    def set_connection_details(self, databases):
+        self.__class__._default = databases["default"]
+        self.__class__._connections = {name: connection for name, connection in databases.items() if name != "default"}
+        return self
+
+    def get_connection(self, name="default"):
+        if name == "default":
+            name = self.__class__._default
+        if not name or name not in self.__class__._connections:
+            raise RuntimeError("No database connections registered. Pass DATABASES in Future(config={...}) or call Connections().set_connection_details(DATABASES).")
+        return self.__class__._connections[name]

future/databases/Database.py

@@ -0,0 +1,66 @@
+# Interface for all database types (MySQL, Elasticsearch, Clickhouse, Redis, etc.).
+# Concrete databases implement these with their own storage primitives
+# (tables, indices, keys, ...). Model only calls these names.
+
+
+class Database:
+    def __init__(self, host: str, port: int, username: str, password: str, database: str):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.database = database
+
+    def connect(self):
+        raise NotImplementedError
+
+    def disconnect(self):
+        raise NotImplementedError
+
+    def save(self, model):
+        raise NotImplementedError
+
+    def find(self, model, id):
+        raise NotImplementedError
+
+    def all(self, model):
+        raise NotImplementedError
+
+    def get(self, model, wheres, limit=None, orders=None):
+        raise NotImplementedError
+
+    def delete(self, model):
+        raise NotImplementedError
+
+    def update(self, model, changes):
+        raise NotImplementedError
+
+    def schema_create(self, blueprint):
+        raise NotImplementedError
+
+    def schema_drop(self, name):
+        raise NotImplementedError
+
+    def migrations_get(self):
+        raise NotImplementedError
+
+    def migrations_put(self, name, batch):
+        raise NotImplementedError
+
+    def migrations_delete(self, name):
+        raise NotImplementedError
+
+    def migrations_max_batch(self):
+        raise NotImplementedError
+
+    def migrations_batch_for(self, name):
+        raise NotImplementedError
+
+    def transaction(self):
+        client = getattr(self, "client", None)
+        if client is None:
+            self.connect()
+            client = getattr(self, "client", None)
+        if client is None or not hasattr(client, "begin"):
+            raise NotImplementedError(f"{type(self).__name__} does not support transactions")
+        return client.begin()