fastlifeweb 0.13.0__tar.gz → 0.15.0__tar.gz

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastlifeweb
-Version: 0.13.0
+Version: 0.15.0
 Summary: High-level web framework
 Home-page: https://github.com/mardiros/fastlife
 License: BSD-derived

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.13.0"
+version = "0.15.0"
 
 [tool.poetry.dependencies]
 python = "^3.11"

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/src/fastlife/config/configurator.py

@@ -14,11 +14,12 @@ phase.
 import importlib
 import inspect
 import logging
-from collections.abc import Mapping
+from collections import defaultdict
+from collections.abc import Mapping, Sequence
 from enum import Enum
 from pathlib import Path
 from types import ModuleType
-from typing import TYPE_CHECKING, Annotated, Any, Callable, Self, Tuple, Type, cast
+from typing import TYPE_CHECKING, Annotated, Any, Callable, Self, Tuple, Type
 
 import venusian
 from fastapi import Depends, FastAPI
@@ -27,20 +28,22 @@ from fastapi import Response
 from fastapi.params import Depends as DependsType
 from fastapi.staticfiles import StaticFiles
 from fastapi.types import IncEx
-from pydantic import BaseModel, Field
 
+from fastlife.config.openapiextra import OpenApiTag
 from fastlife.middlewares.base import AbstractMiddleware
 from fastlife.request.request import Request
 from fastlife.routing.route import Route
 from fastlife.routing.router import Router
 from fastlife.security.csrf import check_csrf
+from fastlife.services.policy import check_permission
 from fastlife.shared_utils.resolver import resolve
 
 from .settings import Settings
 
 if TYPE_CHECKING:
+    from fastlife.security.policy import AbstractSecurityPolicy  # coverage: ignore
     from fastlife.services.templates import (
-        AbstractTemplateRendererFactory,  # coverage: ignore; coverage: ignore
+        AbstractTemplateRendererFactory,  # coverage: ignore
     )
 
     from .registry import AppRegistry, LocaleNegociator  # coverage: ignore
@@ -48,6 +51,8 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 VENUSIAN_CATEGORY = "fastlife"
 
+venusian_ignored_item = str | Callable[[str], bool]
+
 
 class ConfigurationError(Exception):
     """
@@ -55,24 +60,53 @@ class ConfigurationError(Exception):
     """
 
 
-class ExternalDocs(BaseModel):
-    """OpenAPI externalDocs object."""
+def rebuild_router(router: Router) -> Router:
+    """
+    Fix the router.
 
-    description: str
-    """link's description."""
-    url: str
-    """link's URL."""
+    FastAPI routers has dependencies that are injected to routes where they are added.
 
+    It means that if you add a dependencies in the router after the route has
+    been added, then the dependencies is missing in the route added before.
 
-class OpenApiTag(BaseModel):
-    """OpenAPI tag object."""
+    To prenvents issues, we rebuild the router route with the dependency.
 
