fastlifeweb 0.11.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

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,27 @@ 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 = {
+            f".{settings.jinjax_file_ext}": resolve(
+                "fastlife.adapters.jinjax.renderer:JinjaxTemplateRenderer"
+            )(settings),
+        }
+        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:

fastlife/config/resources.py

@@ -0,0 +1,216 @@
+"""
+API Resources declaration using a decorator.
+
+
+```{literalinclude} ../../../../tests/fastlife_app/views/api/foos.py
+
+```
+
+"""
+
+from typing import Any, Callable
+
+import venusian
+from fastapi.types import IncEx
+
+from .configurator import (
+    VENUSIAN_CATEGORY,
+    ConfigurationError,
+    Configurator,
+    ExternalDocs,
+    OpenApiTag,
+)
+
+
+def resource(
+    name: str,
+    *,
+    path: str | None = None,
+    collection_path: str | None = None,
+    description: str | None = None,
+    external_docs: ExternalDocs | None = None,
+) -> Callable[..., Any]:
+    """
+    A decorator to build an OpenAPI set of api grouped under a tag.
+
+    This approach makes the resource the umbrella for all API methods that
+    modify resources of that type, covering operations on both collections and
+    individual items.
+
+    The typical set of api route to manage resources is:
+
+      * `POST /items`: a POST on a `collection_path` that create an item
+      * `GET /items?filters=...&page=...`: a GET on a `collection_path` to list or
+        even search items. Usually it returns partial item fields.
+      * `GET /items/{id}`: Return the item with all its fields.
+      * `PATCH /items/{id}`: An update of a single item on the resource `path`.
+      * `DELETE /items/{id}`: Remove a single item from the collection on the `path`.
+
+    You may implement more methods: `collection_get`, `collection_post`,
+    `collection_put`, `collection_patch`, `collection_delete`, `collection_head`,
+    `collection_options`, `get`, `post`, `put`, `patch`, `delete`, `head`, `options`
+    will autmatically be bound to verb collection path or path.
+
+    Note that there is no abstract class that declare this method, this is done by
+    introspection while returning the configuration method
+    {meth}`fastlife.config.configurator.Configurator.include`
+    """
+    tag = name
+
+    def configure(
+        wrapped: Callable[..., Any],
+    ) -> Callable[..., Any]:
+        def callback(scanner: venusian.Scanner, name: str, ob: type[Any]) -> None:
+            if not hasattr(scanner, VENUSIAN_CATEGORY):
+                return  # coverage: ignore
+
+            config: Configurator = getattr(scanner, VENUSIAN_CATEGORY)
+            if description:
+                config.add_open_tag(
+                    OpenApiTag(
+                        name=tag, description=description, externalDocs=external_docs
+                    )
+                )
+
+            api = ob()
+
+            def bind_config(
+                bind_config: Configurator,
+                method: str,
+                bind_path: str | None,
+                endpoint: Any,
+            ) -> None:
+                if bind_path is None:
+                    prefix = "collection_" if method.startswith("collection_") else ""
+                    raise ConfigurationError(f"{prefix}path not set on resource {tag}")
+
+                bind_config.add_api_route(
+                    name=f"{method}_{tag}",
+                    path=bind_path,
+                    endpoint=endpoint,
+                    tags=[tag],
+                    methods=[method.split("_").pop()],
+                    permission=getattr(endpoint, "permission"),
+                    status_code=getattr(endpoint, "status_code"),
+                    summary=getattr(endpoint, "summary"),
+                    description=getattr(endpoint, "description"),
+                    response_description=getattr(endpoint, "response_description"),
+                    deprecated=getattr(endpoint, "deprecated"),
+                    operation_id=getattr(endpoint, "operation_id"),
+                    response_model_include=getattr(endpoint, "response_model_include"),
+                    response_model_exclude=getattr(endpoint, "response_model_exclude"),
+                    response_model_by_alias=getattr(
+                        endpoint, "response_model_by_alias"
+                    ),
+                    response_model_exclude_unset=getattr(
+                        endpoint, "response_model_exclude_unset"
+                    ),
+                    response_model_exclude_defaults=getattr(
+                        endpoint, "response_model_exclude_defaults"
+                    ),
+                    response_model_exclude_none=getattr(
+                        endpoint, "response_model_exclude_none"
+                    ),
+                    include_in_schema=getattr(endpoint, "include_in_schema"),
+                    openapi_extra=getattr(endpoint, "openapi_extra"),
+                )
+
+            for method in dir(ob):
+                match method:
+                    case (
+                        "collection_get"
+                        | "collection_post"
+                        | "collection_put"
+                        | "collection_patch"
+                        | "collection_delete"
+                        | "collection_head"
+                        | "collection_options"
+                    ):
+                        bind_config(
+                            config, method, collection_path, getattr(api, method)
+                        )
+                    case (
+                        "get" | "post" | "put" | "patch" | "delete" | "head" | "options"
+                    ):
+                        bind_config(config, method, path, getattr(api, method))
+                    case _:
+                        ...
+
+        venusian.attach(wrapped, callback, category=VENUSIAN_CATEGORY)  # type: ignore
+        return wrapped
+
+    return configure
+
+
+def resource_view(
+    permission: str | None = None,
+    status_code: int | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    response_description: str = "Successful Response",
+    deprecated: bool | None = None,
+    methods: list[str] | None = None,
+    operation_id: str | None = None,
+    response_model_include: IncEx | None = None,
+    response_model_exclude: IncEx | None = 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,
+    openapi_extra: dict[str, Any] | None = None,
+) -> Callable[..., Any]:
+    """ "
+    Decorator to use on a method of a class decorated with {func}`resource` in order
+    to add OpenAPI information.
+
+    This decorator has an effect if the decoratated method is named `collection_get`,
+    `collection_post`, `collection_put`, `collection_patch`, `collection_delete`,
+    `collection_head`, `collection_options`, `get`, `post`, `put`, `patch`, `delete`,
+    `head` or `options`.
+
+    :param permission: a permission to validate by the
+        :attr:`fastlife.config.settings.Settings.check_permission` function.
+    :param status_code: returned status_code
+    :param summary: OpenAPI summary for the route.
+    :param description:OpenAPI description 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: OpenAPI deprecated annotation for the route.
+    :param openapi_extra: OpenAPI documentation extra fields.
+    :param include_in_schema: Expose or not the route in the OpenAPI schema and
+    documentation.
+
+    :param response_model_include: customize fields list to include in repsonse.
+    :param response_model_exclude: customize fields list to exclude in repsonse.
+    :param response_model_by_alias: serialize fields by alias or by name if False.
+    :param response_model_exclude_unset: exclude fields that are not explicitly
+        set in response.
+    :param response_model_exclude_defaults: exclude default value of response
+        fields.
+    :param response_model_exclude_none: exclude fields instead of serialize to
+        null value.
+    """
+
+    def wrapped(fn: Any) -> Any:
+        fn.permission = permission
+        fn.status_code = status_code
+        fn.summary = summary
+        fn.description = description
+        fn.response_description = response_description
+        fn.deprecated = deprecated
+        fn.methods = methods
+        fn.operation_id = operation_id
+        fn.response_model_include = response_model_include
+        fn.response_model_exclude = response_model_exclude
+        fn.response_model_by_alias = response_model_by_alias
+        fn.response_model_exclude_unset = response_model_exclude_unset
+        fn.response_model_exclude_defaults = response_model_exclude_defaults
+        fn.response_model_exclude_none = response_model_exclude_none
+        fn.include_in_schema = include_in_schema
+        fn.openapi_extra = openapi_extra
+        return fn
+
+    return wrapped

