pydantic-rpc 0.7.0__tar.gz → 0.9.0__tar.gz

{pydantic_rpc-0.7.0 → pydantic_rpc-0.9.0}/PKG-INFO

@@ -1,20 +1,18 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: pydantic-rpc
-Version: 0.7.0
+Version: 0.9.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: annotated-types>=0.5.0
-Requires-Dist: connecpy==2.0.0
-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.7.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: connecpy>=2.2.0
 Requires-Dist: mcp>=1.9.4
-Requires-Dist: pydantic>=2.1.1
-Requires-Dist: sonora>=0.2.3
 Requires-Dist: starlette>=0.27.0
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
 # 🚀 PydanticRPC
@@ -77,7 +75,7 @@ import asyncio
 from openai import AsyncOpenAI
 from pydantic_ai import Agent
 from pydantic_ai.models.openai import OpenAIModel
-from pydantic_rpc import ConnecpyASGIApp, Message
+from pydantic_rpc import ASGIApp, Message
 
 
 class CityLocation(Message):
@@ -108,7 +106,7 @@ class OlympicsLocationAgent:
         result = await self._agent.run(req.prompt())
         return result.data
 
-app = ConnecpyASGIApp()
+app = ASGIApp()
 app.mount(OlympicsLocationAgent())
 
 ```
@@ -124,10 +122,10 @@ app.mount(OlympicsLocationAgent())
   - 💚 **Health Checking:** Built-in support for gRPC health checks using `grpc_health.v1`.
   - 🔎 **Server Reflection:** Built-in support for gRPC server reflection.
   - ⚡ **Asynchronous Support:** Easily create asynchronous gRPC services with `AsyncIOServer`.
-- **For gRPC-Web:**
-  - 🌐 **WSGI/ASGI Support:** Create gRPC-Web services that can run as WSGI or ASGI applications powered by `Sonora`.
 - **For Connect-RPC:**
-  - 🌐 **Connecpy Support:** Partially supports Connect-RPC via `Connecpy`.
+  - 🌐 **Full Protocol Support:** Native Connect-RPC support via `Connecpy` v2.2.0+
+  - 🔄 **All Streaming Patterns:** Unary, server streaming, client streaming, and bidirectional streaming
+  - 🌐 **WSGI/ASGI Applications:** Run as standard WSGI or ASGI applications for easy deployment
 - 🛠️ **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.
 
@@ -141,7 +139,11 @@ pip install pydantic-rpc
 
 ## 🚀 Getting Started
 
-### 🔧 Synchronous Service Example
+PydanticRPC supports two main protocols:
+- **gRPC**: Traditional gRPC services with `Server` and `AsyncIOServer`
+- **Connect-RPC**: Modern HTTP-based RPC with `ASGIApp` and `WSGIApp`
+
+### 🔧 Synchronous gRPC Service Example
 
 ```python
 from pydantic_rpc import Server, Message
@@ -162,7 +164,7 @@ if __name__ == "__main__":
     server.run(Greeter())
 ```
 
-### ⚙️ Asynchronous Service Example
+### ⚙️ Asynchronous gRPC Service Example
 
 ```python
 import asyncio
@@ -195,7 +197,7 @@ if __name__ == "__main__":
 
 The AsyncIOServer automatically handles graceful shutdown on SIGTERM and SIGINT signals.
 
-### 🌐 ASGI Application Example
+### 🌐 Connect-RPC ASGI Application Example
 
 ```python
 from pydantic_rpc import ASGIApp, Message
@@ -207,27 +209,17 @@ class HelloReply(Message):
     message: str
 
 class Greeter:
-    def say_hello(self, request: HelloRequest) -> HelloReply:
+    async def say_hello(self, request: HelloRequest) -> HelloReply:
         return HelloReply(message=f"Hello, {request.name}!")
 
-
-async def app(scope, receive, send):
-    """ASGI application.
-
-    Args:
-        scope (dict): The ASGI scope.
-        receive (callable): The receive function.
-        send (callable): The send function.
-    """
-    pass
-
-# Please note that `app` is any ASGI application, such as FastAPI or Starlette.
-
-app = ASGIApp(app)
+app = ASGIApp()
 app.mount(Greeter())
+
+# Run with uvicorn:
+# uvicorn script:app --host 0.0.0.0 --port 8000
 ```
 
