How i2y/pydantic-rpc works
Main Components
• Library Core: The heart of the project is found in the “src/pydantic_rpc” directory. This is where the main functionalities—such as automatic protobuf generation, runtime dynamic code generation, and service handling—reside (e.g. in core.py).
• API/Server Abstractions: The library supports several server models, including:
• Synchronous services via “Server”
• Asynchronous services via “AsyncIOServer”
• ASGI/WSGI integration applications (ASGIApp/WSGIApp)
• Connecpy support for Connect-RPC
• Protobuf Generation Mechanism: This component is responsible for creating .proto files on the fly based on Python method and type signatures. It drives integrations with external tools like grpcio-tools and CLI-based code generation.
• External Dependencies & Libraries: Highlight the use of Pydantic (for model definition/validation), gRPC (for transport), external packages like “pydantic_ai” (used in the examples for connecting to OpenAI-like models), and Connecpy (for Connect-RPC services).
• Example Applications and Tests: Both the “examples” and “tests” directories show how the library is intended to be used in practice. They are critical for illustrating various service patterns (gRPC, async streaming, multiple services, etc.) and thus should be referenced as usage samples that demonstrate how the core components are integrated.
Relationships and Interactions
• How the core module accepts Pydantic models (the “Message” classes) and method signatures to generate protobuf definitions on the fly.
• How external components (e.g., gRPC health, server reflection, streaming handlers) interact with the core module.
Architectural Patterns & Design Principles
• Dynamic/On-Demand Code Generation: Emphasize that instead of a static definition, the library generates .proto files and stubs at runtime unless the skip generation flag is set.
• Extensibility: The design allows for pluggable server types (synchronous, asynchronous, ASGI, WSGI, ConnectRPC) and custom interceptors (as shown in the multiple services example), indicating a high degree of flexibility.
Technologies & Libraries
• Pydantic – used for model definitions and type validation.
• grpcio and grpcio-tools – used to support gRPC communications.
• Connecpy – for Connect-RPC support.
• Standard Python libraries: asyncio (for async operations) and others noted in the examples.
• OpenAI integrations (via pydantic_ai and AsyncOpenAI) as showcased in the examples, to illustrate how external services might be integrated.