future-framework 1.1.0__py3-none-any.whl

future/settings.py

@@ -0,0 +1,94 @@
+from os import environ as env
+
+from dotenv import load_dotenv
+
+
+load_dotenv(dotenv_path=".env")  # FIXME: dotenv not used correctly. Shouldn't need both os.environ and dotenv...
+# os.environ["APP_ENV"] = "dev"
+# port = int(os.environ.get("APP_PORT", 44777))
+
+
+# Application settings sourced from .env
+APP_NAME = str(env.get("APP_NAME", "Future"))
+APP_VERSION = str(env.get("APP_VERSION", "1.0"))
+APP_DESCRIPTION = str(env.get("APP_DESCRIPTION", "A short description"))
+APP_DEBUG = env.get("APP_DEBUG", "False").lower() == "true"
+APP_LOG_LEVEL = str("DEBUG" if APP_DEBUG else env.get("APP_LOG_LEVEL", "INFO"))
+APP_ACCESS_LOG = env.get("APP_ACCESS_LOG", "False").lower() == "true"
+APP_WORKERS = int(env.get("APP_WORKERS", 4))
+APP_HOST = str(env.get("APP_HOST", "127.0.0.1"))
+APP_PORT = int(env.get("APP_PORT", 9000))
+APP_SSO = env.get("APP_SSO", "False").lower() == "true"
+APP_KEY = str(env.get("APP_KEY", "secret"))  # os.urandom(24)  # TODO: add to cli --generate
+APP_REGISTRATION = env.get("APP_REGISTRATION", "False").lower() == "true"
+APP_SSL_CERT_FILE = str(env.get("APP_SSL_CERT_FILE", "./cert.pem"))
+APP_SSL_KEY_FILE = str(env.get("APP_SSL_KEY_FILE", "./key.pem"))
+APP_SSL_PASSPHRASE = str(env.get("APP_SSL_PASSPHRASE", "changeme"))
+APP_DOMAIN = str(env.get("APP_DOMAIN", "example.com"))
+
+# Database settings sourced from .env
+DB_DRIVER = str(env.get("DB_DRIVER", "sqlite"))
+DB_HOST = str(env.get("DB_HOST", "127.0.0.1"))
+DB_PORT = int(env.get("DB_PORT", 3306))
+DB_DATABASE = str(env.get("DB_DATABASE", "database"))
+DB_USERNAME = str(env.get("DB_USERNAME", ""))
+DB_PASSWORD = str(env.get("DB_PASSWORD", ""))
+DB_LOGGING = str(env.get("DB_LOGGING", True))
+DB_OPTIONS = str(env.get("DB_OPTIONS", None))
+
+# Elasticsearch settings sourced from .env
+ELASTIC_HOST = str(env.get("ELASTIC_HOST", "127.0.0.1"))
+ELASTIC_PORT = int(env.get("ELASTIC_PORT", 9200))
+ELASTIC_USER = str(env.get("ELASTIC_USER", None))
+ELASTIC_PASS = str(env.get("ELASTIC_PASS", None))
+
+# API Spec is built by Future from registered routes when OPENAPI.enabled is True.
+# See config["OPENAPI"] and future.openapi.openapi_routes().
+API_SPEC = {
+    "openapi": "3.0.0",  # Updated to 3.0.0 for better compatibility
+    "info": {
+        "title": APP_NAME,
+        "version": APP_VERSION,
+        "description": APP_DESCRIPTION,
+    },
+    "paths": {},
+    # "servers": [
+    #    {
+    #        "url": APP_DOMAIN,
+    #         "description": "Development server"
+    #     }
+    # ]
+}
+
+# Logging configuration
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "colored": {
+            "format": "%(message)s",
+        }
+    },
+    "handlers": {
+        "stdout": {
+            "class": "logging.StreamHandler",
+            "level": APP_LOG_LEVEL,
+            "formatter": "colored",
+            "stream": "ext://sys.stdout",
+        },
+        "queue_handler": {
+            "class": "logging.handlers.QueueHandler",
+            "handlers": [
+                "stdout",
+            ],
+            "respect_handler_level": True,
+        },
+    },
+    "loggers": {
+        "future": {
+            "level": APP_LOG_LEVEL,
+            "handlers": ["queue_handler"],
+            "propagate": False,
+        }
+    },
+}

