pydantic-rpc 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

pydantic_rpc/decorators.py

@@ -0,0 +1,138 @@
+"""Decorators for adding protobuf options to RPC methods."""
+
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+from functools import wraps
+
+from .options import OptionMetadata, OPTION_METADATA_ATTR
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def http_option(
+    method: str,
+    path: str,
+    body: Optional[str] = None,
+    response_body: Optional[str] = None,
+    additional_bindings: Optional[List[Dict[str, Any]]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator to add google.api.http option to an RPC method.
+
+    Args:
+        method: HTTP method (GET, POST, PUT, DELETE, PATCH)
+        path: URL path template (e.g., "/v1/books/{id}")
+        body: Request body mapping (e.g., "*" for entire body)
+        response_body: Response body mapping (specific field to return)
+        additional_bindings: List of additional HTTP bindings
+
+    Example:
+        @http_option(method="GET", path="/v1/books/{id}")
+        async def get_book(self, request: GetBookRequest) -> Book:
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        # Get or create option metadata
+        if not hasattr(func, OPTION_METADATA_ATTR):
+            setattr(func, OPTION_METADATA_ATTR, OptionMetadata())
+
+        metadata: OptionMetadata = getattr(func, OPTION_METADATA_ATTR)
+
+        # Set HTTP option
+        metadata.set_http_option(
+            method=method,
+            path=path,
+            body=body,
+            response_body=response_body,
+            additional_bindings=additional_bindings,
+        )
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve the metadata on the wrapper
+        setattr(wrapper, OPTION_METADATA_ATTR, metadata)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def proto_option(name: str, value: Any) -> Callable[[F], F]:
+    """
+    Decorator to add a generic protobuf option to an RPC method.
+
+    Args:
+        name: Option name (e.g., "deprecated", "idempotency_level")
+        value: Option value
+
+    Example:
+        @proto_option("deprecated", True)
+        @proto_option("idempotency_level", "IDEMPOTENT")
+        async def old_method(self, request: Request) -> Response:
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        # Get or create option metadata
+        if not hasattr(func, OPTION_METADATA_ATTR):
+            setattr(func, OPTION_METADATA_ATTR, OptionMetadata())
+
+        metadata: OptionMetadata = getattr(func, OPTION_METADATA_ATTR)
+
+        # Add proto option
+        metadata.add_proto_option(name=name, value=value)
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve the metadata on the wrapper
+        setattr(wrapper, OPTION_METADATA_ATTR, metadata)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def get_method_options(method: Callable) -> Optional[OptionMetadata]:
+    """
+    Get option metadata from a method.
+
+    Args:
+        method: The method to get options from
+
+    Returns:
+        OptionMetadata if present, None otherwise
+    """
+    return getattr(method, OPTION_METADATA_ATTR, None)
+
+
+def has_http_option(method: Callable) -> bool:
+    """
+    Check if a method has an HTTP option.
+
+    Args:
+        method: The method to check
+
+    Returns:
+        True if the method has an HTTP option, False otherwise
+    """
+    metadata = get_method_options(method)
+    return metadata is not None and metadata.http_option is not None
+
+
+def has_proto_options(method: Callable) -> bool:
+    """
+    Check if a method has any proto options.
+
+    Args:
+        method: The method to check
+
+    Returns:
+        True if the method has proto options, False otherwise
+    """
+    metadata = get_method_options(method)
+    return metadata is not None and len(metadata.proto_options) > 0

pydantic_rpc/options.py

@@ -0,0 +1,134 @@
+"""Protocol Buffer options support for pydantic-rpc."""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class HttpBinding(BaseModel):
+    """HTTP binding configuration for a single HTTP method."""
+
+    method: str = Field(..., description="HTTP method (get, post, put, delete, patch)")
+    path: Optional[str] = Field(None, description="URL path template")
+    body: Optional[str] = Field(None, description="Request body mapping")
+    response_body: Optional[str] = Field(None, description="Response body mapping")
+
+    def to_proto_dict(self) -> Dict[str, Any]:
+        """Convert to protobuf option format."""
+        result = {}
+        if self.path:
+            result[self.method.lower()] = self.path
+        if self.body:
+            result["body"] = self.body
+        if self.response_body:
+            result["response_body"] = self.response_body
+        return result
+
+
+class HttpOption(BaseModel):
+    """Google API HTTP option configuration."""
+
+    method: str = Field(..., description="Primary HTTP method")
+    path: str = Field(..., description="Primary URL path template")
+    body: Optional[str] = Field(None, description="Request body mapping")
+    response_body: Optional[str] = Field(None, description="Response body mapping")
+    additional_bindings: List[Dict[str, Any]] = Field(
+        default_factory=list, description="Additional HTTP bindings"
+    )
+
+    def to_proto_string(self) -> str:
+        """Convert to protobuf option string format."""
+        lines = []
+        lines.append("option (google.api.http) = {")
+
+        # Primary binding
+        lines.append(f'  {self.method.lower()}: "{self.path}"')
+
+        # Body mapping
+        if self.body:
+            lines.append(f'  body: "{self.body}"')
+
+        # Response body mapping
+        if self.response_body:
+            lines.append(f'  response_body: "{self.response_body}"')
+
+        # Additional bindings
+        for binding in self.additional_bindings:
+            lines.append("  additional_bindings {")
+            for key, value in binding.items():
+                if key == "body":
+                    lines.append(f'    {key}: "{value}"')
+                else:
+                    lines.append(f'    {key}: "{value}"')
+            lines.append("  }")
+
+        lines.append("};")
+        return "\n".join(lines)
+
+
+class ProtoOption(BaseModel):
+    """Generic protocol buffer option."""
+
+    name: str = Field(..., description="Option name")
+    value: Any = Field(..., description="Option value")
+
+    def to_proto_string(self) -> str:
+        """Convert to protobuf option string format."""
+        if isinstance(self.value, bool):
+            value_str = "true" if self.value else "false"
+        elif isinstance(self.value, str):
+            # Check if it's an enum value (no quotes) or string literal (quotes)
+            if self.value.isupper() or "_" in self.value:
+                # Likely an enum value
+                value_str = self.value
+            else:
+                value_str = f'"{self.value}"'
+        else:
+            value_str = str(self.value)
+
+        return f"option {self.name} = {value_str};"
+
+
+class OptionMetadata(BaseModel):
+    """Metadata container for method/service options."""
+
+    http_option: Optional[HttpOption] = None
+    proto_options: List[ProtoOption] = Field(default_factory=list)
+
+    def add_proto_option(self, name: str, value: Any) -> None:
+        """Add a generic proto option."""
+        self.proto_options.append(ProtoOption(name=name, value=value))
+
+    def set_http_option(
+        self,
+        method: str,
+        path: str,
+        body: Optional[str] = None,
+        response_body: Optional[str] = None,
+        additional_bindings: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Set the HTTP option configuration."""
+        self.http_option = HttpOption(
+            method=method,
+            path=path,
+            body=body,
+            response_body=response_body,
+            additional_bindings=additional_bindings or [],
+        )
+
+    def to_proto_strings(self) -> List[str]:
+        """Convert all options to protobuf strings."""
+        result = []
+
+        # Add HTTP option first if present
+        if self.http_option:
+            result.append(self.http_option.to_proto_string())
+
+        # Add other proto options
+        for option in self.proto_options:
+            result.append(option.to_proto_string())
+
+        return result
+
+
+# Option metadata attribute name used on methods
+OPTION_METADATA_ATTR = "__pydantic_rpc_options__"