fastlifeweb 0.12.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

fastlife/config/configurator.py

@@ -14,28 +14,21 @@ phase.
 import importlib
 import inspect
 import logging
+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,
-    Any,
-    Callable,
-    List,
-    Optional,
-    Self,
-    Tuple,
-    Type,
-    Union,
-    cast,
-)
+from typing import TYPE_CHECKING, Annotated, Any, Callable, Self, Tuple, Type
 
 import venusian
 from fastapi import Depends, FastAPI
 from fastapi import Request as BaseRequest
+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.middlewares.base import AbstractMiddleware
 from fastlife.request.request import Request
@@ -47,11 +40,43 @@ from fastlife.shared_utils.resolver import resolve
 from .settings import Settings
 
 if TYPE_CHECKING:
-    from .registry import AppRegistry  # coverage: ignore
+    from fastlife.services.templates import (
+        AbstractTemplateRendererFactory,  # coverage: ignore; coverage: ignore
+    )
+
+    from .registry import AppRegistry, LocaleNegociator  # coverage: ignore
 
 log = logging.getLogger(__name__)
 VENUSIAN_CATEGORY = "fastlife"
 
+venusian_ignored_item = str | Callable[[str], bool]
+
+
+class ConfigurationError(Exception):
+    """
+    Error raised during configuration, to avoid errors at runtime.
+    """
+
+
+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."""
+
 
 class Configurator:
     """
@@ -64,7 +89,7 @@ class Configurator:
 
     def __init__(self, settings: Settings) -> None:
         """
-        :param settings: Application settings.
+        :param settings: application settings.
         """
         registry_cls = resolve(settings.registry_class)
         self.registry = registry_cls(settings)
@@ -73,70 +98,80 @@ class Configurator:
         self.middlewares: list[Tuple[Type[AbstractMiddleware], Any]] = []
         self.exception_handlers: list[Tuple[int | Type[Exception], Any]] = []
         self.mounts: list[Tuple[str, Path, str]] = []
+        self.tags: dict[str, OpenApiTag] = {}
+
+        self.api_title = "OpenAPI"
+        self.api_version = "v1"
+        self.api_description: str = ""
+        self.api_summary: str | None = None
 
-        self.api_title = "FastAPI"
-        self.api_version = "1"
+        self._route_prefix: str = ""
+        self._routers: dict[str, Router] = defaultdict(Router)
 
-        self.router = Router()
         self.scanner = venusian.Scanner(fastlife=self)
         self.include("fastlife.views")
         self.include("fastlife.middlewares")
 
-    def get_asgi_app(self) -> FastAPI:
+    @property
+    def _current_router(self) -> Router:
+        return self._routers[self._route_prefix]
+
+    def build_asgi_app(self) -> FastAPI:
         """
-        Get the app after configuration in order to start after beeing configured.
+        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,
+            summary=self.api_summary,
             dependencies=[Depends(check_csrf())],
             docs_url=self.registry.settings.api_swagger_ui_url,
             redoc_url=self.registry.settings.api_redocs_url,
+            openapi_tags=[tag.model_dump(by_alias=True) for tag in self.tags.values()]
+            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 prefix, router in self._routers.items():
+            app.include_router(router, prefix=prefix)
 
         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 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) -> "Configurator":
+    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.
 
@@ -152,6 +187,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
@@ -160,12 +197,60 @@ 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:
+        """Install a locale negociator for the app."""
+        self.registry.locale_negociator = locale_negociator
         return self
 
-    def set_api_documentation_info(self, title: str, version: str) -> Self:
+    def add_translation_dirs(self, locales_dir: str) -> Self:
+        """
+        Add a translation directory for localization.
+
+        Usually, the locales is a directory from a package and has to be
+        passed with a `:` separator: {package_name}:locales.
+
+        :param locales_dir: the directory contains local inside a python package.
+        """
+        self.registry.localizer.load(locales_dir)
+        return self
+
+    def set_api_documentation_info(
+        self,
+        title: str,
+        version: str,
+        description: str,
+        summary: str | None = None,
+    ) -> Self:
+        """
+        Set your api documentation title for application that expose an API.
+
+        :param title: OpenAPI documentation title
+        :param version: OpenAPI api version
+        :param description: OpenAPI documentation description
+        :param summary: OpenAPI documentation summary
+        """
         self.api_title = title
         self.api_version = version
+        self.api_description = description
+        self.api_summary = summary
+        return self
+
+    def add_open_tag(self, tag: OpenApiTag) -> Self:
+        """Register a tag description in the documentation."""
+        if tag.name in self.tags:
+            raise ConfigurationError(f"Tag {tag.name} can't be registered twice.")
+        self.tags[tag.name] = tag
         return self
 
     def add_middleware(
@@ -185,14 +270,14 @@ class Configurator:
         *,
         permission: str | None = None,
         status_code: int | None = None,
-        tags: List[Union[str, Enum]] | None = None,
+        tags: list[str | Enum] | None = None,
         summary: str | None = None,
         description: str | None = None,
         response_description: str = "Successful Response",
         # responses: Dict[Union[int, str], Dict[str, Any]] | None = None,
         deprecated: bool | None = None,
-        methods: List[str] | None = None,
-        operation_id: Optional[str] = None,
+        methods: list[str] | None = None,
+        operation_id: str | None = None,
         # response_model: Any = Default(None),
         response_model_include: IncEx | None = None,
         response_model_exclude: IncEx | None = None,
@@ -208,12 +293,12 @@ class Configurator:
         # generate_unique_id_function: Callable[[APIRoute], str] = Default(
         #     generate_unique_id
         # ),
-    ) -> "Configurator":
+    ) -> Self:
         """
         Add an API 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
