PyMicro Models

This repository contains the gRPC model definitions (protobuf files) and generated Python code for Python microservices.

Overview

This package provides:

• Protocol Buffer definitions for gRPC services
• Generated Python gRPC stubs and type hints
• Code generation scripts for easy updates

Directory Structure

py-micro-model/
├── proto/                      # Protocol Buffer definitions
├── src/py_micro/model          # Generated Python code (auto-generated)
├── scripts/                    # Code generation scripts
│   └── generate.py             # Main generation script
├── Makefile                    # Build automation
├── pyproject.toml              # Poetry configuration
└── README.md                   # This file

Getting Started

Prerequisites

• Python 3.8+
• Poetry

Installation

1. Install dependencies:

make install
# or
poetry install

2. Generate gRPC code:

make generate
# or
poetry run python scripts/generate.py

Usage

Adding New Services

1. Create a new .proto file in the proto/ directory
2. Define your service and message types following Protocol Buffer v3 syntax
3. Run code generation:

make generate

Code Generation

The code generation script (scripts/generate.py) will:

• Clean the src/ directory
• Generate Python gRPC stubs from all .proto files
• Create proper Python package structure with __init__.py files
• Fix import statements for proper module resolution
• Generate type stubs (.pyi files) for better IDE support

Example Proto Definition

syntax = "proto3";

package my_service.v1;

service MyService {
  rpc GetItem(GetItemRequest) returns (GetItemResponse);
}

message GetItemRequest {
  string id = 1;
}

message GetItemResponse {
  string id = 1;
  string name = 2;
}

Development

Code Formatting

make format
# or
poetry run black scripts/
poetry run isort scripts/

Linting

make lint
# or
poetry run flake8 scripts/
poetry run mypy scripts/

Integration with Services

To use the generated models in your service:

1. Add this package as a dependency in your service's pyproject.toml:

[tool.poetry.dependencies]
py-micro-models = "^1.0.0"

2. Import and use the generated classes:

from py_micro.model.template_service_pb2 import HealthCheckRequest
from py_micro.model.template_service_pb2_grpc import TemplateServiceServicer

Best Practices

1. Versioning: Use package versioning in your proto definitions (e.g., my_service.v1)
2. Backwards Compatibility: Follow protobuf best practices for field numbering and evolution
3. Documentation: Document your services and messages with comments
4. Validation: Consider adding validation rules using proto annotations
5. Testing: Write tests for your proto definitions and generated code

Troubleshooting

Common Issues

1. Import Errors: Make sure you've run make generate after modifying proto files
2. Module Not Found: Ensure the src/py_micro/model directory has proper __init__.py files
3. Type Checking: Use the generated .pyi files for better IDE support

Regenerating Code

If you encounter issues with generated code:

make clean
make generate

Contributing

1. Add or modify .proto files in the proto/ directory
2. Run tests to ensure everything works
3. Update documentation if needed
4. Regenerate code before committing