future/tasks/__init__.py

@@ -0,0 +1,14 @@
+from future.tasks.scheduler import (
+    CronScheduler,
+    ScheduledTask,
+    Task,
+    Unit,
+    check_disk_usage,
+    check_dns,
+    check_http_status,
+    check_memory_usage,
+    check_ssh_banner,
+    check_system_uptime,
+    daily_backup,
+    sync_task_example,
+)

future/tasks/scheduler.py

@@ -0,0 +1,267 @@
+import asyncio
+import random
+
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Callable, Optional
+
+from future.logger import log
+
+
+class Unit(Enum):
+    SECONDS = "seconds"
+    MINUTES = "minutes"
+    HOURS = "hours"
+    DAYS = "days"
+
+
+class Task:
+    def __init__(
+        self,
+        name: str,
+        interval: Optional[int] = None,
+        unit: Optional[Unit] = None,
+        start_time: Optional[datetime] = None,
+        kwargs: Optional[dict[str, Any]] = None,
+        func: Optional[Callable[..., Any]] = None,
+        args: tuple[Any, ...] = (),
+        jitter: Optional[float] = None,
+    ) -> None:
+        self.name = name
+        self.interval = interval
+        self.unit = unit
+        self.start_time = start_time
+        self.kwargs = kwargs or {}
+        self.func = func
+        self.args = args
+        self.jitter = jitter
+
+
+class ScheduledTask:
+    """Represents a scheduled task with its timing configuration."""
+
+    def __init__(
+        self,
+        name: str,
+        func: Callable[..., Any],
+        interval: int,
+        unit: Unit,
+        start_time: Optional[datetime] = None,
+        last_run: Optional[datetime] = None,
+        next_run: Optional[datetime] = None,
+        args: tuple[Any, ...] = (),
+        kwargs: Optional[dict[str, Any]] = None,
+        jitter: Optional[float] = None,
+    ) -> None:
+        self.name = name
+        self.func = func
+        self.interval = interval
+        self.unit = unit
+        self.start_time = start_time
+        self.last_run = last_run
+        self.next_run = next_run
+        self.args = args
+        self.kwargs = kwargs if kwargs is not None else {}
+        self.jitter = jitter
+
+        if self.start_time is None:
+            self.start_time = datetime.now()
+        self.calculate_next_run()
+
+    def calculate_next_run(self) -> None:
+        """Calculate when this task should run next."""
+        if self.last_run is None:
+            self.next_run = self.start_time
+        else:
+            if self.unit == Unit.SECONDS:
+                self.next_run = self.last_run + timedelta(seconds=self.interval)
+            elif self.unit == Unit.MINUTES:
+                self.next_run = self.last_run + timedelta(minutes=self.interval)
+            elif self.unit == Unit.HOURS:
+                self.next_run = self.last_run + timedelta(hours=self.interval)
+            elif self.unit == Unit.DAYS:
+                self.next_run = self.last_run + timedelta(days=self.interval)
+        if self.next_run is not None and self.jitter and self.jitter > 0:
+            self.next_run = self.next_run + timedelta(seconds=random.uniform(0, self.jitter))
+
+
+class CronScheduler:
+    """A cron-like scheduler for running background tasks."""
+
+    def __init__(self) -> None:
+        self.tasks: dict[str, ScheduledTask] = {}
+        self.running = False
+        self.check_interval = 1.0  # Check every second for tasks to run
+
+    def add_task(self, task: Task) -> None:
+        if task.func is None or task.interval is None or task.unit is None:
+            log.warning(f"Skipping task '{task.name}' - missing required parameters")
+            return
+
+        scheduled = ScheduledTask(
+            name=task.name,
+            func=task.func,
+            interval=task.interval,
+            unit=task.unit,
+            start_time=task.start_time,
+            args=task.args,
+            kwargs=task.kwargs,
+            jitter=task.jitter,
+        )
+        self.tasks[task.name] = scheduled
+        jitter_note = f" (jitter 0–{task.jitter}s)" if task.jitter else ""
+        log.info(f"Added scheduled task '{task.name}' to run every {task.interval} {task.unit.value}{jitter_note}")
+
+    def remove_task(self, name: str) -> bool:
+        """Remove a scheduled task."""
+        if name in self.tasks:
+            del self.tasks[name]
+            log.info(f"Removed scheduled task '{name}'")
+            return True
+        return False
+
+    def get_task(self, name: str) -> Optional[ScheduledTask]:
+        """Get a scheduled task by name."""
+        return self.tasks.get(name)
+
+    def list_tasks(self) -> list[str]:
+        """List all scheduled task names."""
+        return list(self.tasks.keys())
+
+    async def _run_task(self, task: ScheduledTask) -> None:
+        """Run a single task."""
+        try:
+            log.debug(f"Running scheduled task '{task.name}'")
+            if asyncio.iscoroutinefunction(task.func):
+                # Run async functions directly
+                await task.func(*task.args, **task.kwargs)
+            else:
+                # Run sync functions in thread pool
+                loop = asyncio.get_event_loop()
+                await loop.run_in_executor(None, task.func, *task.args, **task.kwargs)
+
+            task.last_run = datetime.now()
+            task.calculate_next_run()
+            if task.next_run:
+                log.debug(f"Completed scheduled task '{task.name}', next run at {task.next_run.strftime('%Y-%m-%d %H:%M:%S')}")
+            else:
+                log.debug(f"Completed scheduled task '{task.name}'")
+
+        except Exception as e:
+            log.error(f"Error running scheduled task '{task.name}': {e}")
+            # Don't update last_run on error, so it will retry next cycle
+
+    async def _scheduler_loop(self) -> None:
+        """Main scheduler loop that checks for tasks to run."""
+        log.info("Starting cron scheduler...")
+
+        while self.running:
+            now = datetime.now()
+            tasks_to_run = []
+
+            # Check which tasks need to run
+            for task in self.tasks.values():
+                if task.next_run and now >= task.next_run:
+                    tasks_to_run.append(task)
+
+            # Run tasks that are due
+            if tasks_to_run:
+                log.debug(f"Running {len(tasks_to_run)} scheduled tasks")
+                for task in tasks_to_run:
+                    asyncio.create_task(self._run_task(task))
+
+            # Wait before next check
+            await asyncio.sleep(self.check_interval)
+
+        log.info("Cron scheduler stopped")
+
+    async def start(self) -> None:
+        """Start the scheduler."""
+        if not self.running:
+            self.running = True
+            asyncio.create_task(self._scheduler_loop())
+
+    async def stop(self) -> None:
+        """Stop the scheduler."""
+        self.running = False
+
+
+# --- Minimal cron task functions ---
+async def check_dns(domain: str = "example.com") -> None:
+    import socket
+
+    try:
+        ip = socket.gethostbyname(domain)
+        log.info(f"DNS: {domain} -> {ip}")
+    except socket.gaierror as e:
+        log.error(f"DNS lookup failed for {domain}: {e}")
+
+
+async def check_http_status(url: str = "https://httpbin.org/status/200") -> None:
+    import httpx
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            log.info(f"HTTP: {url} -> {response.status_code}")
+    except Exception as e:
+        log.error(f"HTTP check failed for {url}: {e}")
+
+
+async def check_ssh_banner(host: str = "localhost", port: int = 22) -> None:
+    try:
+        reader, writer = await asyncio.open_connection(host, port)
+        banner = await reader.read(1024)
+        log.info(f"SSH banner for {host}:{port}: {banner.decode(errors='ignore').strip()}")
+        writer.close()
+        await writer.wait_closed()
+    except Exception as e:
+        log.error(f"SSH banner check failed for {host}:{port}: {e}")
+
+
+def check_system_uptime() -> None:
+    import subprocess
+
+    try:
+        result = subprocess.run(["uptime"], capture_output=True, text=True, timeout=5.0)
+        if result.returncode == 0:
+            log.info(f"System uptime: {result.stdout.strip()}")
+        else:
+            log.error(f"Uptime command failed: {result.stderr}")
+    except subprocess.TimeoutExpired:
+        log.error("Uptime command timed out")
+    except Exception as e:
+        log.error(f"Error checking system uptime: {e}")
+
+
+def check_disk_usage(path: str = "/") -> None:
+    import shutil
+
+    try:
+        total, used, _ = shutil.disk_usage(path)
+        used_percent = (used / total) * 100
+        log.info(f"Disk usage for {path}: {used_percent:.1f}% used ({used // (1024**3)}GB / {total // (1024**3)}GB)")
+    except Exception as e:
+        log.error(f"Error checking disk usage for {path}: {e}")
+
+
+def check_memory_usage() -> None:
+    import psutil
+
+    try:
+        memory = psutil.virtual_memory()
+        log.info(f"Memory usage: {memory.percent}% used ({memory.used // (1024**3)}GB / {memory.total // (1024**3)}GB)")
+    except ImportError:
+        log.warning("psutil not available, skipping memory check")
+    except Exception as e:
+        log.error(f"Error checking memory usage: {e}")
+
+
+def sync_task_example() -> None:
+    log.info(f"Running sync task at {datetime.now()}")
+
+
+async def daily_backup() -> None:
+    log.info(f"Running daily backup at {datetime.now()}")
+    # TODO: Implement actual backup logic
+    # Example: backup database, files, etc.

