pydantic-rpc 0.6.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

{pydantic_rpc-0.6.1.dist-info → pydantic_rpc-0.8.0.dist-info}/METADATA

@@ -1,16 +1,19 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: pydantic-rpc
-Version: 0.6.1
+Version: 0.8.0
 Summary: A Python library for building gRPC/ConnectRPC services with Pydantic models.
 Author: Yasushi Itoh
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: connecpy>=1.4.1
-Requires-Dist: grpcio-health-checking>=1.56.2
-Requires-Dist: grpcio-reflection>=1.56.2
-Requires-Dist: grpcio-tools>=1.56.2
+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
@@ -125,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
 
@@ -178,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
@@ -263,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
@@ -275,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
@@ -648,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:
@@ -733,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:
@@ -762,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
 

pydantic_rpc-0.8.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pydantic_rpc/__init__.py,sha256=7dbedaf58742b13e96954afb68ca91f9800a2faf0799f78da6070c9c88511065,440
+pydantic_rpc/core.py,sha256=2e2bce8aaf677ae50fdcdde51507da605ed77efe5e1a522e52b406c416b18318,104265
+pydantic_rpc/mcp/__init__.py,sha256=f05ad62cc38db5c5972e16870c484523c58c5ac650d8454706f1ce4539cc7a52,123
+pydantic_rpc/mcp/converter.py,sha256=b60dcaf82e6bff6be4b2ab8b1e9f2d16e09cb98d8f00182a4f6f73d1a78848a4,4158
+pydantic_rpc/mcp/exporter.py,sha256=20833662f9a973ed9e1a705b9b59aaa2533de6c514ebd87ef66664a430a0d04f,10239
+pydantic_rpc/py.typed,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+pydantic_rpc-0.8.0.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
+pydantic_rpc-0.8.0.dist-info/entry_points.txt,sha256=72a47b1d2cae3abc045710fe0c2c2e6dfbb051fbf6960c22b62488004e9188ba,57
+pydantic_rpc-0.8.0.dist-info/METADATA,sha256=1cb4d588db71dd052e24c12c63d368c89520279bc9c9a8b10658fdd0d83ee0ec,29803
+pydantic_rpc-0.8.0.dist-info/RECORD,,

pydantic_rpc-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.7.22
+Root-Is-Purelib: true
+Tag: py3-none-any

{pydantic_rpc-0.6.1.dist-info → pydantic_rpc-0.8.0.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 pydantic-rpc = pydantic_rpc.core:main
+

pydantic_rpc-0.6.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-pydantic_rpc/__init__.py,sha256=oomSVGmh_zddQQaphQt1L2xSVh9dD1LVyaAq1cN1FW4,231
-pydantic_rpc/core.py,sha256=SB9GDZRxsMWQFxphinYQUAqrOx10eUn40fPTc7t1xYs,52107
-pydantic_rpc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydantic_rpc-0.6.1.dist-info/METADATA,sha256=Vi8bU0-HjPnhI0ETt9ReRhmMfJxBqPuf9gnAYQjTx4c,20481
-pydantic_rpc-0.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydantic_rpc-0.6.1.dist-info/entry_points.txt,sha256=LeZJ6UN-fhjKrEGkcmsAAKuA-fIe7MpvzKMPSZfi0NE,56
-pydantic_rpc-0.6.1.dist-info/licenses/LICENSE,sha256=Y6jkAm2VqPqoGIGQ-mEQCecNfteQ2LwdpYhC5XiH_cA,1069
-pydantic_rpc-0.6.1.dist-info/RECORD,,

pydantic_rpc-0.6.1.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: hatchling 1.27.0
-Root-Is-Purelib: true
-Tag: py3-none-any

pydantic_rpc-0.6.1.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Yasushi Itoh
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.