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

jararaca/reflect/decorators.py

@@ -0,0 +1,238 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Callable, Self, TypedDict, TypeVar, cast
+
+DECORATED_T = TypeVar("DECORATED_T", bound="Callable[..., Any] | type")
+
+
+S = TypeVar("S", bound="StackableDecorator")
+
+
+class DecoratorMetadata(TypedDict):
+    decorators: "list[StackableDecorator]"
+    decorators_by_type: "dict[Any, list[StackableDecorator]]"
+
+
+class StackableDecorator:
+    _ATTR_NAME: str = "__jararaca_stackable_decorator__"
+
+    def __call__(self, subject: DECORATED_T) -> DECORATED_T:
+        self.pre_decorated(subject)
+        self.register(subject, self)
+        self.post_decorated(subject)
+        return subject
+
+    @classmethod
+    def decorator_key(cls) -> Any:
+        return cls
+
+    @classmethod
+    def get_or_set_metadata(cls, subject: Any) -> DecoratorMetadata:
+        if cls._ATTR_NAME not in subject.__dict__:
+            setattr(
+                subject,
+                cls._ATTR_NAME,
+                DecoratorMetadata(decorators=[], decorators_by_type={}),
+            )
+        return cast(DecoratorMetadata, getattr(subject, cls._ATTR_NAME))
+
+    @classmethod
+    def get_metadata(cls, subject: Any) -> DecoratorMetadata | None:
+        if hasattr(subject, cls._ATTR_NAME):
+            return cast(DecoratorMetadata, getattr(subject, cls._ATTR_NAME))
+        return None
+
+    @classmethod
+    def register(cls, subject: Any, decorator: "StackableDecorator") -> None:
+        if not cls._ATTR_NAME:
+            raise NotImplementedError("Subclasses must define _ATTR_NAME")
+
+        metadata = cls.get_or_set_metadata(subject)
+        metadata["decorators"].append(decorator)
+        metadata["decorators_by_type"].setdefault(cls.decorator_key(), []).append(
+            decorator
+        )
+
+    @classmethod
+    def get(cls, subject: Any) -> list[Self]:
+        metadata = cls.get_metadata(subject)
+        if metadata is None:
+            return []
+
+        if cls is StackableDecorator:
+            return cast(list[Self], metadata["decorators"])
+        else:
+            return cast(
+                list[Self], metadata["decorators_by_type"].get(cls.decorator_key(), [])
+            )
+
+    @classmethod
+    def extract_list(cls, subject: Any) -> list[Self]:
+        metadata = cls.get_metadata(subject)
+        if metadata is None:
+            return []
+
+        if cls is StackableDecorator:
+            return cast(list[Self], metadata["decorators"])
+        else:
+            return cast(
+                list[Self], metadata["decorators_by_type"].get(cls.decorator_key(), [])
+            )
+
+    @classmethod
+    def get_fisrt(cls, subject: Any) -> Self | None:
+        decorators = cls.get(subject)
+        if decorators:
+            return decorators[0]
+        return None
+
+    @classmethod
+    def get_last(cls, subject: Any) -> Self | None:
+        decorators = cls.get(subject)
+        if decorators:
+            return decorators[-1]
+        return None
+
+    def pre_decorated(self, subject: DECORATED_T) -> None:
+        """
+        Hook method called before the subject is decorated.
+        Can be overridden by subclasses to perform additional setup.
+        """
+
+    def post_decorated(self, subject: DECORATED_T) -> None:
+        """
+        Hook method called after the subject has been decorated.
+        Can be overridden by subclasses to perform additional setup.
+        """
+
+    @classmethod
+    def get_all_from_type(cls, subject_type: type, inherit: bool = True) -> list[Self]:
+        """
+        Retrieve all decorators of this type from the given class type.
+        """
+        return resolve_class_decorators(subject_type, cls, inherit)
+
+    @classmethod
+    def get_bound_from_type(
+        cls, subject_type: type, inherit: bool = True, last: bool = False
+    ) -> Self | None:
+        """
+        Retrieve the first or last decorator of this type from the given class type.
+        """
+        return resolve_bound_class_decorators(subject_type, cls, inherit, last=last)
+
+    @classmethod
+    def get_all_from_method(
+        cls, cls_subject_type: type, method_name: str, inherit: bool = True
+    ) -> list[Self]:
+        """
+        Retrieve all decorators of this type from the given method.
+        """
+        return resolve_method_decorators(cls_subject_type, method_name, cls, inherit)
+
+    @classmethod
+    def get_bound_from_method(
+        cls,
+        cls_subject_type: type,
+        method_name: str,
+        inherit: bool = True,
+        last: bool = True,
+    ) -> Self | None:
+        """
+        Retrieve the first or last decorator of this type from the given method.
+        """
+        return resolve_bound_method_decorator(
+            cls_subject_type, method_name, cls, inherit, last=last
+        )
+
+
+def resolve_class_decorators(
+    subject: Any, decorator_cls: type[S], inherit: bool = True
+) -> list[S]:
+    """
+    Resolve decorators for a class or instance, optionally inheriting from base classes.
+    """
+    if not inherit:
+        return decorator_cls.get(subject)
+
+    # If subject is an instance, get its class
+    cls = subject if isinstance(subject, type) else type(subject)
+
+    collected: list[S] = []
+    # Iterate MRO in reverse to apply base class decorators first
+    for base in reversed(cls.mro()):
+        collected.extend(decorator_cls.get(base))
+
+    return collected
+
+
+def resolve_bound_class_decorators(
+    subject: Any, decorator_cls: type[S], inherit: bool = True, last: bool = False
+) -> S | None:
+    """
+    Retrieve the first or last decorator of a given type from a class or instance,
+    optionally inheriting from base classes.
+    """
+    decorators = resolve_class_decorators(subject, decorator_cls, inherit)
+    if not decorators:
+        return None
+    return decorators[-1] if last else decorators[0]
+
+
+def resolve_method_decorators(
+    cls: type,
+    method_name: str,
+    decorator_cls: type[S],
+    inherit: bool = True,
+) -> list[S]:
+    """
+    Resolve decorators for a method, optionally inheriting from base classes.
+    """
+    if not inherit:
+        method = getattr(cls, method_name, None)
+        if method:
+            return decorator_cls.get(method)
+        return []
+
+    collected: list[S] = []
+    # Iterate MRO in reverse to apply base class decorators first
+    for base in reversed(cls.mro()):
+        if method_name in base.__dict__:
+            method = base.__dict__[method_name]
+            # Handle staticmethod/classmethod wrappers if necessary?
+            # Usually decorators are on the underlying function or the wrapper.
+            # getattr(cls, name) returns the bound/unbound method.
+            # base.__dict__[name] returns the raw object (function or descriptor).
+
+            # If it's a staticmethod object, it has no __dict__ usually, but we attach attributes to it?
+            # The decorator runs on the function BEFORE it becomes a staticmethod.
+            # So the attribute should be on the function object.
+
+            # However, when we access it via base.__dict__[method_name], we might get the staticmethod object.
+            # We need to unwrap it if possible.
+
+            if isinstance(method, (staticmethod, classmethod)):
+                method = method.__func__
+
+            collected.extend(decorator_cls.get(method))
+
+    return collected
+
+
+def resolve_bound_method_decorator(
+    cls: type,
+    method_name: str,
+    decorator_cls: type[S],
+    inherit: bool = True,
+    last: bool = False,
+) -> S | None:
+    """
+    Retrieve the first or last decorator of a given type from a method,
+    optionally inheriting from base classes.
+    """
+    decorators = resolve_method_decorators(cls, method_name, decorator_cls, inherit)
+    if not decorators:
+        return None
+    return decorators[-1] if last else decorators[0]

