py-micro-model 1.0.0
gRPC model definitions for Python microservice template
Requires Python: <4.0,>=3.12

# py-micro-model

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

## 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
│   └── template_service.proto  # Example template service definition
├── 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:
```bash
make install
# or
poetry install
```

2. Generate gRPC code:
```bash
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:
```bash
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

```protobuf
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

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

### Linting

```bash
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`:
```toml
[tool.poetry.dependencies]
py-micro-model = {path = "../py-micro-model", develop = true}
```

2. Import and use the generated classes:
```python
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:

```bash
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