Skip to main content

Python gRPC Service UV Basic Archetype

Production-ready Python gRPC microservice with modern UV package management and comprehensive observability stack

Generate a complete, enterprise-grade Python gRPC microservice using the latest Python tooling including UV package manager, modern async patterns, and a full observability stack with Prometheus and Grafana.

Overview​

The python-grpc-service-uv-basic archetype creates a modular, production-ready gRPC microservice built with modern Python practices and the UV package manager for blazing-fast dependency resolution.

Key Characteristics​

  • Package Manager: UV for ultra-fast dependency resolution and virtual environment management
  • Communication: gRPC 1.71.0 with async support and health checking
  • Architecture: Hexagonal architecture with clean separation of concerns
  • Persistence: SQLAlchemy 2.0 with async support and Alembic migrations
  • Observability: Prometheus metrics, Grafana dashboards, and OpenTelemetry tracing
  • Testing: Comprehensive test suites with pytest and TestContainers

Modern Python Tooling​

UV Package Manager Benefits​

Performance​

  • 10-100x faster than pip
  • Parallel dependency resolution
  • Efficient caching strategies
  • Minimal disk space usage

Developer Experience​

  • Single tool for all Python needs
  • Consistent virtual environments
  • Lock file generation
  • Cross-platform compatibility

Production Ready​

  • Reproducible builds
  • Security vulnerability scanning
  • Dependency tree analysis
  • Build artifact optimization

Technology Stack​

Core Technologies

  • Python 3.11+ with modern language features
  • UV package manager for dependency management
  • gRPC 1.71.0 with reflection and health checking
  • Pydantic for type-safe data validation

Data & Persistence

  • SQLAlchemy 2.0 with async/await support
  • Alembic for database migrations
  • Connection pooling and query optimization
  • Support for PostgreSQL, SQLite, and other databases

Observability Stack

  • Prometheus metrics with custom business metrics
  • Grafana dashboards for service monitoring
  • OpenTelemetry for distributed tracing
  • Structured logging with correlation IDs

Project Structure​

Modular Architecture​

Click to enlarge

Generated Structure​

my-awesome-service/
├── my-awesome-service-api/          # API contracts and models
│   ├── pyproject.toml
│   └── src/
├── my-awesome-service-core/         # Business logic
│   ├── pyproject.toml
│   └── src/
├── my-awesome-service-persistence/  # Database layer with migrations
│   ├── pyproject.toml
│   ├── alembic.ini
│   └── src/
├── my-awesome-service-server/       # gRPC server implementation
│   ├── pyproject.toml
│   └── src/
├── my-awesome-service-client/       # Client library
│   ├── pyproject.toml
│   └── src/
├── my-awesome-service-proto/        # Protocol Buffer definitions
│   ├── pyproject.toml
│   └── src/
├── my-awesome-service-integration-tests/  # End-to-end tests
│   ├── pyproject.toml
│   └── tests/
├── monitoring/                      # Grafana & Prometheus config
│   ├── grafana/
│   └── prometheus/
├── scripts/                         # Development utilities
├── docker-compose.yml              # Complete stack orchestration
└── Dockerfile                      # Multi-stage production build

Quality Assurance & Testing​

Comprehensive Testing Strategy​

Test Coverage​

  • Unit tests with pytest and async support
  • Integration tests with TestContainers
  • gRPC connectivity validation
  • Performance and load testing

Quality Metrics​

  • 100% integration test pass rate
  • Code coverage reporting
  • Type checking with mypy
  • Linting with ruff and black

Validation & Quality Gates​

Production Readiness Validation
  • 0 manual fixes required after generation
  • <2 minutes from generation to running service
  • 100% integration test pass rate
  • Template validation with no hardcoded values

Development Workflow​

Quick Start​

# Generate new service
archetect generate git@github.com:p6m-archetypes/python-grpc-service-uv-basic.archetype.git my-service

cd my-service

# 1. Sync all packages with UV
find . -name "pyproject.toml" -exec sh -c 'cd "$(dirname "$1")" && echo "Syncing $(pwd)" && uv sync' _ {} \;

# 2. Start the complete stack
docker-compose up -d

# 3. Run integration tests
./scripts/run-integration-tests.sh

# 4. Access your service
# - gRPC: localhost:50051
# - Health: http://localhost:9011/health  
# - Metrics: http://localhost:9011/metrics
# - Grafana: http://localhost:3000 (admin/admin)
# - Prometheus: http://localhost:9090

Development Commands​

Development Server​

# Run server with hot reloading
cd my-service-server
uv run python -m src.main

# Run with development config
uv run python -m src.main --config dev

# Debug mode with verbose logging
uv run python -m src.main --debug

Testing & Quality​

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Type checking
uv run mypy src/

# Code formatting
uv run black src/ && uv run ruff check src/

Monitoring & Observability​

Prometheus Metrics​

Click to enlarge

Built-in Metrics​

Business Metrics

  • Request count and duration by gRPC method
  • Custom business metric collection
  • Error rates and status code distributions
  • Concurrent request tracking

