pydantic-rpc 0.10.0__tar.gz → 0.11.0__tar.gz

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pydantic-rpc
-Version: 0.10.0
+Version: 0.11.0
 Summary: A Python library for building gRPC/ConnectRPC services with Pydantic models.
 Author: Yasushi Itoh
 Requires-Dist: annotated-types==0.7.0
@@ -62,9 +62,10 @@ class OlympicsLocationAgent:
 
 
 if __name__ == "__main__":
-    s = AsyncIOServer()
+    # New enhanced initialization API (optional - backward compatible)
+    s = AsyncIOServer(service=OlympicsLocationAgent(), port=50051)
     loop = asyncio.get_event_loop()
-    loop.run_until_complete(s.run(OlympicsLocationAgent()))
+    loop.run_until_complete(s.run())
 ```
 
 And here is an example of a simple Connect RPC service that exposes the same agent as an ASGI application:
@@ -106,8 +107,8 @@ class OlympicsLocationAgent:
         result = await self._agent.run(req.prompt())
         return result.data
 
-app = ASGIApp()
-app.mount(OlympicsLocationAgent())
+# New enhanced initialization API (optional - backward compatible)
+app = ASGIApp(service=OlympicsLocationAgent())
 
 ```
 
@@ -129,6 +130,17 @@ app.mount(OlympicsLocationAgent())
 - 🛠️ **Pre-generated Protobuf Files and Code:** Pre-generate proto files and corresponding code via the CLI. By setting the environment variable (PYDANTIC_RPC_SKIP_GENERATION), you can skip runtime generation.
 - 🤖 **MCP (Model Context Protocol) Support:** Expose your services as tools for AI assistants using the official MCP SDK, supporting both stdio and HTTP/SSE transports.
 