-### 🌐 WSGI Application Example
+### 🌐 Connect-RPC WSGI Application Example
 
 ```python
 from pydantic_rpc import WSGIApp, Message
@@ -242,31 +234,69 @@ class Greeter:
     def say_hello(self, request: HelloRequest) -> HelloReply:
         return HelloReply(message=f"Hello, {request.name}!")
 
-def app(environ, start_response):
-    """WSGI application.
-
-    Args:
-        environ (dict): The WSGI environment.
-        start_response (callable): The start_response function.
-    """
-    pass
-
-# Please note that `app` is any WSGI application, such as Flask or Django.
-
-app = WSGIApp(app)
+app = WSGIApp()
 app.mount(Greeter())
+
+# Run with gunicorn:
+# gunicorn script:app
 ```
 
-### 🏆 Connecpy (Connect-RPC) Example
+### 🏆 Connect-RPC with Streaming Example
 
-PydanticRPC also partially supports Connect-RPC via connecpy. Check out “greeting_connecpy.py” for an example:
+PydanticRPC provides native Connect-RPC support via Connecpy v2.2.0+, including full streaming capabilities and PEP 8 naming conventions. Check out our ASGI examples:
 
 ```bash
-uv run greeting_connecpy.py
+# Run with uvicorn
+uv run uvicorn greeting_asgi:app --port 3000
+
+# Or run streaming example
+uv run python examples/streaming_connecpy.py
 ```
 
 This will launch a Connecpy-based ASGI application that uses the same Pydantic models to serve Connect-RPC requests.
 
+#### Streaming Support with Connecpy
+
+Connecpy v2.2.0 provides full support for streaming RPCs with automatic PEP 8 naming (snake_case):
+
+```python
+from typing import AsyncIterator
+from pydantic_rpc import ASGIApp, Message
+
+class StreamRequest(Message):
+    text: str
+    count: int
+
+class StreamResponse(Message):
+    text: str
+    index: int
+
+class StreamingService:
+    # Server streaming
+    async def server_stream(self, request: StreamRequest) -> AsyncIterator[StreamResponse]:
+        for i in range(request.count):
+            yield StreamResponse(text=f"{request.text}_{i}", index=i)
+    
+    # Client streaming
+    async def client_stream(self, requests: AsyncIterator[StreamRequest]) -> StreamResponse:
+        texts = []
+        async for req in requests:
+            texts.append(req.text)
+        return StreamResponse(text=" ".join(texts), index=len(texts))
+    
+    # Bidirectional streaming
+    async def bidi_stream(
+        self, requests: AsyncIterator[StreamRequest]
+    ) -> AsyncIterator[StreamResponse]:
+        idx = 0
+        async for req in requests:
+            yield StreamResponse(text=f"Echo: {req.text}", index=idx)
+            idx += 1
+
+app = ASGIApp()
+app.mount(StreamingService())
+```
+
 > [!NOTE]
 > Please install `protoc-gen-connecpy` to run the Connecpy example.
 >
@@ -303,9 +333,9 @@ export PYDANTIC_RPC_RESERVED_FIELDS=1
 
 ## 💎 Advanced Features
 
-### 🌊 Response Streaming
-PydanticRPC supports streaming responses only for asynchronous gRPC and gRPC-Web services.
-If a service class method’s return type is `typing.AsyncIterator[T]`, the method is considered a streaming method.
+### 🌊 Response Streaming (gRPC)
+PydanticRPC supports streaming responses for both gRPC and Connect-RPC services.
+If a service class method's return type is `typing.AsyncIterator[T]`, the method is considered a streaming method.
 
 
 Please see the sample code below:
@@ -674,9 +704,207 @@ 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
+>>>>>>> origin/main
 
-PydanticRPC supports defining and running multiple services in a single server:
+PydanticRPC supports defining and running multiple gRPC services in a single server:
 
 ```python
 from datetime import datetime
@@ -807,11 +1035,11 @@ Any MCP-compatible client can connect to your service. For example, to configure
 MCP can also be mounted to existing ASGI applications:
 
 ```python
-from pydantic_rpc import ConnecpyASGIApp
+from pydantic_rpc import ASGIApp
 from pydantic_rpc.mcp import MCPExporter
 
 # Create Connect-RPC ASGI app
-app = ConnecpyASGIApp()
+app = ASGIApp()
 app.mount(MathService())
 
 # Add MCP support via HTTP/SSE
@@ -905,8 +1133,8 @@ This approach works because protobuf allows message types within `oneof` fields,
   - [x] unary-stream
   - [x] stream-unary
   - [x] stream-stream
-- [ ] Betterproto Support
-- [ ] Sonora-connect Support
+- [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