-    name: str
-    """name of the tag."""
-    description: str
-    """explanation of the tag."""
-    external_docs: ExternalDocs | None = Field(alias="externalDocs", default=None)
-    """external link to the doc."""
+    :param router: the router to rebuild
+    :return: a new router with fixed routes.
+    """
+    if not router.dependencies:
+        return router
+    _router = Router(prefix=router.prefix)
+    _router.dependencies = router.dependencies
+    route: Route
+    for route in router.routes:  # type: ignore
+        dependencies = [
+            dep for dep in route.dependencies if dep not in _router.dependencies
+        ]
+        _router.add_api_route(
+            path=route.path,
+            endpoint=route.endpoint,
+            response_model=route.response_model,
+            status_code=route.status_code,
+            tags=route.tags,
+            dependencies=dependencies,
+            summary=route.summary,
+            description=route.description,
+            response_description=route.response_description,
+            deprecated=route.deprecated,
+            methods=route.methods,
+            operation_id=route.operation_id,
+            response_model_include=route.response_model_include,
+            response_model_exclude=route.response_model_exclude,
+            response_model_by_alias=route.response_model_by_alias,
+            response_model_exclude_unset=route.response_model_exclude_unset,
+            response_model_exclude_defaults=route.response_model_exclude_defaults,
+            response_model_exclude_none=route.response_model_exclude_none,
+            include_in_schema=route.include_in_schema,
+            name=route.name,
+            openapi_extra=route.openapi_extra,
+        )
+    return _router
 
 
 class Configurator:
@@ -102,18 +136,35 @@ class Configurator:
         self.api_description: str = ""
         self.api_summary: str | None = None
 
-        self.router = Router()
+        self._route_prefix: str = ""
+        self._routers: dict[str, Router] = defaultdict(Router)
+        self._security_policies: dict[str, "type[AbstractSecurityPolicy[Any]]"] = {}
+
         self.scanner = venusian.Scanner(fastlife=self)
         self.include("fastlife.views")
         self.include("fastlife.middlewares")
 
+    @property
+    def _current_router(self) -> Router:
+        return self._routers[self._route_prefix]
+
     def build_asgi_app(self) -> FastAPI:
         """
         Build the app after configuration in order to start after beeing configured.
 
         :return: FastAPI application.
         """
-        _app = FastAPI(
+
+        # register our main template renderer at then end, to ensure that
+        # if settings have been manipulated, everythins is taken into account.
+        self.add_renderer(
+            self.registry.settings.jinjax_file_ext,
+            resolve("fastlife.adapters.jinjax.renderer:JinjaxTemplateRenderer")(
+                self.registry.settings
+            ),
+        )
+
+        app = FastAPI(
             title=self.api_title,
             version=self.api_version,
             description=self.api_description,
@@ -125,48 +176,35 @@ class Configurator:
             if self.tags
             else None,
         )
-        _app.router.route_class = Route
-        for _route in self.router.routes:
-            route = cast(Route, _route)
-            _app.router.add_api_route(
-                path=route.path,
-                endpoint=route.endpoint,
-                response_model=route.response_model,
-                status_code=route.status_code,
-                tags=route.tags,
-                dependencies=route.dependencies,
-                summary=route.summary,
-                description=route.description,
-                response_description=route.response_description,
-                deprecated=route.deprecated,
-                methods=route.methods,
-                operation_id=route.operation_id,
-                response_model_include=route.response_model_include,
-                response_model_exclude=route.response_model_exclude,
-                response_model_by_alias=route.response_model_by_alias,
-                response_model_exclude_unset=route.response_model_exclude_unset,
-                response_model_exclude_defaults=route.response_model_exclude_defaults,
-                response_model_exclude_none=route.response_model_exclude_none,
-                include_in_schema=route.include_in_schema,
-                name=route.name,
-                openapi_extra=route.openapi_extra,
-            )
+        app.router.route_class = Route
 
         for middleware_class, options in self.middlewares:
-            _app.add_middleware(middleware_class, **options)  # type: ignore
+            app.add_middleware(middleware_class, **options)  # type: ignore
 
         for status_code_or_exc, exception_handler in self.exception_handlers:
-            _app.add_exception_handler(status_code_or_exc, exception_handler)
+            app.add_exception_handler(status_code_or_exc, exception_handler)
+
+        for prefix, router in self._routers.items():
+            app.include_router(rebuild_router(router), prefix=prefix)
 
         for route_path, directory, name in self.mounts:
-            _app.mount(route_path, StaticFiles(directory=directory), name=name)
-        return _app
+            app.mount(route_path, StaticFiles(directory=directory), name=name)
+        return app
 
-    def include(self, module: str | ModuleType) -> Self:
+    def include(
+        self,
+        module: str | ModuleType,
+        route_prefix: str = "",
+        ignore: venusian_ignored_item | Sequence[venusian_ignored_item] | None = None,
+    ) -> Self:
         """
         Include a module in order to load its configuration.
 
-        It will load and include all the submodule as well.
+        It will scan and load all the submodule until you add an ignore rule.
+
+        The `ignore` argument allows you to ignore certain modules.
+        If it is a scrint, it can be an absolute module name or a relative
+        one, if starts with a dot.
 
         Here is an example.
 
