pydantic-rpc 0.6.1__tar.gz → 0.8.0__tar.gz

pydantic_rpc-0.6.1/README.md → pydantic_rpc-0.8.0/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.3
+Name: pydantic-rpc
+Version: 0.8.0
+Summary: A Python library for building gRPC/ConnectRPC services with Pydantic models.
+Author: Yasushi Itoh
+Requires-Dist: annotated-types>=0.5.0
+Requires-Dist: pydantic>=2.1.1
+Requires-Dist: grpcio>=1.56.2
+Requires-Dist: grpcio-tools>=1.56.2
+Requires-Dist: grpcio-reflection>=1.56.2
+Requires-Dist: grpcio-health-checking>=1.56.2
+Requires-Dist: sonora>=0.2.3
+Requires-Dist: connecpy==2.0.0
+Requires-Dist: mcp>=1.9.4
+Requires-Dist: starlette>=0.27.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
 # 🚀 PydanticRPC
 
 **PydanticRPC** is a Python library that enables you to rapidly expose [Pydantic](https://docs.pydantic.dev/) models via [gRPC](https://grpc.io/)/[Connect RPC](https://connectrpc.com/docs/protocol/) services without writing any protobuf files. Instead, it automatically generates protobuf files on the fly from the method signatures of your Python objects and the type signatures of your Pydantic models.
@@ -110,6 +128,7 @@ app.mount(OlympicsLocationAgent())
 - **For Connect-RPC:**
   - 🌐 **Connecpy Support:** Partially supports Connect-RPC via `Connecpy`.
 - 🛠️ **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.
 
 ## 📦 Installation
 
@@ -163,12 +182,18 @@ class Greeter:
         return HelloReply(message=f"Hello, {request.name}!")
 
 
+async def main():
+    # You can specify a custom port (default is 50051)
+    server = AsyncIOServer(port=50052)
+    await server.run(Greeter())
+
+
 if __name__ == "__main__":
-    server = AsyncIOServer()
-    loop = asyncio.get_event_loop()
-    loop.run_until_complete(server.run(Greeter()))
+    asyncio.run(main())
 ```
 
+The AsyncIOServer automatically handles graceful shutdown on SIGTERM and SIGINT signals.
+
 ### 🌐 ASGI Application Example
 
 ```python
@@ -248,7 +273,7 @@ This will launch a Connecpy-based ASGI application that uses the same Pydantic m
 >     - Please follow the instruction described in https://go.dev/doc/install.
 > 2. Install `protoc-gen-connecpy`:
 >     ```bash
->     go install github.com/connecpy/protoc-gen-connecpy@latest
+>     go install github.com/i2y/connecpy/v2/protoc-gen-connecpy@latest
 >     ```
 
 ## ♻️ Skipping Protobuf Generation
@@ -260,6 +285,21 @@ export PYDANTIC_RPC_SKIP_GENERATION=true
 
 When this variable is set to "true", PydanticRPC will load existing pre-generated modules rather than generating them on the fly.
 
+## 🪧 Setting Protobuf and Connecpy/gRPC generation directory
+By default your files will be generated in the current working directory where you ran the code from, but you can set a custom specific directory by setting the environment variable below:
+
+```bash
+export PYDANTIC_RPC_PROTO_PATH=/your/path
+```
+
+## ⚠️ Reserved Fields
+
+You can also set an environment variable to reserve a set number of fields for proto generation, for backward and forward compatibility.
+
+```bash
+export PYDANTIC_RPC_RESERVED_FIELDS=1
+```
+
 ## 💎 Advanced Features
 
 ### 🌊 Response Streaming
@@ -633,6 +673,203 @@ buf: * (#2) Call complete
 %
 ```
 
+### 🪶 Empty Messages
+
+Empty request/response messages are automatically mapped to `google.protobuf.Empty`:
+
+```python
+from pydantic_rpc import AsyncIOServer, Message
+
+
+class EmptyRequest(Message):
+    pass  # Automatically uses google.protobuf.Empty
+
+
+class GreetingResponse(Message):
+    message: str
+
+
+class GreetingService:
+    async def say_hello(self, request: EmptyRequest) -> GreetingResponse:
+        return GreetingResponse(message="Hello!")
+    
+    async def get_default_greeting(self) -> GreetingResponse:
+        # Method with no request parameter (implicitly empty)
+        return GreetingResponse(message="Hello, World!")
+```
+
+### 🎨 Custom Serialization
+
+Pydantic's serialization decorators are fully supported:
+
+```python
+from typing import Any
+from pydantic import field_serializer, model_serializer
+from pydantic_rpc import Message
+
+
+class UserMessage(Message):
+    name: str
+    age: int
+    
+    @field_serializer('name')
+    def serialize_name(self, name: str) -> str:
+        """Always uppercase the name when serializing."""
+        return name.upper()
+
+
+class ComplexMessage(Message):
+    value: int
+    multiplier: int
+    
+    @model_serializer
+    def serialize_model(self) -> dict[str, Any]:
+        """Custom serialization with computed fields."""
+        return {
+            'value': self.value,
+            'multiplier': self.multiplier,
+            'result': self.value * self.multiplier  # Computed field
+        }
+```
+
+The serializers are automatically applied when converting between Pydantic models and protobuf messages.
+
+#### ⚠️ Limitations and Considerations
+
+**1. Nested Message serializers are now supported (v0.8.0+)**
+```python
+class Address(Message):
+    city: str
+    
+    @field_serializer("city")
+    def serialize_city(self, city: str) -> str:
+        return city.upper()
+
+class User(Message):
+    name: str
+    address: Address  # ← Address's serializers ARE applied with DEEP strategy
+    
+    @field_serializer("name")
+    def serialize_name(self, name: str) -> str:
+        return name.upper()  # ← This IS applied
+```
+
+**Serializer Strategy Control:**
+You can control how nested serializers are applied via environment variable:
+```bash
+# Apply serializers at all nesting levels (default)
+export PYDANTIC_RPC_SERIALIZER_STRATEGY=deep
+
+# Apply only top-level serializers
+export PYDANTIC_RPC_SERIALIZER_STRATEGY=shallow
+
+# Disable all serializers
+export PYDANTIC_RPC_SERIALIZER_STRATEGY=none
+```
+
+**Performance Impact:**
+- DEEP strategy: ~4% overhead for simple nested structures
+- SHALLOW strategy: ~2% overhead (only top-level)
+- NONE strategy: No overhead (serializers disabled)
+
+**2. New fields added by serializers are ignored**
+```python
+class ComplexMessage(Message):
+    value: int
+    multiplier: int
+    
+    @model_serializer
+    def serialize_model(self) -> dict[str, Any]:
+        return {
+            "value": self.value,
+            "multiplier": self.multiplier,
+            "result": self.value * self.multiplier  # ← Won't appear in protobuf
+        }
+```
+**Problem**: The `result` field doesn't exist in the Message definition, so it's not in the protobuf schema.
+
+**3. Type must remain consistent**
+```python
+class BadExample(Message):
+    number: int
+    
+    @field_serializer("number")
+    def serialize_number(self, number: int) -> str:  # ❌ int → str
+        return str(number)  # This will cause issues
+```
+
+**4. Union/Optional fields have limited support**
+```python
+class UnionExample(Message):
+    data: str | int | None  # Union type
+    
+    @field_serializer("data")
+    def serialize_data(self, data: str | int | None) -> str | int | None:
+        # Serializer may not be applied to Union types
+        return data
+```
+
+**5. Errors fail silently with fallback**
+```python
+class RiskyMessage(Message):
+    value: int
+    
+    @field_serializer("value")
+    def serialize_value(self, value: int) -> int:
+        if value == 0:
+            raise ValueError("Cannot serialize zero")
+        return value * 2
+
+# If error occurs, original value is used (silent fallback)
+```
+
+**6. Circular references are handled gracefully**
+```python
+class Node(Message):
+    value: str
+    child: "Node | None" = None
+    
+    @field_serializer("value")
+    def serialize_value(self, v: str) -> str:
+        return v.upper()
+
+# Circular references are detected and prevented
+node1 = Node(value="first")
+node2 = Node(value="second")
+node1.child = node2
+node2.child = node1  # Circular reference
+
+# When converting to protobuf:
+# - Circular references are detected
+# - Empty proto is returned for repeated objects
+# - No infinite recursion occurs
+# Note: Pydantic's model_dump() will fail on circular refs,
+#       so serializers won't be applied in this case
+```
+
+**✅ Recommended Usage:**
+```python
+class GoodMessage(Message):
+    # Use with primitive types
+    name: str
+    age: int
+    
+    @field_serializer("name")
+    def normalize_name(self, name: str) -> str:
+        return name.strip().title()  # Normalization
+    
+    @field_serializer("age")
+    def clamp_age(self, age: int) -> int:
+        return max(0, min(age, 150))  # Range limiting
+```
+
+**Best Practices:**
+- Use serializers primarily for primitive types (str, int, float, bool)
+- Keep type consistency (int → int, str → str)
+- Avoid complex transformations or side effects
+- Test error cases thoroughly
+- Be aware that errors fail silently
+
 ### 🔗 Multiple Services with Custom Interceptors
 
 PydanticRPC supports defining and running multiple services in a single server:
@@ -718,6 +955,74 @@ if __name__ == "__main__":
 
 TODO
 
+### 🤖 MCP (Model Context Protocol) Support
+
+PydanticRPC can expose your services as MCP tools for AI assistants using FastMCP. This enables seamless integration with any MCP-compatible client.
+
+#### Stdio Mode Example
+
+```python
+from pydantic_rpc import Message
+from pydantic_rpc.mcp import MCPExporter
+
+class CalculateRequest(Message):
+    expression: str
+
+class CalculateResponse(Message):
+    result: float
+
+class MathService:
+    def calculate(self, req: CalculateRequest) -> CalculateResponse:
+        result = eval(req.expression, {"__builtins__": {}}, {})
+        return CalculateResponse(result=float(result))
+
+# Run as MCP stdio server
+if __name__ == "__main__":
+    service = MathService()
+    mcp = MCPExporter(service)
+    mcp.run_stdio()
+```
+
+#### Configuring MCP Clients
+
+Any MCP-compatible client can connect to your service. For example, to configure Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "my-math-service": {
+      "command": "python",
+      "args": ["/path/to/math_mcp_server.py"]
+    }
+  }
+}
+```
+
+#### HTTP/ASGI Mode Example
+
+MCP can also be mounted to existing ASGI applications:
+
+```python
+from pydantic_rpc import ConnecpyASGIApp
+from pydantic_rpc.mcp import MCPExporter
+
+# Create Connect-RPC ASGI app
+app = ConnecpyASGIApp()
+app.mount(MathService())
+
+# Add MCP support via HTTP/SSE
+mcp = MCPExporter(MathService())
+mcp.mount_to_asgi(app, path="/mcp")
+
+# Run with uvicorn
+import uvicorn
+uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+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
 
 You can genereate protobuf files and code for a given module and a specified class using `pydantic-rpc` CLI command:
@@ -747,16 +1052,61 @@ Using this generated proto file and tools as `protoc`, `buf` and `BSR`, you coul
 | subclass of pydantic.BaseModel | message                   |
 
 
+## ⚠️ Known Limitations
+
+### Union Types with Collections
+
+Due to protobuf's `oneof` restrictions, you cannot use `Union` types that contain `repeated` (list/tuple) or `map` (dict) fields directly. This is a limitation of the protobuf specification itself.
+
+**❌ Not Supported:**
+```python
+from typing import Union, List, Dict
+from pydantic_rpc import Message
+
+# These will fail during proto compilation
+class MyMessage(Message):
+    # Union with list - NOT SUPPORTED
+    field1: Union[List[int], str]
+
+    # Union with dict - NOT SUPPORTED
+    field2: Union[Dict[str, int], int]
+
+    # Union with nested collections - NOT SUPPORTED
+    field3: Union[List[Dict[str, int]], str]
+```
+
+**✅ Workaround - Use Message Wrappers:**
+```python
+from typing import Union, List, Dict
+from pydantic_rpc import Message
+
+# Wrap collections in Message types
+class IntList(Message):
+    values: List[int]
+
+class StringIntMap(Message):
+    values: Dict[str, int]
+
+class MyMessage(Message):
+    # Now these work!
+    field1: Union[IntList, str]
+    field2: Union[StringIntMap, int]
+```
+
+This approach works because protobuf allows message types within `oneof` fields, and the collections are contained within those messages.
+
+
 ## TODO
-- [ ] Streaming Support
+- [x] Streaming Support
   - [x] unary-stream
-  - [ ] stream-unary
-  - [ ] stream-stream
-- [ ] Betterproto Support
-- [ ] Sonora-connect Support
+  - [x] stream-unary
+  - [x] stream-stream
+- [x] Empty Message Support (automatic google.protobuf.Empty)
+- [x] Pydantic Serializer Support (@model_serializer, @field_serializer)
 - [ ] Custom Health Check Support
+- [x] MCP (Model Context Protocol) Support via official MCP SDK
 - [ ] Add more examples
-- [ ] Add tests
+- [x] Add tests
 
 ## 📜 License