fastlifeweb 0.10.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

fastlife/__init__.py

@@ -1,5 +1,4 @@
-from .configurator import Configurator, configure
-from .configurator.registry import Registry
+from .config import Configurator, Registry, Settings, configure
 
 # from .request.form_data import model
 from .templating import Template, template
@@ -11,6 +10,7 @@ __all__ = [
     "template",
     "Template",
     "Registry",
+    "Settings",
     # Model
     # "model",
 ]

fastlife/config/__init__.py

@@ -0,0 +1,13 @@
+"""Configure fastlife app for dependency injection."""
+
+from .configurator import Configurator, configure
+from .registry import AppRegistry, Registry
+from .settings import Settings
+
+__all__ = [
+    "Configurator",
+    "configure",
+    "Registry",
+    "AppRegistry",
+    "Settings",
+]

fastlife/{configurator → config}/configurator.py

@@ -1,6 +1,14 @@
 """
-The configurator is here to register routes in a fastapi app,
-with dependency injection.
+The configurator registers routes in a FastAPI application while
+adding support for dependency injection during the configuration phase.
+
+FastAPI does not provide any built-in support for dependency injection
+during the configuration phase.
+Instead, it only resolves dependencies at request time, ensuring they
+are dynamically handled per request.
+
+The configurator is designed to handle the setup during the configuration
+phase.
 """
 
 import importlib
@@ -9,28 +17,20 @@ import logging
 from enum import Enum
 from pathlib import Path
 from types import ModuleType
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Coroutine,
-    List,
-    Optional,
-    Self,
-    Type,
-    Union,
-)
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Self, Type, Union
 
 import venusian
-from fastapi import Depends, FastAPI, Request, Response
+from fastapi import Depends, FastAPI
+from fastapi import Request as BaseRequest
 from fastapi.params import Depends as DependsType
 from fastapi.staticfiles import StaticFiles
 
-from fastlife.configurator.base import AbstractMiddleware
-from fastlife.configurator.route_handler import FastlifeRoute
+from fastlife.middlewares.base import AbstractMiddleware
+from fastlife.request.request import Request
+from fastlife.routing.route import Route
 from fastlife.security.csrf import check_csrf
+from fastlife.shared_utils.resolver import resolve
 
-from .route_handler import FastlifeRequest
 from .settings import Settings
 
 if TYPE_CHECKING:
@@ -45,49 +45,53 @@ class Configurator:
     Configure and build an application.
 
     Initialize the app from the settings.
-
-    :param settings: Application settings.
     """
 
     registry: "AppRegistry"
 
     def __init__(self, settings: Settings) -> None:
-        from .registry import initialize_registry  # XXX circular import
-
-        self.registry = initialize_registry(settings)
+        """
+        :param settings: Application settings.
+        """
+        registry_cls = resolve(settings.registry_class)
+        self.registry = registry_cls(settings)
         self._app = FastAPI(
-            dependencies=[Depends(check_csrf(self.registry))],
+            dependencies=[Depends(check_csrf())],
             docs_url=None,
             redoc_url=None,
         )
-        FastlifeRoute.registry = self.registry
-        self._app.router.route_class = FastlifeRoute
+        Route._registry = self.registry  # type: ignore
+        self._app.router.route_class = Route
         self.scanner = venusian.Scanner(fastlife=self)
         self.include("fastlife.views")
         self.include("fastlife.middlewares")
 
-    def get_app(self) -> FastAPI:
+    def get_asgi_app(self) -> FastAPI:
         """
         Get the app after configuration in order to start after beeing configured.
 
-        :return: FastAPI application
+        :return: FastAPI application.
         """
         return self._app
 
     def include(self, module: str | ModuleType) -> "Configurator":
         """
-        Include a module in order to load its views.
+        Include a module in order to load its configuration.
 
-        Here is an example.
+        It will load and include all the submodule as well.
 
-        ::
+        Here is an example.
 