@@ -182,6 +220,8 @@ class Configurator:
         ```
 
         :param module: a module to include.
+        :param route_prefix: prepend all included route with a prefix
+        :param ignore: ignore submodules
         """
         if isinstance(module, str):
             package = None
@@ -190,7 +230,15 @@ class Configurator:
                 package = caller_module.__name__ if caller_module else "__main__"
 
             module = importlib.import_module(module, package)
-        self.scanner.scan(module, categories=[VENUSIAN_CATEGORY])  # type: ignore
+        old, self._route_prefix = self._route_prefix, route_prefix
+        try:
+            self.scanner.scan(  # type: ignore
+                module,
+                categories=[VENUSIAN_CATEGORY],
+                ignore=ignore,
+            )
+        finally:
+            self._route_prefix = old
         return self
 
     def set_locale_negociator(self, locale_negociator: "LocaleNegociator") -> Self:
@@ -247,6 +295,27 @@ class Configurator:
         self.middlewares.append((middleware_class, options))
         return self
 
+    def set_security_policy(
+        self, security_policy: "type[AbstractSecurityPolicy[Any]]"
+    ) -> Self:
+        """
+        Set a security policy for the application.
+
+        ```{important}
+        The security policy is **per route_prefix**.
+        It means that if the application is splitted via multiple
+        route_prefix using the {meth}`Configurator.include`, they
+        all have a distinct security policy. A secutity policy has
+        to be install by all of those include call.
+
+        :param security_policy: The security policy that will applied for the app
+            portion behind the route prefix.
+        ```
+        """
+        self._security_policies[self._route_prefix] = security_policy
+        self._current_router.dependencies.append(Depends(security_policy))
+        return self
+
     def add_api_route(
         self,
         name: str,
@@ -296,9 +365,7 @@ class Configurator:
         :param path: path of the route, use `{curly_brace}` to inject FastAPI Path
             parameters.
         :param endpoint: the function that will reveive the request.
-        :param permission: a permission to validate by the
-            :attr:`fastlife.config.settings.Settings.check_permission` function.
-
+        :param permission: a permission to validate by the security policy.
         :param methods: restrict route to a list of http methods.
         :param description:OpenAPI description for the route.
         :param summary: OpenAPI summary for the route.
@@ -324,9 +391,9 @@ class Configurator:
         """
         dependencies: list[DependsType] = []
         if permission:
-            dependencies.append(Depends(self.registry.check_permission(permission)))
+            dependencies.append(Depends(check_permission(permission)))
 
-        self.router.add_api_route(
+        self._current_router.add_api_route(
             path,
             endpoint,
             # response_model=response_model,
@@ -379,15 +446,13 @@ class Configurator:
         :param path: path of the route, use `{curly_brace}` to inject FastAPI Path
             parameters.
         :param endpoint: the function that will reveive the request.
-        :param permission: a permission to validate by the
-            :attr:`fastlife.config.settings.Settings.check_permission` function.
-
+        :param permission: a permission to validate by the security policy.
         :param methods: restrict route to a list of http methods.
         :return: the configurator.
         """
         dependencies: list[DependsType] = []
         if permission:
-            dependencies.append(Depends(self.registry.check_permission(permission)))
+            dependencies.append(Depends(check_permission(permission)))
 
         if template:
 
@@ -404,7 +469,7 @@ class Configurator:
 
             endpoint = render
 
-        self.router.add_api_route(
+        self._current_router.add_api_route(
             path,
             endpoint,
             status_code=status_code,
@@ -444,6 +509,11 @@ class Configurator:
         """
 
         def exception_handler(request: BaseRequest, exc: Exception) -> Any:
+            # FastAPI exception handler does not provide our request object
+            # it seems like it is rebuild from the asgi scope. Even the router
+            # class is wrong.
+            # Until we store a security policy per rooter, we rebuild an
+            # incomplete request here.
             request = Request(self.registry, request)
             resp = handler(request, exc)
             if isinstance(resp, Response):
@@ -479,6 +549,17 @@ class Configurator:
         self.registry.renderers[f".{file_ext.lstrip('.')}"] = renderer  # type: ignore
         return self
 
+    def add_template_search_path(self, path: str) -> Self:
+        """
+        Add a template search path directly from the code.
+
+        :param path: template path.
+        """
+        self.registry.settings.template_search_path = (
+            f"{self.registry.settings.template_search_path},{path}"
+        )
+        return self
+
 
 def configure(
     wrapped: Callable[[Configurator], None],

fastlifeweb-0.15.0/src/fastlife/config/openapiextra.py

@@ -0,0 +1,22 @@
+"""Types for OpenAPI documentation."""
+from pydantic import BaseModel, Field
+
+
+class ExternalDocs(BaseModel):
+    """OpenAPI externalDocs object."""
+
+    description: str
+    """link's description."""
+    url: str
+    """link's URL."""
+
+
+class OpenApiTag(BaseModel):
+    """OpenAPI tag object."""
+
+    name: str
+    """name of the tag."""
+    description: str
+    """explanation of the tag."""
+    external_docs: ExternalDocs | None = Field(alias="externalDocs", default=None)
+    """external link to the doc."""

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/src/fastlife/config/registry.py

@@ -5,9 +5,7 @@ from fastapi import Depends
 from fastapi import Request as FastAPIRequest
 
 from fastlife.request.request import Request
-from fastlife.security.policy import CheckPermission
 from fastlife.services.translations import LocalizerFactory
-from fastlife.shared_utils.resolver import resolve
 
 if TYPE_CHECKING:
     from fastlife.services.templates import (  # coverage: ignore
@@ -34,19 +32,13 @@ class AppRegistry:
 
     settings: Settings
     renderers: Mapping[str, "AbstractTemplateRendererFactory"]
-    check_permission: CheckPermission
     locale_negociator: LocaleNegociator
     localizer: LocalizerFactory
 
     def __init__(self, settings: Settings) -> None:
         self.settings = settings
-        self.check_permission = resolve(settings.check_permission)
         self.locale_negociator = _default_negociator(self.settings)
-        self.renderers = {
-            f".{settings.jinjax_file_ext}": resolve(
-                "fastlife.adapters.jinjax.renderer:JinjaxTemplateRenderer"
-            )(settings),
-        }
+        self.renderers = {}
         self.localizer = LocalizerFactory()
 
     def get_renderer(self, template: str) -> "AbstractTemplateRendererFactory":

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/src/fastlife/config/resources.py

@@ -13,11 +13,12 @@ from typing import Any, Callable
 import venusian
 from fastapi.types import IncEx
 
+from fastlife.config.openapiextra import ExternalDocs
+
 from .configurator import (
     VENUSIAN_CATEGORY,
     ConfigurationError,
     Configurator,
-    ExternalDocs,
     OpenApiTag,
 )
 
@@ -143,6 +144,7 @@ def resource(
 
 
 def resource_view(
+    *,
     permission: str | None = None,
     status_code: int | None = None,
     summary: str | None = None,

{fastlifeweb-0.13.0 → fastlifeweb-0.15.0}/src/fastlife/config/settings.py

@@ -106,9 +106,6 @@ class Settings(BaseSettings):
     domain_name: str = Field(default="", title="domain name where the app is served")
     """Domain name whre the app is served."""
 
-    check_permission: str = Field(default="fastlife.security.policy:check_permission")
-    """Handler for checking permission set on any views using the configurator."""
-
     decode_reverse_proxy_headers: bool = Field(default=True)
     """Ensure that the request object has information based on http proxy headers."""
 

fastlifeweb-0.15.0/src/fastlife/request/request.py

@@ -0,0 +1,49 @@
+"""HTTP Request representation in a python object."""
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import Request as FastAPIRequest
+
+if TYPE_CHECKING:
+    from fastlife.config.registry import AppRegistry  # coverage: ignore
+    from fastlife.security.policy import (  # coverage: ignore
+        AbstractSecurityPolicy,
+        HasPermission,
+    )
+
+
+class Request(FastAPIRequest):
+    """HTTP Request representation."""
+
+    registry: "AppRegistry"
+    """Direct access to the application registry."""
+    locale_name: str
+    """Request locale used for the i18n of the response."""
+
+    security_policy: "AbstractSecurityPolicy[Any] | None"
+    """Request locale used for the i18n of the response."""
+
+    def __init__(self, registry: "AppRegistry", request: FastAPIRequest) -> None:
+        super().__init__(request.scope, request.receive)
+        self.registry = registry
+        self.locale_name = registry.locale_negociator(self)
+        self.security_policy = None  # build it from the ? registry
+
+    async def has_permission(
+        self, permission: str
+    ) -> "HasPermission | type[HasPermission]":
+        """
+        A helper to check that a user has the given permission.
+
+        Not that this method does not raised, it return a boolean like object.
+        It allows batch permission checks.
+        You might need to check multiple permissions in different contexts or
+        for different resources before raising an http error.
+        """
+        if self.security_policy is None:
+            raise RuntimeError(
+                f"Request {self.url.path} require a security policy, "
+                "explicit fastlife.security.policy.InsecurePolicy is required."
+            )
+
+        return await self.security_policy.has_permission(permission)

fastlifeweb-0.15.0/src/fastlife/security/policy.py

@@ -0,0 +1,171 @@
+"""Security policy."""
+
+import abc
+import logging
+from typing import Any, Callable, Coroutine, Literal, TypeVar
+from uuid import UUID
+
+from fastapi import HTTPException
+from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
+from typing_extensions import Generic
+
+from fastlife import Request
+
+CheckPermissionHook = Callable[..., Coroutine[Any, Any, None]] | Callable[..., None]
+CheckPermission = Callable[[str], CheckPermissionHook]
+
+TUser = TypeVar("TUser")
+
+log = logging.getLogger(__name__)
+
+
+class Unauthorized(HTTPException):
+    """An exception raised to stop a request exectution and return an HTTP Error."""
+
+    def __init__(
+        self,
+        status_code: int = HTTP_401_UNAUTHORIZED,
+        detail: str = "Unauthorized",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(status_code, detail, headers)
+
+
+class Forbidden(HTTPException):
+    """An exception raised to stop a request exectution and return an HTTP Error."""
+
+    def __init__(
+        self,
+        status_code: int = HTTP_403_FORBIDDEN,
+        detail: str = "Forbidden",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(status_code, detail, headers)
+
+
+class BoolMeta(type):
+    def __bool__(cls) -> bool:
+        return cls.kind == "allowed"  # type: ignore
+
+    def __repr__(cls) -> str:
+        return cls.reason  # type: ignore
+
+
+class HasPermission(int, metaclass=BoolMeta):
+    kind: Literal["allowed", "unauthenticated", "denied"]
+    reason: str
+
+    def __new__(cls, reason: str) -> "HasPermission":
+        instance = super().__new__(cls)
+        instance.reason = reason
+        return instance
+
+    def __repr__(self) -> str:
+        return self.reason
+
+    def __bool__(self) -> bool:
+        return self.kind == "allowed"
+
+
+class Allowed(HasPermission):
+    """Represent a permission check result that is allowed."""
+
+    kind = "allowed"
+    reason = "Allowed"
+
+
+class Unauthenticated(HasPermission):
+    """
+    Represent a permission check result that is not allowed due to
+    missing authentication mechanism.
+    """
+
+    kind = "unauthenticated"
+    reason = "Authentication required"
+
+
+class Denied(HasPermission):
+    """
+    Represent a permission check result that is not allowed due to lack of permission.
+    """
+
+    kind = "denied"
+    reason = "Access denied to this resource"
+
+
+class AbstractSecurityPolicy(abc.ABC, Generic[TUser]):
+    """Security policy base classe."""
+
+    Forbidden = Forbidden
+    """The exception raised if the user identified is not granted."""
+    Unauthorized = Unauthorized
+    """The exception raised if no user has been identified."""
+
+    def __init__(self, request: Request):
+        """
+        Build the security policy.
+
+        When implementing a security policy, multiple parameters can be added
+        to the constructor as FastAPI dependencies, using the `Depends` FastAPI
+        annotation.
+        The security policy is installed has a depenency of the router that hold
+        a route prefix of the application.
+        """
+        self.request = request
+        self.request.security_policy = self  # we do backref to implement has_permission
+
+    @abc.abstractmethod
+    async def identity(self) -> TUser | None:
+        """
+        Return app-specific user object or raise an HTTPException.
+        """
+
+    @abc.abstractmethod
+    async def authenticated_userid(self) -> str | UUID | None:
+        """
+        Return app-specific user object or raise an HTTPException.
+        """
+
+    @abc.abstractmethod
+    async def has_permission(
+        self, permission: str
+    ) -> HasPermission | type[HasPermission]:
+        """Allow access to everything if signed in."""
+
+    @abc.abstractmethod
+    async def remember(self, user: TUser) -> None:
+        """Save the user identity in the request session."""
+
+    @abc.abstractmethod
+    async def forget(self) -> None:
+        """Destroy the request session."""
+
+
+class InsecurePolicy(AbstractSecurityPolicy[None]):
+    """
+    An implementation of the security policy made for explicit unsecured access.
+
+    Setting a permission on a view require a security policy, if not set, accessing
+    to a view will raise a RuntimeError. To bypass this error for testing purpose
+    or your own reason, the InsecurePolicy has to be set to the configurator.
+    """
+
+    async def identity(self) -> None:
+        """Nobodies is identified."""
+        return None
+
+    async def authenticated_userid(self) -> str | UUID:
+        """An uuid mades of 0."""
+        return UUID(int=0)
+
+    async def has_permission(
+        self, permission: str
+    ) -> HasPermission | type[HasPermission]:
+        """Access is allways granted."""
+        return Allowed
+
+    async def remember(self, user: None) -> None:
+        """Do nothing."""
+
+    async def forget(self) -> None:
+        """Do nothing."""