fastlife/config/settings.py

@@ -21,21 +21,22 @@ class Settings(BaseSettings):
 
     fastlife_route_prefix: str = Field(default="/_fl")
     """Route prefix used for fastlife internal views."""
-    template_search_path: str = Field(default="fastlife:templates")
+    template_search_path: str = Field(default="fastlife:components")
     """
-    list of directories where templates could be found by the template engine.
+    list of directories where components could be found by the template engine.
 
     the list is a comma separated string. The directory resolution is made from
-    a python module name. for instance `fastlife:templates` is the direcotry templates
+    a python module name. for instance `fastlife:components` is the directory components
     found in the fastlife package.
     """
     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"
+        default="fastlife.templates.renderer:JinjaxTemplateRenderer"
     )
     """
-    Implementation class for the :class:`fastlife.templatingAbstractTemplateRenderer`.
+    Implementation class for the
+    {class}`fastlife.templates.renderer.AbstractTemplateRenderer`.
     """
     form_data_model_prefix: str = Field(default="payload")
     """
@@ -46,6 +47,16 @@ class Settings(BaseSettings):
     Name of the html input field and for the http cookie for csrf token.
     """
 
+    default_locale: str = Field(default="en")
+    """
+    The default locale
+    """
+
+    jinjax_file_ext: str = Field(default="jinja")
+    """
+    JinjaX file extention.
+    """
+
     jinjax_use_cache: bool = Field(default=True)
     """
     JinjaX (the default template engine) setting use_cache.
@@ -59,7 +70,7 @@ class Settings(BaseSettings):
     Set to true while developing, set false for production.
     """
     jinjax_global_catalog_class: str = Field(
-        default="fastlife.templating.renderer:Constants"
+        default="fastlife.templates.constants:Constants"
     )
     """
     Set global constants accessible in every templates.
@@ -100,3 +111,9 @@ class Settings(BaseSettings):
 
     decode_reverse_proxy_headers: bool = Field(default=True)
     """Ensure that the request object has information based on http proxy headers."""
+
+    api_swagger_ui_url: str | None = Field(default=None)
+    """Path to the automatic API documentation using Swagger UI."""
+
+    api_redocs_url: str | None = Field(default=None)
+    """Path to the automatic API documentation using ReDoc."""

fastlife/config/views.py

@@ -0,0 +1,73 @@
+"""
+Configure views using a decorator.
+
+A simple usage:
+
+```python
+from typing import Annotated
+
+from fastapi import Response
+from fastlife import Template, template, view_config
+
+
+@view_config("hello_world", "/", methods=["GET"])
+async def hello_world(
+    template: Annotated[Template, template("HelloWorld.jinja")],
+) -> Response:
+    return template()
+```
+"""
+from typing import Any, Callable
+
+import venusian
+
+from .configurator import VENUSIAN_CATEGORY, Configurator
+
+
+def view_config(
+    name: str,
+    path: str,
+    *,
+    permission: str | None = None,
+    template: str | None = None,
+    status_code: int | None = None,
+    methods: list[str] | None = None,
+) -> Callable[..., Any]:
+    """
+    A decorator function to add a view in the app.
+
+    :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 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.
+
+    :return: the configuration callback.
+    """
+    view_name = name
+
+    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_route(
+                name=view_name,
+                path=path,
+                endpoint=ob,
+                permission=permission,
+                status_code=status_code,
+                methods=methods,
+                template=template,
+            )
+
+        venusian.attach(wrapped, callback, category=VENUSIAN_CATEGORY)  # type: ignore
+        return wrapped
+
+    return configure

fastlife/request/form_data.py

@@ -84,7 +84,7 @@ async def unflatten_mapping_form_data(
     request: Request, registry: Registry
 ) -> Mapping[str, Any]:
     """
