future-framework 3.1.1__tar.gz → 3.2.0__tar.gz

{future_framework-3.1.1 → future_framework-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: future-framework
-Version: 3.1.1
+Version: 3.2.0
 Summary: ASGI-based framework for web APIs
 Author: nicolaipre
 License-Expression: MIT
@@ -50,7 +50,6 @@ Import name is `future` (`from future.application import Future`).
 ```python
 from future.application import Future
 from future.interfaces.IController import IController
-from future.lifespan import Lifespan
 from future.response import Response
 from future.routing import Get, RouteGroup
 
@@ -58,7 +57,7 @@ class HomeController(IController):
     async def index(self) -> Response:
         return self.response.json({"ok": True})
 
-app = Future(lifespan=Lifespan([], [], []), config={"APP_DOMAIN": "", "APP_NAME": "Demo"})
+app = Future(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)
 ```

{future_framework-3.1.1 → future_framework-3.2.0}/README.md

@@ -20,7 +20,6 @@ Import name is `future` (`from future.application import Future`).
 ```python
 from future.application import Future
 from future.interfaces.IController import IController
-from future.lifespan import Lifespan
 from future.response import Response
 from future.routing import Get, RouteGroup
 
@@ -28,7 +27,7 @@ class HomeController(IController):
     async def index(self) -> Response:
         return self.response.json({"ok": True})
 
-app = Future(lifespan=Lifespan([], [], []), config={"APP_DOMAIN": "", "APP_NAME": "Demo"})
+app = Future(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)
 ```

{future_framework-3.1.1 → future_framework-3.2.0}/future/application.py

@@ -1,6 +1,7 @@
 import platform
 import sys
 import logging
+import inspect
 import traceback
 
 from collections.abc import Sequence
@@ -16,6 +17,8 @@ from rich.table import Table
 from rich.text import Text
 
 from future.exceptions import ErrorHandler, HTTPException
+from future.authentication.AuthenticationComponent import AuthenticationComponent
+from future.container import Container
 from future.logger import create_uvicorn_logging_config, log
 from future.interfaces.IMiddleware import IMiddleware
 from future.openapi import get_openapi_config, is_docs_path, openapi_routes, rebuild_spec_from_routes, set_openapi_config, spec_path
@@ -72,16 +75,28 @@ while True:
 
 
 class Future:
-    def __init__(self, lifespan: Any, config: dict[str, Any] | None = None) -> None:
+    def __init__(self, lifespan: Any | None = None, config: dict[str, Any] | None = None) -> None:
         # spawn background tasks in the lifespan startup process... or database connections etc...
         # on shutdown, save shit, send info about shutdown etc...
+        if lifespan is None:
+            from future.lifespan import Lifespan
+            lifespan = Lifespan()
         self.lifespan = lifespan
         self.routes: dict[str, dict[str, RouteConfig]] = {}
         self.config = config or {}
+        self._container = Container(self.config)
+        self._container.instance(Container, self._container)
+        self._container.configure_bindings(self.config.get("BINDINGS"))
         self.databases = self.config.get("DATABASES")
         if self.databases:
             from future.database import Database
-            Database().set_connection_details(self.databases)
+            database = Database()
+            database.set_connection_details(self.databases)
+            self._container.component(database, Database)
+
+        authentication = self.config.get("AUTHENTICATION")
+        if authentication:
+            self._container.component(AuthenticationComponent(self._container, authentication), AuthenticationComponent)
 
         domain = self.config.get("APP_DOMAIN", "")
 
@@ -117,9 +132,26 @@ class Future:
 
     def set_config(self, config: dict[str, Any]) -> None:
         self.config = config
+        self._container.config = config
         set_openapi_config(self.config)
         log.setLevel(logging.DEBUG if bool(self.config.get("APP_DEBUG")) else logging.INFO)
 
+    def override(self, dependency: Any, value: Any) -> None:
+        """Replace a resolved dependency, primarily for application tests."""
+        self._container.override(dependency, value)
+
+    def _middleware_priority(self, middleware: Any) -> int:
+        return int(getattr(middleware, "priority", 0))
+
+    def _bind_middleware(self, definition: Any, request: Request, response: Response) -> IMiddleware:
+        if inspect.isclass(definition):
+            middleware = self._container.resolve(definition, provided={Request: request, Response: response})
+        else:
+            middleware = definition
+        if not isinstance(middleware, IMiddleware):
+            raise TypeError(f"Middleware must extend IMiddleware, got {type(middleware).__name__}")
+        return middleware.bind(request, response, self._container)
+
     def _resolve_controller_action(self, endpoint: Any) -> tuple[Any, str | None]:
         qual = getattr(endpoint, "__qualname__", "") or ""
         mod_name = getattr(endpoint, "__module__", None)
@@ -149,8 +181,8 @@ class Future:
 
         middleware_classes: list[Any] = []
         if parent_middlewares:
-            middleware_classes.extend(sorted(parent_middlewares, key=lambda m: m.priority))
-        middleware_classes.extend(sorted(route.middlewares, key=lambda m: m.priority))
+            middleware_classes.extend(sorted(parent_middlewares, key=self._middleware_priority))
+        middleware_classes.extend(sorted(route.middlewares, key=self._middleware_priority))
 
         controller_cls, action = self._resolve_controller_action(route.endpoint)
 
@@ -378,15 +410,18 @@ class Future:
 
         started = False
         try:
-            # async with self.lifespan(app) as state:
-            self.lifespan.app = app
-            async with self.lifespan as state:
-                if state is not None:
-                    scope.setdefault("state", {}).update(state)
-                await send({"type": AsgiEventType.LIFESPAN_STARTUP_COMPLETE})
-                started = True
-                message = await receive()
-                assert message["type"] == AsgiEventType.LIFESPAN_SHUTDOWN
+            await self._container.start()
+            try:
+                self.lifespan.app = app
+                async with self.lifespan as state:
+                    if state is not None:
+                        scope.setdefault("state", {}).update(state)
+                    await send({"type": AsgiEventType.LIFESPAN_STARTUP_COMPLETE})
+                    started = True
+                    message = await receive()
+                    assert message["type"] == AsgiEventType.LIFESPAN_SHUTDOWN
+            finally:
+                await self._container.stop()
 
         except BaseException:
             event_type = AsgiEventType.LIFESPAN_SHUTDOWN_FAILED if started else AsgiEventType.LIFESPAN_STARTUP_FAILED
@@ -446,7 +481,7 @@ class Future:
 
             request.route = matched_route.get("route")
             middleware_classes = matched_route["middleware"].get("classes") or []
-            middleware_instances = [m(request, response) for m in middleware_classes]
+            middleware_instances = [self._bind_middleware(middleware, request, response) for middleware in middleware_classes]
             for mw in middleware_instances:
                 early = await mw.before()
                 if early is not None:
@@ -456,7 +491,7 @@ class Future:
             controller_cls = matched_route.get("controller")
             action = matched_route.get("action")
             if controller_cls and action:
-                ctrl = controller_cls(request, response)
+                ctrl = self._container.resolve(controller_cls, provided={Request: request, Response: response})
                 method = getattr(ctrl, action)
                 if route_params:
                     result = await method(**route_params)
@@ -527,7 +562,7 @@ class Future:
         request.route = matched_route.get("route")
         try:
             middleware_classes = matched_route["middleware"].get("classes") or []
-            middleware_instances = [m(request, response) for m in middleware_classes]
+            middleware_instances = [self._bind_middleware(middleware, request, response) for middleware in middleware_classes]
             for mw in middleware_instances:
                 early = await mw.before()
                 if early is not None:
@@ -537,7 +572,7 @@ class Future:
             controller_cls = matched_route.get("controller")
             action = matched_route.get("action")
             if controller_cls and action:
-                ctrl = controller_cls(request, response)
+                ctrl = self._container.resolve(controller_cls, provided={Request: request, Response: response})
                 method = getattr(ctrl, action)
                 if route_params:
                     result = await method(**route_params)

future_framework-3.2.0/future/authentication/Auth0Authentication.py

@@ -0,0 +1,15 @@
+"""
+Auth0 authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class Auth0Authentication(IAuthentication):
+    auth_type = "oauth"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "Auth0 authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/AuthenticationComponent.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import inspect
+
+from typing import Any
+
+from future.authentication.Identity import Identity
+from future.container import Container
+from future.request import Request
+
+
+class AuthenticationComponent:
+    """Registry and lifecycle owner for named authentication providers."""
+
+    def __init__(self, container: Container, config: dict[str, Any] | None = None) -> None:
+        self._container = container
+        self.config = config or {}
+        self.default = self.config.get("default")
+        self.providers: dict[str, Any] = {}
+        for name, definition in self.config.get("providers", {}).items():
+            self.register(name, self._build_provider(name, definition))
+        if self.default is None and len(self.providers) == 1:
+            self.default = next(iter(self.providers))
+
+    def register(self, name: str, provider: Any) -> None:
+        if not name:
+            raise ValueError("Authentication provider names cannot be empty")
+        if not callable(getattr(provider, "authenticate", None)):
+            raise TypeError(f"Authentication provider {name!r} must define authenticate(request)")
+        self.providers[name] = provider
+
+    def get(self, name: str | None = None) -> Any:
+        selected = name or self.default
+        if not selected:
+            raise LookupError("No default authentication provider is configured")
+        try:
+            return self.providers[selected]
+        except KeyError as exc:
+            raise LookupError(f"Authentication provider {selected!r} is not configured") from exc
+
+    async def authenticate(self, request: Request, provider: str | None = None) -> Identity | None:
+        selected = provider or self.default
+        authenticator = self.get(selected)
+        result = authenticator.authenticate(request)
+        if inspect.isawaitable(result):
+            result = await result
+        if result is not None and not isinstance(result, Identity):
+            raise TypeError(f"Authentication provider {selected!r} must return Identity or None, got {type(result).__name__}")
+        return result
+
+    async def start(self) -> None:
+        for provider in self.providers.values():
+            start = getattr(provider, "start", None)
+            if start is not None:
+                result = start()
+                if inspect.isawaitable(result):
+                    await result
+
+    async def stop(self) -> None:
+        for provider in reversed(list(self.providers.values())):
+            stop = getattr(provider, "stop", None)
+            if stop is not None:
+                result = stop()
+                if inspect.isawaitable(result):
+                    await result
+
+    def _build_provider(self, name: str, definition: Any) -> Any:
+        if not isinstance(definition, dict):
+            if inspect.isclass(definition):
+                return self._container.resolve(definition)
+            return definition
+        driver = definition.get("driver")
+        if driver is None:
+            raise ValueError(f"Authentication provider {name!r} is missing its driver")
+        options = definition.get("options") or {}
+        if not isinstance(options, dict):
+            raise TypeError(f"Authentication provider {name!r} options must be a dictionary")
+        return self._container.resolve(driver, options=options)

future_framework-3.2.0/future/authentication/AzureADAuthentication.py

@@ -0,0 +1,15 @@
+"""
+Azure AD authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class AzureADAuthentication(IAuthentication):
+    auth_type = "basic"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "Azure AD authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/BasicAuthentication.py

@@ -0,0 +1,48 @@
+"""HTTP Basic authentication backed by an application credential verifier."""
+
+import base64
+import binascii
+import inspect
+
+from collections.abc import Callable
+from typing import Any
+
+from future.authentication.Identity import Identity
+from future.interfaces.IAuthentication import IAuthentication
+from future.request import Request
+
+
+class BasicAuthentication(IAuthentication):
+    auth_type = "basic"
+
+    def __init__(self, verify_credentials: Callable[[str, str], Any], realm: str = "Future") -> None:
+        self.verify_credentials = verify_credentials
+        self.challenge = f'Basic realm="{realm}"'
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        authorization = request.headers.get("authorization", "")
+        scheme, _, encoded = authorization.partition(" ")
+        if scheme.lower() != "basic" or not encoded:
+            return None
+        try:
+            username, password = base64.b64decode(encoded, validate=True).decode("utf-8").split(":", 1)
+        except (binascii.Error, ValueError, UnicodeDecodeError):
+            return None
+        result = self.verify_credentials(username, password)
+        if inspect.isawaitable(result):
+            result = await result
+        if result is None or result is False:
+            return None
+        if isinstance(result, Identity):
+            return result
+        if result is True:
+            return Identity(subject=username, provider="basic")
+        if isinstance(result, str):
+            return Identity(subject=result, provider="basic")
+        if isinstance(result, dict):
+            claims = dict(result.get("claims") or {})
+            subject = str(result.get("subject") or result.get("id") or username)
+            roles = tuple(str(role) for role in result.get("roles", ()))
+            scopes = tuple(str(scope) for scope in result.get("scopes", ()))
+            return Identity(subject=subject, provider="basic", claims=claims, roles=roles, scopes=scopes)
+        raise TypeError(f"Basic credential verifier must return Identity, dict, str, bool, or None, got {type(result).__name__}")

future_framework-3.2.0/future/authentication/Identity.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class Identity:
+    __slots__ = ("subject", "provider", "claims", "roles", "scopes", "_initialized")
+    subject: str
+    provider: str
+    claims: dict[str, Any]
+    roles: tuple[str, ...]
+    scopes: tuple[str, ...]
+    _initialized: bool
+
+    def __init__(self, subject: str, provider: str, claims: dict[str, Any] | None = None, roles: tuple[str, ...] = (), scopes: tuple[str, ...] = ()) -> None:
+        object.__setattr__(self, "subject", subject)
+        object.__setattr__(self, "provider", provider)
+        object.__setattr__(self, "claims", dict(claims or {}))
+        object.__setattr__(self, "roles", tuple(roles))
+        object.__setattr__(self, "scopes", tuple(scopes))
+        object.__setattr__(self, "_initialized", True)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if getattr(self, "_initialized", False):
+            raise AttributeError("Identity is immutable")
+        object.__setattr__(self, name, value)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Identity):
+            return False
+        return (self.subject, self.provider, self.claims, self.roles, self.scopes) == (other.subject, other.provider, other.claims, other.roles, other.scopes)
+
+    def __repr__(self) -> str:
+        return f"Identity(subject={self.subject!r}, provider={self.provider!r}, claims={self.claims!r}, roles={self.roles!r}, scopes={self.scopes!r})"