jararaca/reflect/metadata.py

@@ -1,23 +1,32 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from contextlib import contextmanager, suppress
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Mapping, TypeVar, Union, cast
+from typing import Any, Awaitable, Callable, Generator, Mapping, TypeVar, Union
+
+from jararaca.reflect.decorators import StackableDecorator
 
 DECORATED = TypeVar("DECORATED", bound=Union[Callable[..., Awaitable[Any]], type])
 
 
-@dataclass
-class ControllerInstanceMetadata:
+@dataclass(frozen=True)
+class TransactionMetadata:
     value: Any
-    inherited: bool
+    """The value of the metadata."""
+
+    inherited_from_controller: bool
+    """Whether the metadata was inherited from a parent class."""
 
 
-metadata_context: ContextVar[Mapping[str, ControllerInstanceMetadata]] = ContextVar(
+metadata_context: ContextVar[Mapping[str, TransactionMetadata]] = ContextVar(
     "metadata_context"
 )
 
 
-def get_metadata(key: str) -> ControllerInstanceMetadata | None:
+def get_metadata(key: str) -> TransactionMetadata | None:
     return metadata_context.get({}).get(key)
 
 
@@ -28,12 +37,14 @@ def get_metadata_value(key: str, default: Any | None = None) -> Any:
     return metadata.value
 
 
-def get_all_metadata() -> Mapping[str, ControllerInstanceMetadata]:
+def get_all_metadata() -> Mapping[str, TransactionMetadata]:
     return metadata_context.get({})
 
 
 @contextmanager
-def provide_metadata(metadata: Mapping[str, ControllerInstanceMetadata]) -> Any:
+def start_transaction_metadata_context(
+    metadata: Mapping[str, TransactionMetadata],
+) -> Generator[None, Any, None]:
 
     current_metadata = metadata_context.get({})
 
@@ -45,23 +56,21 @@ def provide_metadata(metadata: Mapping[str, ControllerInstanceMetadata]) -> Any:
             metadata_context.reset(token)
 
 
-class SetMetadata:
+@contextmanager
+def start_providing_metadata(
+    **metadata: Any,
+) -> Generator[None, Any, None]:
+
+    with start_transaction_metadata_context(
+        {
+            key: TransactionMetadata(value=value, inherited_from_controller=False)
+            for key, value in metadata.items()
+        }
+    ):
+        yield
+
+
+class SetMetadata(StackableDecorator):
     def __init__(self, key: str, value: Any) -> None:
         self.key = key
         self.value = value
-
-    METATADA_LIST = "__metadata_list__"
-
-    @staticmethod
-    def register_metadata(cls: DECORATED, value: "SetMetadata") -> None:
-        metadata_list = getattr(cls, SetMetadata.METATADA_LIST, [])
-        metadata_list.append(value)
-        setattr(cls, SetMetadata.METATADA_LIST, metadata_list)
-
-    @staticmethod
-    def get(cls: DECORATED) -> "list[SetMetadata]":
-        return cast(list[SetMetadata], getattr(cls, SetMetadata.METATADA_LIST, []))
-
-    def __call__(self, cls: DECORATED) -> DECORATED:
-        SetMetadata.register_metadata(cls, self)
-        return cls

jararaca/rpc/__init__.py

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

jararaca/rpc/http/__init__.py

@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# HTTP RPC Module - Complete REST Client Implementation
+"""
+This module provides a complete REST client implementation with support for:
+- HTTP method decorators (@Get, @Post, @Put, @Patch, @Delete)
+- Request parameter decorators (@Query, @Header, @PathParam, @Body, @FormData, @File)
+- Configuration decorators (@Timeout, @Retry, @ContentType)
+- Authentication middleware (BearerTokenAuth, BasicAuth, ApiKeyAuth)
+- Caching and response middleware
+- Request/response hooks for customization
+"""
+
+from .backends.httpx import HTTPXHttpRPCAsyncBackend
+from .decorators import (  # HTTP Method decorators; Request parameter decorators; Configuration decorators; Client builder and core classes; Authentication classes; Middleware and hooks; Configuration classes; Data structures; Error handlers; Exceptions
+    ApiKeyAuth,
+    AuthenticationMiddleware,
+    BasicAuth,
+    BearerTokenAuth,
+    Body,
+    CacheMiddleware,
+    ContentType,
+    Delete,
+    File,
+    FormData,
+    Get,
+    GlobalHttpErrorHandler,
+    Header,
+    HttpMapping,
+    HttpRpcClientBuilder,
+    HttpRPCRequest,
+    HttpRPCResponse,
+    Patch,
+    PathParam,
+    Post,
+    Put,
+    Query,
+    RequestAttribute,
+    RequestHook,
+    ResponseHook,
+    ResponseMiddleware,
+    RestClient,
+    Retry,
+    RetryConfig,
+    RouteHttpErrorHandler,
+    RPCRequestNetworkError,
+    RPCUnhandleError,
+    Timeout,
+    TimeoutException,
+)
+
+__all__ = [
+    # HTTP Method decorators
+    "Get",
+    "Post",
+    "Put",
+    "Patch",
+    "Delete",
+    # Request parameter decorators
+    "Query",
+    "Header",
+    "PathParam",
+    "Body",
+    "FormData",
+    "File",
+    # Configuration decorators
+    "Timeout",
+    "Retry",
+    "ContentType",
+    # Client builder and core classes
+    "RestClient",
+    "HttpRpcClientBuilder",
+    "HttpMapping",
+    "RequestAttribute",
+    # Authentication classes
+    "BearerTokenAuth",
+    "BasicAuth",
+    "ApiKeyAuth",
+    "AuthenticationMiddleware",
+    # Middleware and hooks
+    "CacheMiddleware",
+    "ResponseMiddleware",
+    "RequestHook",
+    "ResponseHook",
+    # Configuration classes
+    "RetryConfig",
+    # Data structures
+    "HttpRPCRequest",
+    "HttpRPCResponse",
+    # Error handlers
+    "GlobalHttpErrorHandler",
+    "RouteHttpErrorHandler",
+    # Exceptions
+    "RPCRequestNetworkError",
+    "RPCUnhandleError",
+    "TimeoutException",
+    # Backend
+    "HTTPXHttpRPCAsyncBackend",
+]

jararaca/rpc/http/backends/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# HTTP RPC Backends
+"""
+Backend implementations for HTTP RPC clients.
+"""
+
+from .httpx import HTTPXHttpRPCAsyncBackend
+
+__all__ = [
+    "HTTPXHttpRPCAsyncBackend",
+]

jararaca/rpc/http/backends/httpx.py

@@ -1,3 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import time
 from urllib.parse import urljoin
 
 import httpx
@@ -7,34 +12,63 @@ from jararaca.rpc.http.decorators import (
     HttpRPCRequest,
     HttpRPCResponse,
     RPCRequestNetworkError,
+    TimeoutException,
 )
 
 
 class HTTPXHttpRPCAsyncBackend(HttpRPCAsyncBackend):
 
-    def __init__(self, prefix_url: str = ""):
+    def __init__(self, prefix_url: str = "", default_timeout: float = 30.0):
         self.prefix_url = prefix_url
+        self.default_timeout = default_timeout
 
     async def request(
         self,
         request: HttpRPCRequest,
     ) -> HttpRPCResponse:
 
-        async with httpx.AsyncClient() as client:
+        start_time = time.time()
+
+        # Prepare timeout
+        timeout = (
+            request.timeout if request.timeout is not None else self.default_timeout
+        )
+
+        # Prepare request kwargs
+        request_kwargs = {
+            "method": request.method,
+            "url": urljoin(self.prefix_url, request.url),
+            "headers": request.headers,
+            "params": request.query_params,
+            "timeout": timeout,
+        }
 
+        # Handle different content types
+        if request.form_data and request.files:
+            # Multipart form data with files
+            request_kwargs["data"] = request.form_data
+            request_kwargs["files"] = request.files
+        elif request.form_data:
+            # Form data only
+            request_kwargs["data"] = request.form_data
+        elif request.body:
+            # Raw body content
+            request_kwargs["content"] = request.body
+
+        async with httpx.AsyncClient() as client:
             try:
-                response = await client.request(
-                    method=request.method,
-                    url=urljoin(self.prefix_url, request.url),
-                    headers=request.headers,
-                    params=request.query_params,
-                    content=request.body,
-                )
+                response = await client.request(**request_kwargs)  # type: ignore[arg-type]
+
+                elapsed_time = time.time() - start_time
 
                 return HttpRPCResponse(
                     status_code=response.status_code,
                     data=response.content,
+                    headers=dict(response.headers),
+                    elapsed_time=elapsed_time,
                 )
+            except httpx.TimeoutException as err:
+                raise TimeoutException(f"Request timed out: {err}") from err
             except httpx.NetworkError as err:
                 raise RPCRequestNetworkError(
                     request=request, backend_request=err.request

jararaca/rpc/http/backends/otel.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from opentelemetry import baggage, trace
 from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator