Examples

Practical examples and code snippets demonstrating common Pyvider RPC Plugin patterns and use cases.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Quick Reference

Example	Description	Complexity	Lines
Quick Start	Focused code samples for specific features	🟢 Beginner	~20-30 each
Echo Service	Complete RPC service from basic to production	🟢-🟡 Beginner to Advanced	~570

Getting Started

New to pyvider-rpcplugin?

Start here to learn the fundamentals:

1. Quick Start Examples - Six focused examples covering:
2. Basic client and server setup
3. Health checks and rate limiting
4. TCP transport configuration

5. Custom protocol implementation

6. Echo Service Example - Complete service demonstrating:

7. Unary RPC patterns
8. Streaming (server, client, bidirectional)
9. Error handling and retry logic
10. Production features (health, rate limiting, metrics, security)

Learning Paths

Beginner TrackIntermediate TrackAdvanced Track

Goal: Understand core plugin lifecycle and basic patterns

1. Quick Start: Basic Server - Minimal server (15 lines)
2. Quick Start: Basic Client - Minimal client (20 lines)
3. Echo Service: Basic Setup - Complete RPC service
4. Quick Start: Health Checks - Production monitoring
5. Quick Start: Rate Limiting - Service protection

Next: Explore streaming patterns in the Echo Service example

Goal: Master streaming, transports, and custom protocols

1. Echo Service: Streaming Patterns - Server/client/bidirectional streaming
2. Quick Start: TCP Transport - Cross-platform communication
3. Quick Start: Custom Protocol - Integrate your gRPC services
4. Echo Service: Error Handling - Robust error management

Next: Study production deployment in the Configuration Guide

Goal: Build production-ready, observable, secure services

1. Echo Service: Production Features - Health, rate limiting, metrics, mTLS
2. Echo Service: Testing - Unit and integration test patterns
3. Advanced Topics Guide - Observability, performance tuning
4. Security Guide - Comprehensive mTLS setup

Next: Implement custom middleware and observability

Example Structure

Quick Start Examples

Six focused examples (15-30 lines each) demonstrating specific features:

# Basic Server (15 lines)
async def main():
    protocol = plugin_protocol()
    handler = object()
    server = plugin_server(protocol=protocol, handler=handler)
    await server.serve()

See Quick Start Examples for all patterns.

Echo Service Example

Comprehensive example (576 lines) covering:

• Basic Setup - Unary RPC with client/server implementation
• Streaming Patterns - Server, client, and bidirectional streaming
• Error Handling - Validation, retry, graceful degradation
• Production Features - Health, rate limiting, metrics, mTLS, testing

See Echo Service Example for complete details.

Running Examples

Installation

# Clone the repository
git clone https://github.com/provide-io/pyvider-rpcplugin.git
cd pyvider-rpcplugin

# Install dependencies
uv sync

Quick Start Examples

# Basic client (launches basic_server.py automatically)
python examples/short/basic_client.py

# Health check server
python examples/short/health_check.py

# Rate limited server
python examples/short/rate_limiting.py

# TCP transport server
python examples/short/tcp_transport.py

# Custom protocol server
python examples/short/custom_protocol.py

Echo Service Example

# Run echo client (launches echo_server.py automatically)
python examples/echo_client.py

Expected output:

2025-01-15 10:30:45.123 [info     ] Client will use server script: .../examples/echo_server.py
2025-01-15 10:30:45.200 [info     ] Starting Echo Plugin Server...
2025-01-15 10:30:45.201 [info     ] EchoService handler registered with gRPC server
2025-01-15 10:30:45.250 [info     ] Client started and connected successfully
2025-01-15 10:30:45.251 [info     ] Sending Echo request to server: 'Hello from pyvider client!'

Example Files Reference

Documentation vs. Actual Code

Simplified Examples vs. Runnable Files

Documentation examples are simplified for teaching. Actual files in examples/ include:

• example_utils.configure_for_example() for environment setup
• Comprehensive error handling and logging
• Production-ready patterns and best practices

Here's the mapping:

Documentation	Actual File	Notes
Basic plugin	dummy_server.py	Minimal server with BasicRPCPluginProtocol
Basic client	quick_start_client.py	Client that launches dummy_server.py
Echo server	echo_server.py ✓	Matches documentation (production patterns)
Echo client	echo_client.py ✓	Matches documentation (class-based)

Available Files

examples/
├── short/                           # Quick start examples (15-30 lines)
│   ├── basic_client.py              # Minimal client connection
│   ├── basic_server.py              # Minimal server setup
│   ├── health_check.py              # Health check implementation
│   ├── rate_limiting.py             # Rate limiting example
│   ├── tcp_transport.py             # TCP transport configuration
│   └── custom_protocol.py           # Custom protocol example
├── echo_server.py                   # Echo service server (comprehensive)
├── echo_client.py                   # Echo service client (production-ready)
├── quick_start_client.py            # Basic client launching dummy_server.py
├── dummy_server.py                  # Minimal plugin server
├── proto/                           # Protocol Buffer definitions
│   └── echo.proto                   # Echo service definition
├── example_utils.py                 # Shared utilities for examples
└── run_all_examples.py              # Script to run all examples

See the repository for additional advanced examples.

Common Issues

Import Errors

If you get "ModuleNotFoundError": - Ensure you're running from the project root directory - Run uv sync to install dependencies - The example_utils.configure_for_example() call should handle path setup

Connection Issues

If client can't connect to server: - Check server logs for errors (logs go to stderr) - Verify no other process is using the socket/port - Try increasing timeout: await asyncio.wait_for(client.start(), timeout=30.0)

Transport Issues

If Unix sockets or TCP transport fails: - Unix sockets: Not available on Windows - use TCP instead - TCP: Check firewall allows the port - Port conflicts: Try different port or use port=0 for automatic assignment - Verify port availability: lsof -i :50051

Next Steps

Explore Guides

• Server Guide - Server-side patterns and optimization
• Client Guide - Client-side patterns and error handling
• Configuration Guide - Environment-driven configuration
• Security Guide - Comprehensive mTLS setup
• Advanced Topics - Observability, performance, custom protocols

Study Concepts

• RPC Architecture - Understanding the plugin model
• Transport Configuration - Unix sockets vs TCP
• Security Model - Authentication and encryption

Get Help

• API Reference - Technical API documentation
• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions

Contributing Examples

We welcome contributions! Please:

1. Follow the established structure and naming conventions
2. Include comprehensive documentation and comments
3. Add appropriate error handling and logging
4. Test examples on multiple platforms (Linux, macOS, Windows where applicable)
5. Submit a pull request with your example

See the Contributing Guide for details.