-            from fastlife import Configurator, configure
+        ```python
+        from fastlife import Configurator, configure
 
-            @configure
-            def includeme(config: Configurator) -> None:
-                config.include(".views")
+        def home() -> dict[str, str]:
+            return {"hello": "world"}
 
+        @configure
+        def includeme(config: Configurator) -> None:
+            config.add_route("home", "/", home)
+        ```
 
         :param module: a module to include.
         """
@@ -114,7 +118,7 @@ class Configurator:
         self,
         name: str,
         path: str,
-        endpoint: Callable[..., Coroutine[Any, Any, Response]],
+        endpoint: Callable[..., Any],
         *,
         permission: str | None = None,
         status_code: int | None = None,
@@ -142,7 +146,26 @@ class Configurator:
         #     generate_unique_id
         # ),
     ) -> "Configurator":
-        """Add a route to the app."""
+        """
+        Add a route to the app.
+
+        Fastlife does not use a decorator to attach routes, instead the decorator
+        :func:`fastlife.config.configurator.configure` has to be used to
+        inject routes inside a method and call the add_route method.
+
+        :param name: name of the route, used to build route from the helper
+            :meth:`fastlife.request.request.Request.url_for` in order to create links.
+        :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 methods: restrict route to a list of http methods.
+        :param response_description: description for the response.
+        :param deprecated: mark the route as deprecated.
+        :return: the configurator.
+        """
         dependencies: List[DependsType] = []
         if permission:
             dependencies.append(Depends(self.registry.check_permission(permission)))
@@ -181,7 +204,7 @@ class Configurator:
         """
         Mount a directory to an http endpoint.
 
-        :param route_path: the root path for the statics
+        :param route_path: the root path for the statics.
         :param directory: the directory on the filesystem where the statics files are.
         :param name: a name for the route in the starlette app.
         :return: the configurator
@@ -195,8 +218,8 @@ class Configurator:
     ) -> "Configurator":
         """Add an exception handler the application."""
 
-        def exception_handler(request: Request, exc: Exception) -> Any:
-            req = FastlifeRequest(self.registry, request)
+        def exception_handler(request: BaseRequest, exc: Exception) -> Any:
+            req = Request(self.registry, request)
             return handler(req, exc)
 
         self._app.add_exception_handler(status_code_or_exc, exception_handler)

fastlife/{configurator → config}/registry.py

@@ -2,7 +2,7 @@ from typing import TYPE_CHECKING, Annotated
 
 from fastapi import Depends
 
-from fastlife.configurator.route_handler import FastlifeRequest
+from fastlife.request.request import Request
 from fastlife.security.policy import CheckPermission
 from fastlife.shared_utils.resolver import resolve
 
@@ -33,15 +33,7 @@ class AppRegistry:
         self.check_permission = resolve(settings.check_permission)
 
 
-def initialize_registry(settings: Settings) -> AppRegistry:
-    # global DEFAULT_REGISTRY
-    # if DEFAULT_REGISTRY is not None:  # type: ignore
-    #     raise ValueError("Registry is already set")
-    AppRegistryCls = resolve(settings.registry_class)
-    return AppRegistryCls(settings)  # type: ignore
-
-
-def get_registry(request: FastlifeRequest) -> AppRegistry:
+def get_registry(request: Request) -> AppRegistry:
     return request.registry
 
 

fastlife/{configurator → config}/settings.py

@@ -15,7 +15,9 @@ class Settings(BaseSettings):
     """
 
     model_config = SettingsConfigDict(env_prefix="fastlife_")
-    """Set the prefix fastlife_ for configuration using operating system environment."""
+    """
+    Set the prefix ``fastlife_`` for configuration using operating system environment.
+    """
 
     fastlife_route_prefix: str = Field(default="/_fl")
     """Route prefix used for fastlife internal views."""
@@ -27,7 +29,7 @@ class Settings(BaseSettings):
     a python module name. for instance `fastlife:templates` is the direcotry templates
     found in the fastlife package.
     """