future_framework-3.2.0/future/authentication/KerberosAuthentication.py

@@ -0,0 +1,15 @@
+"""
+Kerberos Single Sign-On authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class KerberosAuthentication(IAuthentication):
+    auth_type = "sso"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "Kerberos authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/KeycloakAuthentication.py

@@ -0,0 +1,15 @@
+"""
+Keycloak authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class KeycloakAuthentication(IAuthentication):
+    auth_type = "oauth"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "Keycloak authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/OAuth2Authentication.py

@@ -0,0 +1,15 @@
+"""
+OAuth 2 authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class OAuth2Authentication(IAuthentication):
+    auth_type = "oauth"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "OAuth 2 authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/OpenIdConnectAuthentication.py

@@ -0,0 +1,15 @@
+"""
+OpenID Connect authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class OpenIdConnectAuthentication(IAuthentication):
+    auth_type = "oidc"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "OpenID Connect authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/SAMLAuthentication.py

@@ -0,0 +1,15 @@
+"""
+SAML Single Sign-On authentication.
+"""
+
+from future.interfaces.IAuthentication import IAuthentication
+from future.authentication.Identity import Identity
+from future.request import Request
+
+
+class SAMLAuthentication(IAuthentication):
+    auth_type = "sso"
+
+    async def authenticate(self, request: Request) -> Identity | None:
+        message = "SAML authentication is not implemented yet"
+        raise NotImplementedError(message)