+## ⚠️ Important Notes for Connect-RPC
+
+When using Connect-RPC with ASGIApp:
+
+- **Endpoint Path Format**: Connect-RPC endpoints use CamelCase method names in the path: `/<package>.<service>/<Method>` (e.g., `/chat.v1.ChatService/SendMessage`)
+- **Content-Type**: Set `Content-Type: application/json` or `application/connect+json` for requests
+- **HTTP/2 Requirement**: Bidirectional streaming requires HTTP/2. Use Hypercorn instead of uvicorn for HTTP/2 support
+- **Testing**: Use [buf curl](https://buf.build/docs/ecosystem/cli/curl) for testing Connect-RPC endpoints with proper streaming support
+
+For detailed examples and testing instructions, see the [examples directory](examples/).
+
 ## 📦 Installation
 
 Install PydanticRPC via pip:
@@ -137,6 +149,54 @@ Install PydanticRPC via pip:
 pip install pydantic-rpc
 ```
 
+For CLI support with built-in server runners:
+
+```bash
+pip install pydantic-rpc-cli  # Includes hypercorn and gunicorn
+```
+
+## 🆕 Enhanced Features (v0.10.0+)
+
+**Note: All new features are fully backward compatible. Existing code continues to work without modification.**
+
+### Enhanced Initialization API
+All server classes now support optional initialization with services:
+
+```python
+# Traditional API (still works)
+server = AsyncIOServer()
+server.set_port(50051)
+await server.run(MyService())
+
+# New enhanced API (optional)
+server = AsyncIOServer(
+    service=MyService(),
+    port=50051,
+    package_name="my.package"
+)
+await server.run()
+
+# Same for ASGI/WSGI apps
+app = ASGIApp(service=MyService(), package_name="my.package")
+```
+
+### Error Handling with Decorators
+Automatically map exceptions to gRPC/Connect status codes:
+
+```python
+from pydantic_rpc import error_handler
+import grpc
+
+class MyService:
+    @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+    @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+    async def get_user(self, request: GetUserRequest) -> User:
+        # Exceptions are automatically converted to proper status codes
+        if request.id not in users_db:
+            raise KeyError(f"User {request.id} not found")
+        return users_db[request.id]
+```
+
 ## 🚀 Getting Started
 
 PydanticRPC supports two main protocols:
@@ -1090,15 +1150,40 @@ MCP endpoints will be available at:
 - SSE: `GET http://localhost:8000/mcp/sse`
 - Messages: `POST http://localhost:8000/mcp/messages/`
 
-### 🗄️ Protobuf file and code (Python files) generation using CLI
+### 🗄️ CLI Tool (pydantic-rpc-cli)
+
+The CLI tool provides powerful features for generating protobuf files and running servers. Install it separately:
+
+```bash
+pip install pydantic-rpc-cli
+```
+
+#### Generate Protobuf Files
 
-You can genereate protobuf files and code for a given module and a specified class using `pydantic-rpc` CLI command:
+```bash
+# Generate .proto file from a service class
+pydantic-rpc generate myapp.services.UserService --output ./proto/
+
+# Also compile to Python code
+pydantic-rpc generate myapp.services.UserService --compile
+```
+
+#### Run Servers Directly
+
+The CLI can run any type of server:
 
 ```bash
-pydantic-rpc a_module.py aClassName
+# Run as gRPC server (auto-detects async/sync)
+pydantic-rpc serve myapp.services.UserService --port 50051
+
+# Run as Connect-RPC with ASGI (HTTP/2, uses Hypercorn)
+pydantic-rpc serve myapp.services.UserService --asgi --port 8000
+
+# Run as Connect-RPC with WSGI (HTTP/1.1, uses Gunicorn)
+pydantic-rpc serve myapp.services.UserService --wsgi --port 8000 --workers 4
 ```
 
-Using this generated proto file and tools as `protoc`, `buf` and `BSR`, you could generate code for any desired language other than Python.
+Using the generated proto files with tools like `protoc`, `buf` and `BSR`, you can generate code for any desired language.
 
 
 ## 📖 Data Type Mapping

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/README.md

@@ -45,9 +45,10 @@ class OlympicsLocationAgent:
 
 
 if __name__ == "__main__":
-    s = AsyncIOServer()
+    # New enhanced initialization API (optional - backward compatible)
+    s = AsyncIOServer(service=OlympicsLocationAgent(), port=50051)
     loop = asyncio.get_event_loop()
-    loop.run_until_complete(s.run(OlympicsLocationAgent()))
+    loop.run_until_complete(s.run())
 ```
 
 And here is an example of a simple Connect RPC service that exposes the same agent as an ASGI application:
@@ -89,8 +90,8 @@ class OlympicsLocationAgent:
         result = await self._agent.run(req.prompt())
         return result.data
 
-app = ASGIApp()
-app.mount(OlympicsLocationAgent())
+# New enhanced initialization API (optional - backward compatible)
+app = ASGIApp(service=OlympicsLocationAgent())
 
 ```
 
@@ -112,6 +113,17 @@ app.mount(OlympicsLocationAgent())
 - 🛠️ **Pre-generated Protobuf Files and Code:** Pre-generate proto files and corresponding code via the CLI. By setting the environment variable (PYDANTIC_RPC_SKIP_GENERATION), you can skip runtime generation.
 - 🤖 **MCP (Model Context Protocol) Support:** Expose your services as tools for AI assistants using the official MCP SDK, supporting both stdio and HTTP/SSE transports.
 
+## ⚠️ Important Notes for Connect-RPC
+
+When using Connect-RPC with ASGIApp:
+
+- **Endpoint Path Format**: Connect-RPC endpoints use CamelCase method names in the path: `/<package>.<service>/<Method>` (e.g., `/chat.v1.ChatService/SendMessage`)
+- **Content-Type**: Set `Content-Type: application/json` or `application/connect+json` for requests
+- **HTTP/2 Requirement**: Bidirectional streaming requires HTTP/2. Use Hypercorn instead of uvicorn for HTTP/2 support
+- **Testing**: Use [buf curl](https://buf.build/docs/ecosystem/cli/curl) for testing Connect-RPC endpoints with proper streaming support
+
+For detailed examples and testing instructions, see the [examples directory](examples/).
+
 ## 📦 Installation
 
 Install PydanticRPC via pip:
@@ -120,6 +132,54 @@ Install PydanticRPC via pip:
 pip install pydantic-rpc
 ```
 
+For CLI support with built-in server runners:
+
+```bash
+pip install pydantic-rpc-cli  # Includes hypercorn and gunicorn
+```
+
+## 🆕 Enhanced Features (v0.10.0+)
+
+**Note: All new features are fully backward compatible. Existing code continues to work without modification.**
+
+### Enhanced Initialization API
+All server classes now support optional initialization with services:
+
+```python
+# Traditional API (still works)
+server = AsyncIOServer()
+server.set_port(50051)
+await server.run(MyService())
+
+# New enhanced API (optional)
+server = AsyncIOServer(
+    service=MyService(),
+    port=50051,
+    package_name="my.package"
+)
+await server.run()
+
+# Same for ASGI/WSGI apps
+app = ASGIApp(service=MyService(), package_name="my.package")
+```
+
+### Error Handling with Decorators
+Automatically map exceptions to gRPC/Connect status codes:
+
+```python
+from pydantic_rpc import error_handler
+import grpc
+
+class MyService:
+    @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+    @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+    async def get_user(self, request: GetUserRequest) -> User:
+        # Exceptions are automatically converted to proper status codes
+        if request.id not in users_db:
+            raise KeyError(f"User {request.id} not found")
+        return users_db[request.id]
+```
+
 ## 🚀 Getting Started
 
 PydanticRPC supports two main protocols:
@@ -1073,15 +1133,40 @@ MCP endpoints will be available at:
 - SSE: `GET http://localhost:8000/mcp/sse`
 - Messages: `POST http://localhost:8000/mcp/messages/`
 
-### 🗄️ Protobuf file and code (Python files) generation using CLI
+### 🗄️ CLI Tool (pydantic-rpc-cli)
+
+The CLI tool provides powerful features for generating protobuf files and running servers. Install it separately:
+
+```bash
+pip install pydantic-rpc-cli
+```
+
+#### Generate Protobuf Files
 
-You can genereate protobuf files and code for a given module and a specified class using `pydantic-rpc` CLI command:
+```bash
+# Generate .proto file from a service class
+pydantic-rpc generate myapp.services.UserService --output ./proto/
+
+# Also compile to Python code
+pydantic-rpc generate myapp.services.UserService --compile
+```
+
+#### Run Servers Directly
+
+The CLI can run any type of server:
 
 ```bash
-pydantic-rpc a_module.py aClassName
+# Run as gRPC server (auto-detects async/sync)
+pydantic-rpc serve myapp.services.UserService --port 50051
+
+# Run as Connect-RPC with ASGI (HTTP/2, uses Hypercorn)
+pydantic-rpc serve myapp.services.UserService --asgi --port 8000
+
+# Run as Connect-RPC with WSGI (HTTP/1.1, uses Gunicorn)
+pydantic-rpc serve myapp.services.UserService --wsgi --port 8000 --workers 4
 ```
 
-Using this generated proto file and tools as `protoc`, `buf` and `BSR`, you could generate code for any desired language other than Python.
+Using the generated proto files with tools like `protoc`, `buf` and `BSR`, you can generate code for any desired language.
 
 
 ## 📖 Data Type Mapping

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-rpc"
-version = "0.10.0"
+version = "0.11.0"
 description = "A Python library for building gRPC/ConnectRPC services with Pydantic models."
 authors = [
     { name = "Yasushi Itoh" }
@@ -19,8 +19,6 @@ dependencies = [
 readme = "README.md"
 requires-python = ">= 3.11"
 
-[project.scripts]
-pydantic-rpc = "pydantic_rpc.core:main"
 
 [build-system]
 requires = ["uv_build>=0.7.21,<0.8.0"]

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/__init__.py

@@ -13,6 +13,8 @@ from .decorators import (
     proto_option,
     get_method_options,
     has_http_option,
+    error_handler,
+    get_error_handlers,
 )
 from .tls import (
     GrpcTLSConfig,
@@ -31,6 +33,8 @@ __all__ = [
     "proto_option",
     "get_method_options",
     "has_http_option",
+    "error_handler",
+    "get_error_handlers",
     "GrpcTLSConfig",
     "extract_peer_identity",
     "extract_peer_certificate_chain",

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/core.py

@@ -2606,6 +2606,9 @@ class Server:
 
     def __init__(
         self,
+        service: Optional[object] = None,
+        port: int = 50051,
+        package_name: str = "",
         max_workers: int = 8,
         *interceptors: Any,
         tls: Optional["GrpcTLSConfig"] = None,
@@ -2614,9 +2617,10 @@ class Server:
             futures.ThreadPoolExecutor(max_workers), interceptors=interceptors
         )
         self._service_names: list[str] = []
-        self._package_name: str = ""
-        self._port: int = 50051
+        self._package_name: str = package_name
+        self._port: int = port
         self._tls_config = tls
+        self._initial_service = service
 
     def set_package_name(self, package_name: str):
         """Set the package name for .proto generation."""
@@ -2654,6 +2658,11 @@ class Server:
         Mount multiple services and run the gRPC server with reflection and health check.
         Press Ctrl+C or send SIGTERM to stop.
         """
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2699,14 +2708,18 @@ class AsyncIOServer:
 
     def __init__(
         self,
+        service: Optional[object] = None,
+        port: int = 50051,
+        package_name: str = "",
         *interceptors: grpc.ServerInterceptor,
         tls: Optional["GrpcTLSConfig"] = None,
     ) -> None:
         self._server: grpc.aio.Server = grpc.aio.server(interceptors=interceptors)
         self._service_names: list[str] = []
-        self._package_name: str = ""
-        self._port: int = 50051
+        self._package_name: str = package_name
+        self._port: int = port
         self._tls_config = tls
+        self._initial_service = service
 
     def set_package_name(self, package_name: str):
         """Set the package name for .proto generation."""
@@ -2746,6 +2759,11 @@ class AsyncIOServer:
         Mount multiple async services and run the gRPC server with reflection and health check.
         Press Ctrl+C or send SIGTERM to stop.
         """
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2802,10 +2820,11 @@ class ASGIApp:
     An ASGI-compatible application that can serve Connect-RPC via Connecpy.
     """
 
-    def __init__(self):
+    def __init__(self, service: Optional[object] = None, package_name: str = ""):
         self._services: list[tuple[Any, str]] = []  # List of (app, path) tuples
         self._service_names: list[str] = []
-        self._package_name: str = ""
+        self._package_name: str = package_name
+        self._initial_service = service
 
     def mount(self, obj: object, package_name: str = ""):
         """Generate and compile proto files, then mount the async service implementation."""
@@ -2838,6 +2857,11 @@ class ASGIApp:
 
     def mount_objs(self, *objs: object):
         """Mount multiple service objects into this ASGI app."""
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2848,6 +2872,10 @@ class ASGIApp:
         send: Callable[[dict[str, Any]], Any],
     ):
         """ASGI entry point with routing for multiple services."""
+        # Mount initial service on first call if not already mounted
+        if self._initial_service and not self._services:
+            self.mount(self._initial_service, self._package_name)
+
         if scope["type"] != "http":
             await send({"type": "http.response.start", "status": 404})
             await send({"type": "http.response.body", "body": b"Not Found"})
@@ -2874,10 +2902,11 @@ class WSGIApp:
     A WSGI-compatible application that can serve Connect-RPC via Connecpy.
     """
 
-    def __init__(self):
+    def __init__(self, service: Optional[object] = None, package_name: str = ""):
         self._services: list[tuple[Any, str]] = []  # List of (app, path) tuples
         self._service_names: list[str] = []
-        self._package_name: str = ""
+        self._package_name: str = package_name
+        self._initial_service = service
 
     def mount(self, obj: object, package_name: str = ""):
         """Generate and compile proto files, then mount the sync service implementation."""
@@ -2910,6 +2939,11 @@ class WSGIApp:
 
     def mount_objs(self, *objs: object):
         """Mount multiple service objects into this WSGI app."""
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2921,6 +2955,10 @@ class WSGIApp:
         ],
     ) -> Iterable[bytes]:
         """WSGI entry point with routing for multiple services."""
+        # Mount initial service on first call if not already mounted
+        if self._initial_service and not self._services:
+            self.mount(self._initial_service, self._package_name)
+
         path = environ.get("PATH_INFO", "")
 
         # Route to the appropriate service based on path

{pydantic_rpc-0.10.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/decorators.py

@@ -1,12 +1,15 @@
 """Decorators for adding protobuf options to RPC methods."""
 
-from typing import Any, Callable, Dict, List, Optional, TypeVar
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Type
 from functools import wraps
+import grpc
+from connecpy.code import Code as ConnectErrors
 
 from .options import OptionMetadata, OPTION_METADATA_ATTR
 
 
 F = TypeVar("F", bound=Callable[..., Any])
+ERROR_HANDLER_ATTR = "__pydantic_rpc_error_handlers__"
 
 
 def http_option(
@@ -136,3 +139,71 @@ def has_proto_options(method: Callable) -> bool:
     """
     metadata = get_method_options(method)
     return metadata is not None and len(metadata.proto_options) > 0
+
+
+def error_handler(
+    exception_type: Type[Exception],
+    status_code: Optional[grpc.StatusCode] = None,
+    connect_code: Optional[ConnectErrors] = None,
+    handler: Optional[Callable[[Exception], tuple[str, Any]]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator to add automatic error handling to an RPC method.
+
+    Args:
+        exception_type: The type of exception to handle
+        status_code: The gRPC status code to return (for gRPC services)
+        connect_code: The Connect error code to return (for Connect services)
+        handler: Optional custom handler function that returns (message, details)
+
+    Example:
+        @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+        @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+        async def get_user(self, request: GetUserRequest) -> User:
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        # Get or create error handlers list
+        if not hasattr(func, ERROR_HANDLER_ATTR):
+            setattr(func, ERROR_HANDLER_ATTR, [])
+
+        handlers = getattr(func, ERROR_HANDLER_ATTR)
+
+        # Add this handler to the list
+        handlers.append(
+            {
+                "exception_type": exception_type,
+                "status_code": status_code or grpc.StatusCode.INTERNAL,
+                "connect_code": connect_code or ConnectErrors.INTERNAL,
+                "handler": handler,
+            }
+        )
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve the error handlers on the wrapper
+        setattr(wrapper, ERROR_HANDLER_ATTR, handlers)
+
+        # Preserve any existing option metadata
+        if hasattr(func, OPTION_METADATA_ATTR):
+            setattr(wrapper, OPTION_METADATA_ATTR, getattr(func, OPTION_METADATA_ATTR))
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def get_error_handlers(method: Callable) -> Optional[List[Dict[str, Any]]]:
+    """
+    Get error handlers from a method.
+
+    Args:
+        method: The method to get error handlers from
+
+    Returns:
+        List of error handler configurations if present, None otherwise
+    """
+    return getattr(method, ERROR_HANDLER_ATTR, None)