jararaca 0.3.11a16__py3-none-any.whl → 0.4.0a19__py3-none-any.whl

jararaca/persistence/utilities.py

@@ -1,5 +1,10 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import asyncio
 import logging
+import math
 from datetime import UTC, date, datetime
 from functools import reduce
 from typing import (
@@ -29,6 +34,7 @@ from jararaca.persistence.base import (
     BaseEntity,
     recursive_get_dict,
 )
+from jararaca.persistence.interceptors.aiosqa_interceptor import use_session
 from jararaca.persistence.sort_filter import (
     FilterModel,
     FilterRuleApplier,
@@ -61,7 +67,7 @@ class DatedEntity(BaseEntity):
         DateTime(timezone=True), nullable=False, default=nowutc
     )
     updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), nullable=False, default=nowutc
+        DateTime(timezone=True), nullable=False, default=nowutc, onupdate=nowutc
     )
 
 
@@ -283,11 +289,13 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
     def __init__(
         self,
         entity_type: Type[QUERY_ENTITY_T],
-        session_provider: Callable[[], AsyncSession],
-        filters_functions: list[QueryInjector],
+        session_provider: Callable[[], AsyncSession] = use_session,
+        filters_functions: list[QueryInjector] = [],
+        *,
         unique: bool = False,
         sort_rule_applier: SortRuleApplier | None = None,
         filter_rule_applier: FilterRuleApplier | None = None,
+        base_statement: Select[Tuple[QUERY_ENTITY_T]] | None = None,
     ) -> None:
         self.entity_type: type[QUERY_ENTITY_T] = entity_type
         self.session_provider = session_provider
@@ -295,6 +303,7 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
         self.unique = unique
         self.sort_rule_applier = sort_rule_applier
         self.filter_rule_applier = filter_rule_applier
+        self.base_statement = base_statement
 
     @property
     def session(self) -> AsyncSession:
@@ -303,9 +312,20 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
     async def query(
         self,
         filter: QUERY_FILTER_T,
+        *,
         interceptors: list[
             Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
         ] = [],
+        base_statement: (
+            Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
+            | Select[Tuple[QUERY_ENTITY_T]]
+            | None
+        ) = None,
+        final_listing_statement: (
+            Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
+            | None
+        ) = None,
+        total_type: Literal["total_over", "count_subquery"] = "total_over",
     ) -> "Paginated[QUERY_ENTITY_T]":
         """
         Executes a query with the provided filter and interceptors.
@@ -316,8 +336,15 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
             Paginated[QUERY_ENTITY_T]: A paginated result containing the items and metadata.
         """
 
+        initial_statement = self.base_statement or select(self.entity_type)
+
+        if base_statement is not None and callable(base_statement):
+            initial_statement = base_statement(initial_statement)
+        elif base_statement is not None and isinstance(base_statement, Select):
+            initial_statement = base_statement
+
         tier_one_filtered_query = self.generate_filtered_query(
-            filter, select(self.entity_type)
+            filter, initial_statement
         )
 
         tier_two_filtered_query = reduce(
@@ -340,30 +367,56 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
                 )
             )
 
-        unpaginated_total = (
-            await self.session.execute(
-                select(func.count()).select_from(tier_two_filtered_query.subquery())
-            )
-        ).scalar_one()
+        if final_listing_statement is not None:
+            tier_two_filtered_query = final_listing_statement(tier_two_filtered_query)
 
-        paginated_query = tier_two_filtered_query.limit(filter.page_size).offset(
-            (filter.page) * filter.page_size
-        )
+        if total_type == "total_over":
+            # Use window function for total count (single query)
+            paginated_query = tier_two_filtered_query.add_columns(
+                func.count().over().label("total_count")
+            )
+            paginated_query = paginated_query.limit(filter.page_size).offset(
+                (filter.page) * filter.page_size
+            )
 
-        paginated_total = (
-            await self.session.execute(
-                select(func.count()).select_from(paginated_query.subquery())
+            result = await self.session.execute(paginated_query)
+            result = self.judge_unique(result)
+            rows = result.all()
+
+            if rows:
+                unpaginated_total = rows[0].total_count
+                result_scalars = [row[0] for row in rows]
+            else:
+                result_scalars = []
+                unpaginated_total = 0
+        else:  # total_type == "count_subquery"
+            # Use separate count query (two queries)
+            paginated_query = tier_two_filtered_query.limit(filter.page_size).offset(
+                (filter.page) * filter.page_size
             )
-        ).scalar_one()
 
-        result = await self.session.execute(paginated_query)
-        result_scalars = list(self.judge_unique(result).scalars().all())
+            result = await self.session.execute(paginated_query)
+            result = self.judge_unique(result)
+            result_scalars = list(result.scalars())
+
+            # Always fetch total with separate query
+            unpaginated_total = (
+                await self.session.execute(
+                    tier_two_filtered_query.with_only_columns(
+                        func.count(self.entity_type.id)
+                    ).order_by(None)
+                    if issubclass(self.entity_type, IdentifiableEntity)
+                    else select(func.count()).select_from(
+                        tier_two_filtered_query.subquery()
+                    )
+                )
+            ).scalar_one()
 
         return Paginated(
             items=result_scalars,
-            total=paginated_total,
+            total=len(result_scalars),
             unpaginated_total=unpaginated_total,
-            total_pages=int(unpaginated_total / filter.page_size) + 1,
+            total_pages=math.ceil(unpaginated_total / filter.page_size),
         )
 
     def judge_unique(

jararaca/presentation/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later

jararaca/presentation/decorators.py

@@ -1,7 +1,12 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import inspect
 from contextlib import contextmanager
 from contextvars import ContextVar
 from functools import wraps
-from typing import Any, Awaitable, Callable, Literal, Protocol, TypeVar, cast
+from typing import Any, Awaitable, Callable, Literal, Mapping, Protocol, TypeVar
 
 from fastapi import APIRouter
 from fastapi import Depends as DependsF
@@ -15,12 +20,13 @@ from jararaca.reflect.controller_inspect import (
     ControllerMemberReflect,
     inspect_controller,
 )
+from jararaca.reflect.decorators import FUNC_OR_TYPE_T, StackableDecorator
 
+DECORATED_TYPE = TypeVar("DECORATED_TYPE", bound=Any)
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
-DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
 
 
-ControllerOptions = dict[str, Any]
+ControllerOptions = Mapping[str, Any]
 
 
 class RouterFactory(Protocol):
@@ -28,20 +34,25 @@ class RouterFactory(Protocol):
     def __call__(self, lifecycle: AppLifecycle, instance: Any) -> APIRouter: ...
 
 
-class RestController:
+class RestController(StackableDecorator):
     REST_CONTROLLER_ATTR = "__rest_controller__"
 
     def __init__(
         self,
         path: str = "",
+        *,
         options: ControllerOptions | None = None,
         middlewares: list[type[HttpMiddleware]] = [],
         router_factory: RouterFactory | None = None,
+        class_inherits_decorators: bool = True,
+        methods_inherit_decorators: bool = True,
     ) -> None:
         self.path = path
         self.options = options
         self.router_factory = router_factory
         self.middlewares = middlewares
+        self.class_inherits_decorators = class_inherits_decorators
+        self.methods_inherit_decorators = methods_inherit_decorators
 
     def get_router_factory(
         self,
@@ -50,12 +61,15 @@ class RestController:
             raise Exception("Router factory is not set")
         return self.router_factory
 
-    def __call__(self, cls: type[DECORATED_CLASS]) -> type[DECORATED_CLASS]:
+    def post_decorated(self, subject: FUNC_OR_TYPE_T) -> None:
 
         def router_factory(
             lifecycle: AppLifecycle,
-            instance: DECORATED_CLASS,
+            instance: FUNC_OR_TYPE_T,
         ) -> APIRouter:
+            assert inspect.isclass(
+                subject
+            ), "RestController can only be applied to classes"
             dependencies: list[Depends] = []
 
             for self_middleware_type in self.middlewares:
@@ -64,13 +78,19 @@ class RestController:
                 )
                 dependencies.append(Depends(middleware_instance.intercept))
 
-            for middlewares_by_hook in UseMiddleware.get_middlewares(instance):
+            class_middlewares = UseMiddleware.get_all_from_type(
+                subject, self.class_inherits_decorators
+            )
+            for middlewares_by_hook in class_middlewares:
                 middleware_instance = lifecycle.container.get_by_type(
                     middlewares_by_hook.middleware
                 )
                 dependencies.append(Depends(middleware_instance.intercept))
 
-            for dependency in UseDependency.get_dependencies(instance):
+            class_dependencies = UseDependency.get_all_from_type(
+                subject, self.class_inherits_decorators
+            )
+            for dependency in class_dependencies:
                 dependencies.append(DependsF(dependency.dependency))
 
             router = APIRouter(
@@ -79,15 +99,23 @@ class RestController:
                 **(self.options or {}),
             )
 
-            controller, members = inspect_controller(cls)
+            controller, members = inspect_controller(subject)
 
             router_members = [
                 (name, mapping, member)
                 for name, member in members.items()
                 if (
-                    mapping := (
-                        HttpMapping.get_http_mapping(member.member_function)
-                        or WebSocketEndpoint.get(member.member_function)
+                    mapping := HttpMapping.get_bound_from_method(
+                        subject,
+                        name,
+                        self.methods_inherit_decorators,
+                        last=True,
+                    )
+                    or WebSocketEndpoint.get_bound_from_method(
+                        subject,
+                        name,
+                        self.methods_inherit_decorators,
+                        last=True,
                     )
                 )
                 is not None
@@ -97,17 +125,22 @@ class RestController:
 
             for name, mapping, member in router_members:
                 route_dependencies: list[Depends] = []
-                for middlewares_by_hook in UseMiddleware.get_middlewares(
-                    getattr(instance, name)
-                ):
+
+                method_middlewares = UseMiddleware.get_all_from_method(
+                    subject, name, self.methods_inherit_decorators
+                )
+                for middlewares_by_hook in method_middlewares:
                     middleware_instance = lifecycle.container.get_by_type(
                         middlewares_by_hook.middleware
                     )
                     route_dependencies.append(Depends(middleware_instance.intercept))
 
-                for dependency in UseDependency.get_dependencies(
-                    getattr(instance, name)
-                ):
+                method_dependencies = UseDependency.get_all_from_method(
+                    subject,
+                    name,
+                    self.methods_inherit_decorators,
+                )
+                for dependency in method_dependencies:
                     route_dependencies.append(DependsF(dependency.dependency))
 
                 instance_method = getattr(instance, name)
@@ -141,21 +174,6 @@ class RestController:
 
         self.router_factory = router_factory
 
-        RestController.register(cls, self)
-
-        return cls
-
-    @staticmethod
-    def register(cls: type[DECORATED_CLASS], controller: "RestController") -> None:
-        setattr(cls, RestController.REST_CONTROLLER_ATTR, controller)
-
-    @staticmethod
-    def get_controller(cls: type[DECORATED_CLASS]) -> "RestController | None":
-        if not hasattr(cls, RestController.REST_CONTROLLER_ATTR):
-            return None
-
-        return cast(RestController, getattr(cls, RestController.REST_CONTROLLER_ATTR))
-
 
 Options = dict[str, Any]
 
@@ -170,9 +188,8 @@ ResponseType = Literal[
 ]
 
 
-class HttpMapping:
+class HttpMapping(StackableDecorator):
 
-    HTTP_MAPPING_ATTR = "__http_mapping__"
     ORDER_COUNTER = 0
 
     def __init__(
@@ -190,24 +207,20 @@ class HttpMapping:
         HttpMapping.ORDER_COUNTER += 1
         self.order = HttpMapping.ORDER_COUNTER
 
-    def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
-
-        HttpMapping.register(func, self)
-
-        return func
+    @classmethod
+    def decorator_key(cls) -> "type[HttpMapping]":
+        return HttpMapping
 
-    @staticmethod
-    def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
+    # def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
+    #     HttpMapping.register(func, self)
 
-    @staticmethod
-    def get_http_mapping(func: DECORATED_FUNC) -> "HttpMapping | None":
+    #     return func
 
-        if not hasattr(func, HttpMapping.HTTP_MAPPING_ATTR):
-            return None
+    # @staticmethod
+    # def register(func: DECORATED_FUNC, mapping: "HttpMapping") -> None:
 
-        return cast(HttpMapping, getattr(func, HttpMapping.HTTP_MAPPING_ATTR))
+    #     setattr(func, HttpMapping.HTTP_MAPPING_ATTR, mapping)
 
 
 class Post(HttpMapping):
@@ -265,52 +278,46 @@ class Patch(HttpMapping):
         super().__init__("PATCH", path, options, response_type)
 
 
-class UseMiddleware:
-
-    __MIDDLEWARES_ATTR__ = "__middlewares__"
+class UseMiddleware(StackableDecorator):
 
     def __init__(self, middleware: type[HttpMiddleware]) -> None:
         self.middleware = middleware
 
-    def __call__(self, subject: DECORATED_FUNC) -> DECORATED_FUNC:
-
-        UseMiddleware.register(subject, self)
-
-        return subject
-
-    @staticmethod
-    def register(subject: DECORATED_FUNC, middleware: "UseMiddleware") -> None:
-        middlewares = getattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, [])
-        middlewares.append(middleware)
-        setattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, middlewares)
-
-    @staticmethod
-    def get_middlewares(subject: DECORATED_FUNC) -> list["UseMiddleware"]:
-        return getattr(subject, UseMiddleware.__MIDDLEWARES_ATTR__, [])
-
 
-class UseDependency:
-
-    __DEPENDENCY_ATTR__ = "__dependencies__"
+class UseDependency(StackableDecorator):
 
     def __init__(self, dependency: Any) -> None:
         self.dependency = dependency
 
-    def __call__(self, subject: DECORATED_FUNC) -> DECORATED_FUNC:
 
-        UseDependency.register(subject, self)
+def compose_route_decorators(
+    *decorators: UseMiddleware | UseDependency,
+    reverse: bool = False,
+) -> Callable[[DECORATED_TYPE], DECORATED_TYPE]:
+    """
+    Compose multiple route decorators (middlewares/dependencies) into a single decorator.
 
-        return subject
+    Args:
+        *decorators (UseMiddleware | UseDependency): The decorators to compose.
+        reverse (bool): Whether to apply the decorators in reverse order. Warning: This may affect the order of middleware execution.
 
-    @staticmethod
-    def register(subject: DECORATED_FUNC, dependency: "UseDependency") -> None:
-        dependencies = getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
-        dependencies.append(dependency)
-        setattr(subject, UseDependency.__DEPENDENCY_ATTR__, dependencies)
+    Returns:
+        Callable[[DECORATED_TYPE], DECORATED_TYPE]: A single decorator that applies all the given decorators.
 
-    @staticmethod
-    def get_dependencies(subject: DECORATED_FUNC) -> list["UseDependency"]:
-        return getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
+    Example:
+        IsWorkspaceAdmin = compose_route_decorators(
+            UseMiddleware(AuthMiddleware),
+            UseMiddleware(IsWorkspaceScoped),
+            UseMiddleware(RequiresAdminRole),
+        )
+    """
+
+    def composed_decorator(func: DECORATED_TYPE) -> DECORATED_TYPE:
+        for decorator in reversed(decorators) if reverse else decorators:
+            func = decorator(func)
+        return func
+
+    return composed_decorator
 
 
 def wraps_with_member_data(
@@ -330,11 +337,6 @@ def wraps_with_member_data(
 
             return await func(*args, **kwargs)
 
-    # Copy metadata from the original function to the wrapper
-    # for attr in dir(func):
-    #     if not attr.startswith("__"):
-    #         setattr(wrapper, attr, getattr(func, attr))
-
     return wrapper
 
 

jararaca/presentation/exceptions.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from fastapi import Request, Response, WebSocket
+
+
+class PresentationException(Exception):
+    """Base exception for presentation layer errors."""
+
+    def __init__(
+        self,
+        *,
+        original_exception: Exception,
+        request: Request | None = None,
+        response: Response | None = None,
+        websocket: WebSocket | None = None,
+    ) -> None:
+        super().__init__(str(original_exception))
+        self.original_exception = original_exception
+        self.request = request
+        self.response = response
+        self.websocket = websocket

jararaca/presentation/hooks.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from contextlib import contextmanager
 from typing import Any, ContextManager, Generator, Type
 

jararaca/presentation/http_microservice.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from dataclasses import dataclass, field
 from typing import Any, AsyncGenerator, Callable, Protocol