future/testing/__init__.py

@@ -0,0 +1 @@
+from future.testing.client import FutureTestClient

future/testing/client.py

@@ -0,0 +1,135 @@
+from typing import Any
+from urllib.parse import urlparse
+
+import asyncio
+import httpx
+
+from future.application import Future
+
+
+class FutureTestClient:
+    def __init__(self, app: Future) -> None:
+        self.app = app
+        self.transport = httpx.ASGITransport(app=self.app)
+        self.client = httpx.AsyncClient(transport=self.transport)
+
+    async def __aenter__(self) -> "FutureTestClient":
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.client.__aexit__(exc_type, exc, tb)
+
+    async def get(self, url: str, headers: dict[str, str] | None = None) -> httpx.Response:
+        response = await self.client.get(url, headers=headers)
+        return response
+
+    async def post(self, url: str, json: dict[str, Any] | None = None, data: str | bytes | None = None, headers: dict[str, str] | None = None) -> httpx.Response:
+        if json is not None:
+            response = await self.client.post(url, json=json, headers=headers)
+        elif data is not None:
+            response = await self.client.post(url, content=data, headers=headers)
+        else:
+            response = await self.client.post(url, headers=headers)
+        return response
+
+    async def websocket_connect(self, url: str, headers: dict[str, str] | None = None) -> Any:
+        """Connect via real ASGI websocket handshake against the Future app."""
+        parsed = urlparse(url)
+        path = parsed.path
+        if parsed.query:
+            path += "?" + parsed.query
+
+        ws_headers = []
+        if headers:
+            for key, value in headers.items():
+                ws_headers.append((key.lower().encode(), value.encode()))
+
+        scope = {
+            "type": "websocket",
+            "asgi": {"version": "3.0", "spec_version": "2.3"},
+            "path": path,
+            "headers": ws_headers,
+            "raw_path": path.encode(),
+            "query_string": b"",
+            "client": ("127.0.0.1", 12345),
+            "server": ("127.0.0.1", 8000),
+            "scheme": "ws",
+            "root_path": "",
+            "subprotocols": [],
+            "extensions": {},
+            "state": {},
+        }
+
+        send_queue: asyncio.Queue = asyncio.Queue()
+        recv_queue: asyncio.Queue = asyncio.Queue()
+        await recv_queue.put({"type": "websocket.connect"})
+
+        async def receive() -> dict[str, Any]:
+            return await recv_queue.get()
+
+        async def send(message: dict[str, Any]) -> None:
+            await send_queue.put(message)
+
+        task = asyncio.create_task(self.app(scope, receive, send))
+
+        class AsgiWebSocket:
+            def __init__(self) -> None:
+                self.accepted = False
+                self.closed = False
+                self.close_code = None
+                self.close_reason = None
+                self._task = task
+
+            async def _next_server_message(self) -> dict[str, Any]:
+                while True:
+                    try:
+                        return await asyncio.wait_for(send_queue.get(), timeout=2.0)
+                    except asyncio.TimeoutError:
+                        if self._task.done():
+                            exc = self._task.exception()
+                            if exc:
+                                raise exc
+                            raise TimeoutError("WebSocket app ended without a message")
+                        raise
+
+            async def wait_accepted(self) -> None:
+                message = await self._next_server_message()
+                if message["type"] == "websocket.close":
+                    self.closed = True
+                    self.close_code = message.get("code")
+                    self.close_reason = message.get("reason")
+                    raise ConnectionError(f"WebSocket closed: {self.close_code} {self.close_reason}")
+                if message["type"] != "websocket.accept":
+                    raise AssertionError(f"Expected websocket.accept, got {message}")
+                self.accepted = True
+
+            async def send(self, message: str) -> None:
+                await recv_queue.put({"type": "websocket.receive", "text": message})
+
+            async def recv(self) -> str:
+                message = await self._next_server_message()
+                if message["type"] == "websocket.send":
+                    if "text" in message:
+                        return message["text"]
+                    return message.get("bytes", b"").decode("utf-8")
+                if message["type"] == "websocket.close":
+                    self.closed = True
+                    self.close_code = message.get("code")
+                    self.close_reason = message.get("reason")
+                    raise ConnectionError(f"WebSocket closed: {self.close_code} {self.close_reason}")
+                raise AssertionError(f"Unexpected message: {message}")
+
+            async def close(self) -> None:
+                await recv_queue.put({"type": "websocket.disconnect", "code": 1000})
+                try:
+                    await asyncio.wait_for(self._task, timeout=2.0)
+                except asyncio.TimeoutError:
+                    self._task.cancel()
+
+        socket = AsgiWebSocket()
+        await socket.wait_accepted()
+        # Greeting frame from WebSocketResponse (duplex send/recv available after)
+        first = await socket.recv()
+        socket._first = first  # type: ignore[attr-defined]
+        return socket