-    Parse the :meth:`fastlife.request.request.form` and build a nested structure.
+    Parse the {meth}`fastlife.request.request.form` and build a nested structure.
     """
 
     form_data = await request.form()
@@ -113,7 +113,7 @@ 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.
+    Parse the {meth}`fastlife.request.request.form` and build a list of structure.
     """
     form_data = await request.form()
     # Could raise a value error !
@@ -124,11 +124,11 @@ 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`
+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`
+Fast API Dependency to deserialize a {meth}`fastlife.request.request.Request.form`
 to a list.
 """

fastlife/request/localizer.py

@@ -0,0 +1,13 @@
+from typing import Annotated
+
+from fastapi import Depends
+
+from fastlife.request.request import Request
+from fastlife.services.translations import Localizer as RequestLocalizer
+
+
+def get_localizer(request: Request) -> RequestLocalizer:
+    return request.registry.localizer(request)
+
+
+Localizer = Annotated[RequestLocalizer, Depends(get_localizer)]

fastlife/request/request.py

@@ -1,18 +1,22 @@
 """HTTP Request representation in a python object."""
+
 from typing import TYPE_CHECKING
 
-from fastapi import Request as BaseRequest
+from fastapi import Request as FastAPIRequest
 
 if TYPE_CHECKING:
     from fastlife.config.registry import AppRegistry  # coverage: ignore
 
 
-class Request(BaseRequest):
+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."""
 
-    def __init__(self, registry: "AppRegistry", request: BaseRequest) -> None:
+    def __init__(self, registry: "AppRegistry", request: FastAPIRequest) -> None:
         super().__init__(request.scope, request.receive)
         self.registry = registry
+        self.locale_name = registry.locale_negociator(self)

fastlife/routing/route.py

@@ -27,7 +27,7 @@ class Route(APIRoute):
     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.
+    {class}`fastlife.config.Registry` depenency injection.
     """
 
     def get_route_handler(

fastlife/routing/router.py

@@ -1,7 +1,7 @@
 """
 FastApi router for fastlife application.
 
-The aim of this router is get :class:`fastlife.routing.route.Route`
+The aim of this router is get {class}`fastlife.routing.route.Route`
 available in the FastApi request depency injection.
 """
 from typing import Any

fastlife/security/csrf.py

@@ -6,7 +6,7 @@ Fast life did not reinvent the wheel on CSRF Protection.
 It use the good old method. A CSRF token is saved in a cookie.
 Forms post the CSRF token, and the token in the cookies and the form must match
 to process the request, otherwise an exception
-:class:`fastlife.security.csrf.CSRFAttack` is raised.
+{class}`fastlife.security.csrf.CSRFAttack` is raised.
 
 The cookie named is configurabllefia the settings
 :attr:`fastlife.config.settings.Settings.csrf_token_name`

fastlife/security/policy.py

@@ -14,7 +14,7 @@ def check_permission(permission_name: str) -> CheckPermissionHook:
 
     When the check permission is properly set in the settings., the hook is called
     for every route added with a permission keyword.
-    :meth:`fastlife.config.configurator.Configurator.add_route`
+    {meth}`fastlife.config.configurator.Configurator.add_route`
 
     :param permission_name: a permission name set in a view to check access.
     :return: a function that raise http exceptions or any configured exception here.