+        {func}`fastlife.config.configurator.configure` has to be used to
         inject routes inside a method and call the add_route method.
 
         This route has to be used to add API Route, by API, to expose it in the
@@ -222,7 +307,7 @@ class Configurator:
         To add a route that serve HTML user the method {meth}`Configurator.add_route`
 
         :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.
+            {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.
@@ -230,13 +315,13 @@ class Configurator:
             :attr:`fastlife.config.settings.Settings.check_permission` function.
 
         :param methods: restrict route to a list of http methods.
-        :param description: description for the route.
-        :param summary: summary for the route.
-        :param response_description: description for the response.
+        :param description:OpenAPI description for the route.
+        :param summary: OpenAPI summary for the route.
+        :param response_description: OpenAPI description for the response.
         :param operation_id: OpenAPI optional unique string used to identify an
             operation.
-        :param tags: openapi tags for the route.
-        :param deprecated: mark the route as deprecated.
+        :param tags: OpenAPI tags for the route.
+        :param deprecated: OpenAPI deprecated annotation for the route.
 
         :param response_model_include: customize fields list to include in repsonse.
         :param response_model_exclude: customize fields list to exclude in repsonse.
@@ -252,11 +337,11 @@ class Configurator:
 
         :return: the configurator.
         """
-        dependencies: List[DependsType] = []
+        dependencies: list[DependsType] = []
         if permission:
             dependencies.append(Depends(self.registry.check_permission(permission)))
 
-        self.router.add_api_route(
+        self._current_router.add_api_route(
             path,
             endpoint,
             # response_model=response_model,
@@ -291,40 +376,21 @@ class Configurator:
         endpoint: Callable[..., Any],
         *,
         permission: str | None = None,
+        template: str | None = None,
         status_code: int | None = None,
-        # tags: List[Union[str, Enum]] | None = None,
-        # summary: Optional[str] = None,
-        # description: Optional[str] = None,
-        # response_description: str = "Successful Response",
-        # responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
-        # deprecated: Optional[bool] = None,
-        methods: List[str] | None = None,
-        # operation_id: Optional[str] = None,
-        # response_model: Any = Default(None),
-        # response_model_include: Optional[IncEx] = None,
-        # response_model_exclude: Optional[IncEx] = None,
-        # response_model_by_alias: bool = True,
-        # response_model_exclude_unset: bool = False,
-        # response_model_exclude_defaults: bool = False,
-        # response_model_exclude_none: bool = False,
-        # include_in_schema: bool = True,
-        # response_class: Union[Type[Response], DefaultPlaceholder] = Default(
-        #     HTMLResponse
-        # ),
-        # openapi_extra: Optional[Dict[str, Any]] = None,
-        # generate_unique_id_function: Callable[[APIRoute], str] = Default(
-        #     generate_unique_id
-        # ),
-    ) -> "Configurator":
+        methods: list[str] | None = None,
+    ) -> Self:
         """
         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.
+        Fastlife does not use the FastAPI decorator to attach routes, instead the
+        decorator {func}`@configure <fastlife.config.configurator.configure>` has to
+        be used to inject routes inside a method and call the add_route method.
+        Or the decorator {func}`@view_config <fastlife.config.views.view_config>`
+        can decorate view functions.
 
         :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.
+            {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.
@@ -334,41 +400,39 @@ class Configurator:
         :param methods: restrict route to a list of http methods.
         :return: the configurator.
         """
-        dependencies: List[DependsType] = []
+        dependencies: list[DependsType] = []
         if permission:
             dependencies.append(Depends(self.registry.check_permission(permission)))
 
-        self.router.add_api_route(
+        if template:
+
+            def render(
+                request: Request,
+                resp: Annotated[Response | Mapping[str, Any], Depends(endpoint)],
+            ) -> Response:
+                if isinstance(resp, Response):
+                    return resp
+                return request.registry.get_renderer(template)(request).render(
+                    template,
+                    params=resp,
+                )
+
+            endpoint = render
+
+        self._current_router.add_api_route(
             path,
             endpoint,
-            # response_model=response_model,
             status_code=status_code,
-            # tags=tags,
             dependencies=dependencies,
-            # summary=summary,
-            # description=description,
-            # response_description=response_description,
-            # responses=responses,
-            # deprecated=deprecated,
             methods=methods,
-            # operation_id=operation_id,
-            # response_model_include=response_model_include,
-            # response_model_exclude=response_model_exclude,
-            # response_model_by_alias=response_model_by_alias,
-            # response_model_exclude_unset=response_model_exclude_unset,
-            # response_model_exclude_defaults=response_model_exclude_defaults,
-            # response_model_exclude_none=response_model_exclude_none,
             include_in_schema=False,
-            # response_class=response_class,
             name=name,
-            # openapi_extra=openapi_extra,
-            # generate_unique_id_function=generate_unique_id_function,
         )
         return self
 
     def add_static_route(
         self, route_path: str, directory: Path, name: str = "static"
-    ) -> "Configurator":
+    ) -> Self:
         """
         Mount a directory to an http endpoint.
 
@@ -382,17 +446,65 @@ class Configurator:
         return self
 
     def add_exception_handler(
-        self, status_code_or_exc: int | Type[Exception], handler: Any
-    ) -> "Configurator":
-        """Add an exception handler the application."""
+        self,
+        status_code_or_exc: int | Type[Exception],
+        handler: Any,
+        *,
+        template: str | None = None,
+        status_code: int = 500,
+    ) -> Self:
+        """
+        Add an exception handler the application.
+
+        """
 
         def exception_handler(request: BaseRequest, exc: Exception) -> Any:
-            req = Request(self.registry, request)
-            return handler(req, exc)
+            request = Request(self.registry, request)
+            resp = handler(request, exc)
+            if isinstance(resp, Response):
+                return resp
+
+            if not template:
+                raise RuntimeError(
+                    "No template set for "
+                    f"{exc.__module__}:{exc.__class__.__qualname__} but "
+                    f"{handler.__module__}:{handler.__qualname__} "
+                    "did not return a Response"
+                )
+
+            return request.registry.get_renderer(template)(request).render(
+                template,
+                params=resp,
+                status_code=status_code,
+            )
 
         self.exception_handlers.append((status_code_or_exc, exception_handler))
         return self
 
+    def add_renderer(
+        self, file_ext: str, renderer: "AbstractTemplateRendererFactory"
+    ) -> Self:
+        """
+        Add a render for a given file extension.
+
+        :param file_ext: the file extention of your templates.
+        :param renderer: the renderer that will render the template.
+        """
+        # we don't want to expose the renderer publicly as mutable
+        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],