-    registry_class: str = Field(default="fastlife.configurator.registry:AppRegistry")
+    registry_class: str = Field(default="fastlife.config.registry:AppRegistry")
     """Implementation class for the application regitry."""
     template_renderer_class: str = Field(
         default="fastlife.templating.renderer:JinjaxTemplateRenderer"
@@ -40,7 +42,9 @@ class Settings(BaseSettings):
     Pydantic form default model prefix for serialized field in www-urlencoded-form.
     """
     csrf_token_name: str = Field(default="csrf_token")
-    """Name of the html input field for csrf token."""
+    """
+    Name of the html input field and for the http cookie for csrf token.
+    """
 
     jinjax_use_cache: bool = Field(default=True)
     """

fastlife/middlewares/__init__.py

@@ -0,0 +1,7 @@
+"""
+Fastlife HTTP middlewares are Starlette HTTP Middleware.
+
+HTTP middleware is a function that processes requests before they reach
+the view function or modifies responses after the view has processed
+the request.
+"""

fastlife/middlewares/base.py

@@ -0,0 +1,24 @@
+"""Build you own middleware."""
+
+import abc
+
+from starlette.types import Receive, Scope, Send
+
+
+class AbstractMiddleware(abc.ABC):
+    """
+    Abstract Base Class that represent a fastlife middleware.
+
+    Starlette provide a middleware stack but does not have an abstract base class.
+    This is the only reason this class exists.
+
+    Fastlife middleware are starlette middlewares.
+    """
+
+    @abc.abstractmethod
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """
+        Called every time an http request is reveived.
+
+        This method before the request object even exists.
+        """

fastlife/middlewares/reverse_proxy/__init__.py

@@ -1,7 +1,23 @@
+"""
+A middleware that update the request scope for https behind a proxy.
+
+The attempt of this middleware is to fix Starlette behavior that use client and scheme
+header based on the header ``x-forwarded-*`` headers and the ``x-real-ip``.
+
+the ``x-forwarded-for`` header is not parsed to find the appropriate value,
+the ``x-real-ip`` is used.
+notethat the ``x-forwarded-port`` header is not used.
+
+Note that uvicorn or hypercorn offer the same kind middleware.
+
+Norw, every website is in https, so, this middleware is active by default.
+"""
 from fastlife import Configurator, configure
 
 from .x_forwarded import XForwardedStar
 
+__all__ = ["XForwardedStar"]
+
 
 @configure
 def includeme(config: Configurator) -> None:

fastlife/middlewares/reverse_proxy/x_forwarded.py

@@ -1,22 +1,9 @@
-"""
-A middleware that update the request scope for https behind a proxy.
-
-The attempt of this middleware is to fix Starlette behavior that use client and scheme
-header based on the header x-forwarded-* headers and the x-real-ip.
-
-the x-forwarded-for header is not parsed to find the appropriate value,
-the x-real-ip is used.
-notethat the x-forwarded-port header is not used.
-
-Note that uvicorn or hypercorn offer the same kind middleware.
-"""
-
 import logging
 from typing import Optional, Sequence, Tuple
 
 from starlette.types import ASGIApp, Receive, Scope, Send
 
-from fastlife.configurator.base import AbstractMiddleware
+from fastlife.middlewares.base import AbstractMiddleware
 
 log = logging.getLogger(__name__)
 

fastlife/middlewares/session/__init__.py

@@ -1,7 +1,23 @@
+"""
+Initialize a session.
+
+
+The session :attr:`fastlife.config.settings.Settings.session_secret_key` must
+be set in order to create a session.
+
+This secret is used to sign session content in order to prevent malicious user
+to write their own session content. Note that the provided session implementation
+does not cipher session content, it just sign. No secret should be placed in the
+session.
+"""
+
 from fastlife import Configurator, configure
 from fastlife.shared_utils.resolver import resolve
 
 from .middleware import SessionMiddleware
+from .serializer import AbsractSessionSerializer, SignedSessionSerializer
+
+__all__ = ["SessionMiddleware", "AbsractSessionSerializer", "SignedSessionSerializer"]
 
 
 @configure

fastlife/middlewares/session/middleware.py

@@ -1,3 +1,5 @@
+"""Deal with http session."""
+
 from datetime import timedelta
 from typing import Literal, Type
 
@@ -5,12 +7,14 @@ from starlette.datastructures import MutableHeaders
 from starlette.requests import HTTPConnection
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
-from fastlife.configurator.base import AbstractMiddleware
+from fastlife.middlewares.base import AbstractMiddleware
 
 from .serializer import AbsractSessionSerializer, SignedSessionSerializer
 
 
 class SessionMiddleware(AbstractMiddleware):
+    """Http session based on cookie."""
+
     def __init__(
         self,
         app: ASGIApp,
@@ -36,6 +40,7 @@ class SessionMiddleware(AbstractMiddleware):
             self.security_flags += f"; Domain={cookie_domain}"
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Initialize a session based on cookie."""
         if scope["type"] not in ("http", "websocket"):  # pragma: no cover
             await self.app(scope, receive, send)
             return

fastlife/middlewares/session/serializer.py

@@ -1,3 +1,4 @@
+"""Serialize session."""
 import abc
 import json
 from base64 import b64decode, b64encode
@@ -7,31 +8,51 @@ import itsdangerous
 
 
 class AbsractSessionSerializer(abc.ABC):
+    """Session serializer base class"""
+
     @abc.abstractmethod
     def __init__(self, secret_key: str, max_age: int) -> None:
         ...
 
     @abc.abstractmethod
     def serialize(self, data: Mapping[str, Any]) -> bytes:
+        """Serialize the session content to bytes in order to be saved."""
         ...
 
     @abc.abstractmethod
     def deserialize(self, data: bytes) -> Tuple[Mapping[str, Any], bool]:
+        """Derialize the session raw bytes content and return it as a mapping."""
         ...
 
 
 class SignedSessionSerializer(AbsractSessionSerializer):
+    """
+    The default fastlife session serializer.
+
+    It's based on the itsdangerous package to sign the session with a secret key.
+
+    :param secret_key: a secret used to sign the session payload.
+
+    :param max_age: session lifetime in seconds.
+    """
+
     def __init__(self, secret_key: str, max_age: int) -> None:
         self.signer = itsdangerous.TimestampSigner(secret_key)
         self.max_age = max_age
 
     def serialize(self, data: Mapping[str, Any]) -> bytes:
+        """Serialize and sign the session."""
         dump = json.dumps(data).encode("utf-8")
         encoded = b64encode(dump)
         signed = self.signer.sign(encoded)
         return signed
 
     def deserialize(self, data: bytes) -> Tuple[Mapping[str, Any], bool]:
+        """Deserialize the session.
+
+        If the signature is incorect, the session restart from the begining.
+        No exception raised.
+        """
         try:
             data = self.signer.unsign(data, max_age=self.max_age)
             # We can't deserialize something wrong since the serialize

fastlife/request/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP Request."""
+
+from .request import Request
+
+__all__ = ["Request"]

fastlife/request/form.py

@@ -1,9 +1,11 @@
+"""HTTP Form serialization."""
+
 from typing import Any, Callable, Generic, Mapping, Type, TypeVar, get_origin
 
 from fastapi import Depends
 from pydantic import BaseModel, ValidationError
 
-from fastlife.configurator.registry import Registry
+from fastlife.config.registry import Registry
 from fastlife.request.form_data import MappingFormData
 from fastlife.shared_utils.infer import is_union
 

fastlife/request/form_data.py

@@ -1,3 +1,7 @@
+"""
+Set of functions to unserialize www-form-urlencoded format to python simple types.
+"""
+
 from typing import (
     Annotated,
     Any,
@@ -10,7 +14,7 @@ from typing import (
 
 from fastapi import Depends, Request
 
-from fastlife.configurator.registry import Registry
+from fastlife.config.registry import Registry
 
 
 def unflatten_struct(
@@ -20,6 +24,12 @@ def unflatten_struct(
     *,
     csrf_token_name: Optional[str] = None,
 ) -> Mapping[str, Any] | Sequence[Any]:
+    """
+    Take a flatten_input map, with key segmented by `.` and build a nested dict.
+
+    Fastlife use plain old web form to send data via HTTP POST, this function
+    prepare the data before get injected to pydantic for serialization.
+    """
     # we sort to ensure that list index are ordered
     # formkeys = sorted(flatten_input.keys())
     for key in flatten_input:
@@ -71,8 +81,12 @@ def unflatten_struct(
 
 
 async def unflatten_mapping_form_data(
-    request: Request, reg: Registry
+    request: Request, registry: Registry
 ) -> Mapping[str, Any]:
+    """
+    Parse the :meth:`fastlife.request.request.form` and build a nested structure.
+    """
+
     form_data = await request.form()
     form_data_decode_list: MutableMapping[str, Any] = {}
     for key, val in form_data.multi_items():
@@ -90,7 +104,7 @@ async def unflatten_mapping_form_data(
             form_data_decode_list[key] = val
 
     ret = unflatten_struct(
-        form_data_decode_list, {}, csrf_token_name=reg.settings.csrf_token_name
+        form_data_decode_list, {}, csrf_token_name=registry.settings.csrf_token_name
     )  # type: ignore
     return ret  # type: ignore
 
@@ -98,6 +112,9 @@ async def unflatten_mapping_form_data(
 async def unflatten_sequence_form_data(
     request: Request, reg: Registry
 ) -> Sequence[str]:
+    """
+    Parse the :meth:`fastlife.request.request.form` and build a list of structure.
+    """
     form_data = await request.form()
     # Could raise a value error !
     return unflatten_struct(
@@ -106,4 +123,12 @@ async def unflatten_sequence_form_data(
 
 
 MappingFormData = Annotated[Mapping[str, Any], Depends(unflatten_mapping_form_data)]
+"""
+Fast API Dependency to deserialize a :meth:`fastlife.request.request.Request.form`
+to a dict.
+"""
 SequenceFormData = Annotated[Sequence[str], Depends(unflatten_sequence_form_data)]
+"""
+Fast API Dependency to deserialize a :meth:`fastlife.request.request.Request.form`
+to a list.
+"""

fastlife/request/request.py

@@ -0,0 +1,18 @@
+"""HTTP Request representation in a python object."""
+from typing import TYPE_CHECKING
+
+from fastapi import Request as BaseRequest
+
+if TYPE_CHECKING:
+    from fastlife.config.registry import AppRegistry  # coverage: ignore
+
+
+class Request(BaseRequest):
+    """HTTP Request representation."""
+
+    registry: "AppRegistry"
+    """Direct access to the application registry."""
+
+    def __init__(self, registry: "AppRegistry", request: BaseRequest) -> None:
+        super().__init__(request.scope, request.receive)
+        self.registry = registry

fastlife/routing/__init__.py

@@ -0,0 +1,7 @@
+"""
+HTTP Routing.
+
+The http routing is the process that choose the proper view functions based
+on the http request received. Usually it is based on the request path_info
+and the http method.
+"""

fastlife/routing/route.py

@@ -0,0 +1,45 @@
+"""HTTP Route."""
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+from fastapi.routing import APIRoute
+from starlette.requests import Request as StarletteRequest
+from starlette.responses import Response
+
+from fastlife.request.request import Request
+
+if TYPE_CHECKING:
+    from fastlife.config.registry import AppRegistry  # coverage: ignore
+
+
+class Route(APIRoute):
+    """
+    Routing for fastlife application.
+
+    The fastlife router construct fastlife request object in order to
+    have the registry property available in every received request.
+    """
+
+    _registry: "AppRegistry"
+    """
+    The application registry.
+
+    this static variable is initialized by the configurator during
+    the startup and keep the registry during the lifetime of the application.
+
+    this variable should be accessed via the request object or the
+    :class:`fastlife.config.Registry` depenency injection.
+    """
+
+    def get_route_handler(
+        self,
+    ) -> Callable[[StarletteRequest], Coroutine[Any, Any, Response]]:
+        """
+        Replace the request object by the fastlife request associated with the registry.
+        """
+        orig_route_handler = super().get_route_handler()
+
+        async def route_handler(request: StarletteRequest) -> Response:
+            req = Request(self._registry, request)
+            return await orig_route_handler(req)
+
+        return route_handler

fastlife/routing/router.py

@@ -1,13 +1,21 @@
+"""
+FastApi router for fastlife application.
+
+The aim of this router is get :class:`fastlife.routing.route.Route`
+available in the FastApi request depency injection.
+"""
 from typing import Any
 
 from fastapi import APIRouter
 
-from fastlife.configurator.route_handler import FastlifeRoute
+from fastlife.routing.route import Route
 
 
-class FastLifeRouter(APIRouter):
-    """The router used split your app in many routes."""
+class Router(APIRouter):
+    """
+    The router used split your app in many routes.
+    """
 
     def __init__(self, **kwargs: Any) -> None:
-        kwargs["route_class"] = FastlifeRoute
+        kwargs["route_class"] = Route
         super().__init__(**kwargs)

fastlife/security/__init__.py

@@ -0,0 +1 @@
+"""Security features."""