Technical Metrics

  • Database connection pool statistics
  • Memory usage and garbage collection
  • CPU utilization and thread counts
  • Network I/O and latency measurements

Grafana Dashboards​

Pre-configured Monitoring

Includes comprehensive Grafana dashboards for service health, performance monitoring, database metrics, and business KPIs with alerting rules.

Database & Persistence​

SQLAlchemy 2.0 Integration​

# Modern async SQLAlchemy patterns
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from typing import Optional
import uuid

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    
    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    name: Mapped[str] = mapped_column(String(100))
    email: Mapped[Optional[str]] = mapped_column(String(255), unique=True)
    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)

# Repository pattern with async support
class UserRepository:
    def __init__(self, session: AsyncSession):
        self.session = session
    
    async def create(self, user_data: UserCreate) -> User:
        user = User(**user_data.dict())
        self.session.add(user)
        await self.session.commit()
        await self.session.refresh(user)
        return user
    
    async def get_by_id(self, user_id: uuid.UUID) -> Optional[User]:
        return await self.session.get(User, user_id)

Migration Management​

Alembic Integration​

  • Automatic migration generation
  • Version-controlled schema changes
  • Rollback and upgrade capabilities
  • Multi-environment migration support

Database Features​

  • Connection pooling with async support
  • Query optimization and logging
  • Transaction management
  • Health check integration

Production Deployment​

Docker Containerization​

# Multi-stage Dockerfile included
FROM python:3.11-slim as builder

# Install UV
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Copy source and install dependencies
COPY . /app
WORKDIR /app
RUN uv sync --frozen

FROM python:3.11-slim as runtime
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src /app/src

# Ensure virtual environment is in PATH
ENV PATH="/app/.venv/bin:$PATH"

EXPOSE 50051 9011
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD python -c "import grpc; import grpc_health.v1.health_pb2_grpc as health_grpc"

CMD ["python", "-m", "src.main"]

Kubernetes Deployment​

Container Orchestration​

  • Kubernetes manifests included
  • Health and readiness probes
  • Resource limits and requests
  • Horizontal pod autoscaling

Configuration Management​

  • Environment-specific configs
  • Secret and ConfigMap integration
  • Feature flag support
  • Runtime configuration updates

gRPC Service Implementation​

Service Definition Example​

# gRPC service implementation
import grpc
from grpc import aio
from src.proto import user_service_pb2_grpc, user_service_pb2
from src.core.services import UserService
from src.persistence.repositories import UserRepository

class UserServiceImpl(user_service_pb2_grpc.UserServiceServicer):
    def __init__(self, user_service: UserService):
        self.user_service = user_service
    
    async def CreateUser(
        self, 
        request: user_service_pb2.CreateUserRequest, 
        context: grpc.aio.ServicerContext
    ) -> user_service_pb2.User:
        try:
            user = await self.user_service.create_user(
                name=request.name,
                email=request.email
            )
            return user_service_pb2.User(
                id=str(user.id),
                name=user.name,
                email=user.email
            )
        except ValueError as e:
            await context.abort(grpc.StatusCode.INVALID_ARGUMENT, str(e))
        except Exception as e:
            await context.abort(grpc.StatusCode.INTERNAL, "Internal server error")
    
    async def GetUser(
        self,
        request: user_service_pb2.GetUserRequest,
        context: grpc.aio.ServicerContext
    ) -> user_service_pb2.User:
        user = await self.user_service.get_user(request.id)
        if not user:
            await context.abort(grpc.StatusCode.NOT_FOUND, "User not found")
        
        return user_service_pb2.User(
            id=str(user.id),
            name=user.name,
            email=user.email
        )

Client Integration​

# Generated client library usage
from my_service_client import UserServiceClient
import asyncio

async def main():
    async with UserServiceClient("localhost:50051") as client:
        # Create a user
        user = await client.create_user(
            name="John Doe",
            email="john@example.com"
        )
        print(f"Created user: {user.id}")
        
        # Get the user
        retrieved_user = await client.get_user(user.id)
        print(f"Retrieved: {retrieved_user.name}")

if __name__ == "__main__":
    asyncio.run(main())

Performance & Optimization​

Built-in Performance Features​

Async/Await Support

Full async/await implementation throughout the stack for maximum concurrency and performance with non-blocking I/O operations.

Connection Pooling

Optimized database connection pooling with configurable pool sizes, timeouts, and connection lifecycle management.

Caching Strategy

Built-in caching layers with Redis support, query result caching, and intelligent cache invalidation strategies.

Best Practices & Guidelines​

Development Patterns​

Code Organization​

  • Hexagonal architecture separation
  • Dependency injection with modern patterns
  • Type hints throughout the codebase
  • Comprehensive error handling

Testing Strategy​

  • Unit tests for business logic
  • Integration tests with real databases
  • Contract testing for gRPC interfaces
  • Performance testing with load scenarios

This archetype provides a comprehensive foundation for building production-grade Python gRPC microservices with modern tooling, comprehensive observability, and enterprise-ready patterns that scale from development to production environments.