fastlife/config/exceptions.py

@@ -0,0 +1,41 @@
+from typing import Any, Callable
+
+import venusian
+
+from .configurator import VENUSIAN_CATEGORY, Configurator
+
+
+def exception_handler(
+    exception: type[Exception],
+    *,
+    template: str | None = None,
+    status_code: int | None = None,
+) -> Callable[..., Any]:
+    """
+    A decorator function to add an exception handler in the app.
+
+    :param methods: restrict route to a list of http methods.
+
+    :return: the configuration callback.
+    """
+
+    def configure(
+        wrapped: Callable[..., Any],
+    ) -> Callable[..., Any]:
+        def callback(
+            scanner: venusian.Scanner, name: str, ob: Callable[..., Any]
+        ) -> None:
+            if not hasattr(scanner, VENUSIAN_CATEGORY):
+                return  # coverage: ignore
+            config: Configurator = getattr(scanner, VENUSIAN_CATEGORY)
+            config.add_exception_handler(
+                exception,
+                wrapped,
+                template=template,
+                **({} if status_code is None else {"status_code": status_code}),
+            )
+
+        venusian.attach(wrapped, callback, category=VENUSIAN_CATEGORY)  # type: ignore
+        return wrapped
+
+    return configure

fastlife/config/registry.py

@@ -1,18 +1,30 @@
-from typing import TYPE_CHECKING, Annotated
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Annotated, Callable
 
 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.templating.renderer import (  # coverage: ignore
+    from fastlife.services.templates import (  # coverage: ignore
         AbstractTemplateRendererFactory,  # coverage: ignore
     )  # coverage: ignore
 
 from .settings import Settings
 
+LocaleNegociator = Callable[[Request], str]
+
+
+def _default_negociator(settings: Settings) -> LocaleNegociator:
+    def locale_negociator(request: FastAPIRequest) -> str:
+        return settings.default_locale
+
+    return locale_negociator
+
 
 class AppRegistry:
     """
@@ -21,16 +33,23 @@ class AppRegistry:
     """
 
     settings: Settings
-    renderer: "AbstractTemplateRendererFactory"
+    renderers: Mapping[str, "AbstractTemplateRendererFactory"]
     check_permission: CheckPermission
+    locale_negociator: LocaleNegociator
+    localizer: LocalizerFactory
 
     def __init__(self, settings: Settings) -> None:
-        # Abtract class resolved for dependency injection
-        TemplateRenderer = resolve(settings.template_renderer_class)
-
         self.settings = settings
-        self.renderer = TemplateRenderer(settings)
         self.check_permission = resolve(settings.check_permission)
+        self.locale_negociator = _default_negociator(self.settings)
+        self.renderers = {}
+        self.localizer = LocalizerFactory()
+
+    def get_renderer(self, template: str) -> "AbstractTemplateRendererFactory":
+        for key, val in self.renderers.items():
+            if template.endswith(key):
+                return val
+        raise RuntimeError(f"No renderer registered for template {template}")
 
 
 def get_registry(request: Request) -> AppRegistry: