jararaca 0.2.37a12__py3-none-any.whl → 0.4.0a5__py3-none-any.whl

jararaca/scheduler/decorators.py

@@ -1,63 +1,124 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import inspect
-from typing import Any, Callable, TypeVar, cast
+from dataclasses import dataclass
+from types import FunctionType
+from typing import Any, Awaitable, Callable, TypeVar
+
+from jararaca.reflect.controller_inspect import (
+    ControllerMemberReflect,
+    inspect_controller,
+)
+from jararaca.reflect.decorators import StackableDecorator
 
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
 
 
-class ScheduledAction:
-    SCHEDULED_ACTION_ATTR = "__scheduled_action__"
+class ScheduledAction(StackableDecorator):
 
     def __init__(
         self,
         cron: str,
         allow_overlap: bool = False,
-        exclusive: bool = False,
+        exclusive: bool = True,
         timeout: int | None = None,
         exception_handler: Callable[[BaseException], None] | None = None,
+        name: str | None = None,
     ) -> None:
         """
         :param cron: A string representing the cron expression for the scheduled action.
         :param allow_overlap: A boolean indicating if the scheduled action should new executions even if the previous one is still running.
         :param exclusive: A boolean indicating if the scheduled action should be executed in one instance of the application. (Requires a distributed lock provided by a backend)
+        :param exception_handler: A callable that will be called when an exception is raised during the execution of the scheduled action.
+        :param timeout: An integer representing the timeout for the scheduled action in seconds. If the scheduled action takes longer than this time, it will be terminated.
+        :param name: An optional name for the scheduled action, used for filtering which actions to run.
         """
         self.cron = cron
+        """
+        A string representing the cron expression for the scheduled action.
+        """
+
         self.allow_overlap = allow_overlap
+        """
+        A boolean indicating if the scheduled action should new executions even if the previous one is still running.
+        """
+
         self.exclusive = exclusive
+        """
+        A boolean indicating if the scheduled action should be executed
+        in one instance of the application. (Requires a distributed lock provided by a backend)
+        """
+
         self.exception_handler = exception_handler
+        """
+        A callable that will be called when an exception is raised during the execution of the scheduled action.
+        """
+
         self.timeout = timeout
+        """
+        An integer representing the timeout for the scheduled action in seconds.
+        If the scheduled action takes longer than this time, it will be terminated.
+        """
 
-    def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
-        ScheduledAction.register(func, self)
-        return func
+        self.name = name
+        """
+        An optional name for the scheduled action, used for filtering which actions to run.
+        """
 
     @staticmethod
-    def register(func: DECORATED_FUNC, scheduled_action: "ScheduledAction") -> None:
-        setattr(func, ScheduledAction.SCHEDULED_ACTION_ATTR, scheduled_action)
+    def get_function_id(
+        func: Callable[..., Any],
+    ) -> str:
+        """
+        Get the function ID of the scheduled action.
+        This is used to identify the scheduled action in the message broker.
+        """
+        return f"{func.__module__}.{func.__qualname__}"
 
-    @staticmethod
-    def get_scheduled_action(func: DECORATED_FUNC) -> "ScheduledAction | None":
-        if not hasattr(func, ScheduledAction.SCHEDULED_ACTION_ATTR):
-            return None
 
-        return cast(
-            ScheduledAction, getattr(func, ScheduledAction.SCHEDULED_ACTION_ATTR)
-        )
+@dataclass(frozen=True)
+class ScheduledActionData:
+    spec: ScheduledAction
+    controller_member: ControllerMemberReflect
+    callable: Callable[..., Awaitable[None]]
 
-    @staticmethod
-    def get_type_scheduled_actions(
-        instance: Any,
-    ) -> list[tuple[Callable[..., Any], "ScheduledAction"]]:
 
-        members = inspect.getmembers(instance, predicate=inspect.ismethod)
+def get_type_scheduled_actions(
+    instance: Any,
+) -> list[ScheduledActionData]:
+
+    _, member_metadata_map = inspect_controller(instance.__class__)
+
+    members: list[tuple[str, FunctionType]] = []
+    for name, value in inspect.getmembers_static(
+        instance, predicate=inspect.isfunction
+    ):
+
+        members.append((name, value))
 
-        scheduled_actions: list[tuple[Callable[..., Any], "ScheduledAction"]] = []
+    scheduled_actions: list[ScheduledActionData] = []
 
-        for _, member in members:
-            scheduled_action = ScheduledAction.get_scheduled_action(member)
+    for name, member in members:
+        scheduled_action = ScheduledAction.get_last(member)
 
-            if scheduled_action is None:
-                continue
+        if scheduled_action is None:
+            continue
 
-            scheduled_actions.append((member, scheduled_action))
+        if name not in member_metadata_map:
+            raise Exception(
+                f"Member '{name}' is not a valid controller member in '{instance.__class__.__name__}'"
+            )
+
+        member_metadata = member_metadata_map[name]
+
+        scheduled_actions.append(
+            ScheduledActionData(
+                callable=member,
+                spec=scheduled_action,
+                controller_member=member_metadata,
+            )
+        )
 
-        return scheduled_actions
+    return scheduled_actions

jararaca/scheduler/types.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from pydantic import BaseModel
+
+
+class DelayedMessageData(BaseModel):
+    message_topic: str
+    dispatch_time: int
+    payload: bytes

jararaca/tools/app_config/__init__.py

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

jararaca/tools/app_config/decorators.py

@@ -1,31 +1,19 @@
-from typing import Any, Type, TypeVar, cast
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Type, TypeVar
 
 from pydantic import BaseModel
 
 from jararaca.core.providers import Token
+from jararaca.reflect.decorators import StackableDecorator
 
 DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
 
 
-class RequiresConfig:
-
-    REQUIRE_CONFIG_ATTR = "__requires_config__"
+class RequiresConfig(StackableDecorator):
 
     def __init__(self, token: Token[Any], config: Type[BaseModel]):
         self.config = config
         self.token = token
-
-    @staticmethod
-    def register(cls: Type[DECORATED_CLASS], config: "RequiresConfig") -> None:
-        setattr(cls, RequiresConfig.REQUIRE_CONFIG_ATTR, config)
-
-    @staticmethod
-    def get(cls: Type[DECORATED_CLASS]) -> "RequiresConfig | None":
-        if not hasattr(cls, RequiresConfig.REQUIRE_CONFIG_ATTR):
-            return None
-
-        return cast(RequiresConfig, getattr(cls, RequiresConfig.REQUIRE_CONFIG_ATTR))
-
-    def __call__(self, cls: Type[DECORATED_CLASS]) -> Type[DECORATED_CLASS]:
-        RequiresConfig.register(cls, self)
-        return cls

jararaca/tools/app_config/interceptor.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import logging
 import os
 from contextlib import asynccontextmanager
@@ -7,9 +11,9 @@ from pydantic import BaseModel
 
 from jararaca.core.providers import Token
 from jararaca.microservice import (
-    AppContext,
     AppInterceptor,
     AppInterceptorWithLifecycle,
+    AppTransactionContext,
     Container,
     Microservice,
 )
@@ -40,7 +44,9 @@ class AppConfigurationInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
         self.config_parser = config_parser
 
     @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def intercept(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
         yield
 
     def instance_basemodels(self, basemodel_type: Type[BaseModel]) -> BaseModel:
@@ -54,7 +60,7 @@ class AppConfigurationInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
             *[
                 (config.token, config.config)
                 for controller in app.controllers
-                if (config := RequiresConfig.get(controller))
+                if (config := RequiresConfig.get_last(controller))
             ],
         ]
 
@@ -88,7 +94,7 @@ class AppConfigurationInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
 
         yield
 
-        logger.info("finalizando")
+        logger.debug("finalizando")
 
 
 class AppConfigValidationError(Exception):

jararaca/tools/typescript/__init__.py

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

jararaca/tools/typescript/decorators.py

@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Callable, TypeVar
+
+from pydantic import BaseModel
+
+from jararaca.reflect.decorators import StackableDecorator
+
+DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
+
+
+class QueryEndpoint(StackableDecorator):
+    """
+    Decorator to mark a endpoint function as a query endpoint for Typescript generation.
+    """
+
+    def __init__(self, has_infinite_query: bool = False) -> None:
+        """
+        Initialize the QueryEndpoint decorator.
+
+        Args:
+            has_infinite_query: Whether the query endpoint supports infinite queries.
+            Important:
+            - Make sure a PaginatedQuery child instance is on the first argument
+            - Make sure the endpoint is a Patch (recommended) or Put method
+            - Make sure the endpoint returns a Paginated[T]
+        """
+        self.has_infinite_query = has_infinite_query
+
+    @staticmethod
+    def extract_query_endpoint(func: Any) -> "QueryEndpoint | None":
+        """
+        Check if the function is marked as a query endpoint.
+        """
+        return QueryEndpoint.get_last(func)
+
+
+class MutationEndpoint(StackableDecorator):
+    """
+    Decorator to mark a endpoint function as a mutation endpoint for Typescript generation.
+    """
+
+    def __init__(self) -> None: ...
+
+    @staticmethod
+    def is_mutation(func: Any) -> bool:
+        """
+        Check if the function is marked as a mutation endpoint.
+        """
+        return MutationEndpoint.get_last(func) is not None
+
+
+BASEMODEL_T = TypeVar("BASEMODEL_T", bound=BaseModel)
+
+
+class SplitInputOutput(StackableDecorator):
+    """
+    Decorator to mark a Pydantic model to generate separate Input and Output TypeScript interfaces.
+
+    Input interface: Used for API inputs (mutations/queries), handles optional fields with defaults
+    Output interface: Used for API outputs, represents the complete object structure
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def is_split_model(cls: type) -> bool:
+        """
+        Check if the Pydantic model is marked for split interface generation.
+        """
+        return SplitInputOutput.get_last(cls) is not None
+
+
+class ExposeType:
+    """
+    Decorator to explicitly expose types for TypeScript interface generation.
+
+    Use this decorator to include types in the generated TypeScript output without
+    needing them as request/response bodies or indirect dependencies.
+
+    Example:
+        @ExposeType()
+        class UserRole(BaseModel):
+            id: str
+            name: str
+
+        # This ensures UserRole interface is generated even if it's not
+        # directly referenced in any REST endpoint
+    """
+
+    METADATA_KEY = "__jararaca_expose_type__"
+    _exposed_types: set[type] = set()
+
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self, cls: type[BASEMODEL_T]) -> type[BASEMODEL_T]:
+        """
+        Decorate the type to mark it for explicit TypeScript generation.
+        """
+        setattr(cls, self.METADATA_KEY, True)
+        ExposeType._exposed_types.add(cls)
+        return cls
+
+    @staticmethod
+    def is_exposed_type(cls: type) -> bool:
+        """
+        Check if the type is marked for explicit exposure.
+        """
+        return getattr(cls, ExposeType.METADATA_KEY, False)
+
+    @staticmethod
+    def get_all_exposed_types() -> set[type]:
+        """
+        Get all types that have been marked for explicit exposure.
+        """
+        return ExposeType._exposed_types.copy()