future/types.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import enum
+import re
+
+from collections.abc import Awaitable, MutableMapping
+from typing import Any, Callable, TypedDict
+
+
+# ASGI specific
+ASGIScope = MutableMapping[str, Any]
+ASGIMessage = MutableMapping[str, Any]
+ASGISend = Callable[[ASGIMessage], Awaitable[None]]
+ASGIReceive = Callable[[], Awaitable[ASGIMessage]]
+
+
+class AsgiEventType(enum.StrEnum):
+    LIFESPAN_STARTUP = "lifespan.startup"
+    LIFESPAN_STARTUP_COMPLETE = "lifespan.startup.complete"
+    LIFESPAN_STARTUP_FAILED = "lifespan.startup.failed"
+    LIFESPAN_SHUTDOWN = "lifespan.shutdown"
+    LIFESPAN_SHUTDOWN_COMPLETE = "lifespan.shutdown.complete"
+    LIFESPAN_SHUTDOWN_FAILED = "lifespan.shutdown.failed"
+    HTTP_REQUEST = "http.request"
+    HTTP_RESPONSE_START = "http.response.start"
+    HTTP_RESPONSE_BODY = "http.response.body"
+    WEBSOCKET_CONNECT = "websocket.connect"
+    WEBSOCKET_ACCEPT = "websocket.accept"
+    WEBSOCKET_RECEIVE = "websocket.receive"
+    WEBSOCKET_SEND = "websocket.send"
+    WEBSOCKET_DISCONNECT = "websocket.disconnect"
+    WEBSOCKET_CLOSE = "websocket.close"
+
+
+class RegexConfig(TypedDict):
+    paths: list[re.Pattern[str]]
+
+
+class RouteConfig(TypedDict):
+    handler: Callable[..., Any]
+    controller: Any
+    action: str | None
+    middleware: dict[str, list[Any]]  # type: ignore
+    regex: dict[str, list[re.Pattern[str] | re.Pattern[bytes]]] | None
+    methods: list[str]
+    route: Any  # FIXME: Added in temporarily because of a regression in the regex matching causing /users/123/test to not match /users/123/test/. Not sure when this happened. This shouldnt be needed.
+    group: dict[str, str]