future_framework-3.2.0/future/authentication/__init__.py

@@ -0,0 +1,3 @@
+from future.authentication.AuthenticationComponent import AuthenticationComponent
+from future.authentication.BasicAuthentication import BasicAuthentication
+from future.authentication.Identity import Identity

{future_framework-3.1.1 → future_framework-3.2.0}/future/cli.py

@@ -11,7 +11,7 @@ from typing import Any
 
 
 APP_ROOT = "app"
-APP_DIRS = ["config", "controllers", "middleware", "models", "plugins", "tasks"]
+APP_DIRS = ["authentication", "config", "controllers", "interfaces", "middleware", "models", "plugins", "repositories", "services", "tasks"]
 
 STUB_KINDS = {
     "readme": {
@@ -172,7 +172,7 @@ STUB_KINDS = {
         "template": dedent("""
             from app.controllers.ExampleController import ExampleController
             from app.middleware.ExampleMiddleware import ExampleMiddleware
-            from future.openapi import openapi_routes
+            from future.controllers.OpenAPIController import OpenAPIController
             from future.routing import RouteGroup, Get
 
 
@@ -181,7 +181,14 @@ STUB_KINDS = {
                     name="Docs",
                     prefix="/api",
                     # middlewares=[ExampleMiddleware],  # protect docs if needed
-                    routes=openapi_routes(uis=["swagger", "redoc", "scalar", "rapidoc"]),
+                    routes=[
+                        Get("/openapi.json", OpenAPIController.openapi, "openapi"),
+                        Get("/swagger-config", OpenAPIController.swagger_config, "swagger-config"),
+                        Get("/docs", OpenAPIController.swagger, "docs"),
+                        Get("/redoc", OpenAPIController.redoc, "redoc"),
+                        Get("/scalar", OpenAPIController.scalar, "scalar"),
+                        Get("/rapidoc", OpenAPIController.rapidoc, "rapidoc"),
+                    ],
                 ),
                 RouteGroup(
                     name="Main",
@@ -332,6 +339,36 @@ STUB_KINDS = {
         """).lstrip("\n"),
         "init": {"class_name": "ExampleMiddleware"},
     },
+    "authentication": {
+        "directory": "app/authentication",
+        "suffix": "Authentication",
+        "template": dedent("""
+            from future.authentication.Identity import Identity
+            from future.interfaces.IAuthentication import IAuthentication
+            from future.request import Request
+
+
+            class {class_name}(IAuthentication):
+                async def authenticate(self, request: Request) -> Identity | None:
+                    return None
+        """).lstrip("\n"),
+    },
+    "repository": {
+        "directory": "app/repositories",
+        "suffix": "Repository",
+        "template": dedent("""
+            class {class_name}:
+                pass
+        """).lstrip("\n"),
+    },
+    "service": {
+        "directory": "app/services",
+        "suffix": "Service",
+        "template": dedent("""
+            class {class_name}:
+                pass
+        """).lstrip("\n"),
+    },
     "plugin": {
         "directory": "app/plugins",
         "suffix": "Plugin",
@@ -399,6 +436,9 @@ class StubMaker:
     def make(self, kind, name):
         if kind not in STUB_KINDS:
             raise ValueError(f"Unknown stub kind: {kind}")
+        is_interface_name = name.startswith("I") and len(name) > 1 and name[1].isupper()
+        if is_interface_name:
+            raise ValueError("The I prefix is reserved for interfaces in app/interfaces")
         config = STUB_KINDS[kind]
         if "directory" not in config:
             raise ValueError(f"Stub kind {kind!r} is not a make:* target")
@@ -651,6 +691,9 @@ examples:
   future routes
   future make:model Trade
   future make:controller Trade
+  future make:service Trade
+  future make:repository Trade
+  future make:authentication LDAP
   future make:migration Trade
   future make:migrations
   future make:seed Trade
@@ -690,10 +733,13 @@ examples:
     subparsers.add_parser("make:seeds", help="Generate seeders for all annotated models (skips existing files)")
 
     stub_help = {
+        "authentication": "Create app/authentication/<Name>Authentication.py",
         "model": "Create app/models/<Name>.py",
         "controller": "Create app/controllers/<Name>Controller.py",
         "middleware": "Create app/middleware/<Name>Middleware.py",
         "plugin": "Create app/plugins/<Name>Plugin.py",
+        "repository": "Create app/repositories/<Name>Repository.py",
+        "service": "Create app/services/<Name>Service.py",
         "task": "Create app/tasks/<Name>.py",
     }
     for kind, help_text in stub_help.items():