future_framework-1.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: future-framework
+Version: 1.1.0
+Summary: Next Gen. ASGI Framework for minimal Web APIs
+License: LICENSE
+License-File: LICENSE
+Author: nicolaipre
+Requires-Python: >=3.12,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: clickhouse-driver (>=0.2.11,<0.3.0)
+Requires-Dist: elasticsearch (>=9.4.0,<10.0.0)
+Requires-Dist: faker (>=40.0.0,<41.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: inflection (>=0.5.1,<0.6.0)
+Requires-Dist: psycopg2-binary (>=2.9.12,<3.0.0)
+Requires-Dist: pymongo (>=4.17.0,<5.0.0)
+Requires-Dist: pymysql (>=1.2.0,<2.0.0)
+Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)
+Requires-Dist: redis (>=8.0.0,<9.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: sqlalchemy (>=2.0.51,<3.0.0)
+Requires-Dist: strawberry-graphql (>=0.323.0,<0.324.0)
+Requires-Dist: uvicorn (>=0.51.0,<0.52.0)
+Description-Content-Type: text/markdown
+
+# Future
+Minimal, decorator-free [ASGI](https://asgi.readthedocs.io/) framework for Python APIs — routing, middleware, Active Record, migrations, seeds, OpenAPI, and interval tasks.
+
+[![Build Status](https://github.com/nicolaipre/future/actions/workflows/ci.yml/badge.svg)](https://github.com/nicolaipre/future/actions)
+[![Package version](https://badge.fury.io/py/future-framework.svg)](https://pypi.org/project/future-framework/)
+[![codecov](https://codecov.io/gh/nicolaipre/future/branch/master/graph/badge.svg)](https://codecov.io/gh/nicolaipre/future)
+
+## Documentation
+Published at **[nicolaipre.github.io/future](https://nicolaipre.github.io/future/)**. To preview locally: `poetry install --with docs && poetry run mkdocs serve`.
+
+## Install
+```bash
+poetry add future-framework
+# or from git: poetry add git+https://github.com/nicolaipre/future.git@master
+poetry run future init myproject
+```
+
+Import name is `future` (`from future.application import Future`).
+
+## Hello
+```python
+from future.application import Future
+from future.controllers import Controller
+from future.lifespan import Lifespan
+from future.response import Response
+from future.routing import Get, RouteGroup
+
+class HomeController(Controller):
+    async def index(self) -> Response:
+        return self.response.json({"ok": True})
+
+app = Future(lifespan=Lifespan([], [], []), config={"APP_DOMAIN": "", "APP_NAME": "Demo"})
+app.add_routes([RouteGroup(name="Main", routes=[Get("/", HomeController.index, "home")])])
+app.run(host="127.0.0.1", port=8000)
+```
+
+## License
+See [LICENSE](LICENSE). Versioning: [CHANGELOG.md](CHANGELOG.md).
+