lara-django-base-grpc 0.2.105
gRPC interface to lara_django_base
Requires Python: ==3.13.*

# LARA Django Base - gRPC API

This directory contains the gRPC interface for the `lara-django-base` application, providing a high-performance API for managing base entities like addresses, locations, countries, cities, tags, and other core data types in the LARA database.

## Overview

The gRPC API provides remote procedure call access to the LARA Django Base service with support for multiple programming languages through protocol buffer definitions.
It also contains a high-level Python interface for easy integration with Python applications.

**Package:** `lara-django-base-grpc`  
**Python Requirement:** 3.13.*

## Project Structure

```
api/grpc/
├── go/                          # Go gRPC client code
├── connect-es/                  # Connect-ES client code
├── connectrpc-es/               # ConnectRPC ES implementations
├── grpc-web/                    # gRPC-Web client code
├── gen/                         # Generated code from protobuf definitions
├── dist/                        # Distribution packages
├── pyproject.toml               # Python project configuration
└── python/                      # Python API module root
    └── lara_django_base_grpc/
        ├── lara_django_base_data_model.py   # Data model definitions
        ├── lara_django_base_interfaces.py   # High-level interface
        └── v1/
            └── *_pb2.py         # Generated protocol buffer code
```

```

## Installation

### Using uv (Recommended)

Install the `lara-django-base-grpc` package with uv for faster dependency resolution:

```bash
cd api/grpc
uv pip install .
```

Or with development dependencies:

```bash
uv pip install -e ".[dev]"
```

For development, install with editable mode and all dependency groups:

```bash
cd api/grpc
uv sync --all-groups
```

### Using pip

Alternatively, install with pip:

```bash
pip install lara-django-base-grpc
```

Or from the local directory:

```bash
cd api/grpc
pip install .
```

### Dependencies

- **Runtime:** `grpcio>=1.73.0`
- **Development:** 
  - `grpcio-tools>=1.73.0`
  - `pytest>=8,<9`
  - `pytest-cov>=6,<7`
  - `pytest-asyncio`

## Code Generation

Protocol buffer definitions are located in `../proto/lara_django_base_grpc/`. To regenerate gRPC code from protobuf definitions, e.g. in case you changed the `.proto` file, use the Buf CLI:

```bash
cd api
buf generate
```

This will generate code for multiple targets as configured in `buf.gen.yaml`:
- Python
- Go
- JavaScript/TypeScript (Connect-ES, ConnectRPC, gRPC-Web)

## Running Tests

The test suite is located in `api/tests_latest/` and includes tests for all major entities:

### Using uv

```bash
# From the api/grpc directory
uv run pytest ../tests_latest/

# With coverage
uv run pytest ../tests_latest/ --cov
```

### Using pytest directly

```bash
# From the api/grpc directory
pytest ../tests_latest/

# With coverage
pytest ../tests_latest/ --cov
```

### Test Files

- `test_lara_django_base_Address_grpc.py` - Address tests
- `test_lara_django_base_City_grpc.py` - City tests
- `test_lara_django_base_Country_grpc.py` - Country tests
- `test_lara_django_base_CountrySubdivision_grpc.py` - Country subdivision tests
- `test_lara_django_base_Currency_grpc.py` - Currency tests
- `test_lara_django_base_DataType_grpc.py` - Data type tests
- `test_lara_django_base_ExternalResource_grpc.py` - External resource tests
- `test_lara_django_base_ExtraData_grpc.py` - Extra data tests
- `test_lara_django_base_GeoLocation_grpc.py` - Geo location tests
- `test_lara_django_base_ItemStatus_grpc.py` - Item status tests
- `test_lara_django_base_LARASyncServer_grpc.py` - LARA sync server tests
- `test_lara_django_base_Location_grpc.py` - Location tests
- `test_lara_django_base_MediaType_grpc.py` - Media type tests
- `test_lara_django_base_Namespace_grpc.py` - Namespace tests
- `test_lara_django_base_PhysicalStateMatter_grpc.py` - Physical state matter tests
- `test_lara_django_base_PhysicalUnit_grpc.py` - Physical unit tests
- `test_lara_django_base_RoomCategory_grpc.py` - Room category tests
- `test_lara_django_base_ScientificConstant_grpc.py` - Scientific constant tests
- `test_lara_django_base_SubdivisionType_grpc.py` - Subdivision type tests
- `test_lara_django_base_Tag_grpc.py` - Tag tests

## Usage Examples

### Python Client

```python
import grpc
from lara_django_base_grpc.v1 import lara_django_base_pb2, lara_django_base_pb2_grpc

# Create a channel to the gRPC server
channel = grpc.insecure_channel('localhost:50051')

# Create a stub (client) - example with Country
stub = lara_django_base_pb2_grpc.CountryControllerStub(channel)

# Make a request to list countries
response = stub.List(lara_django_base_pb2.CountryListRequest())
for country in response.results:
    print(f"{country.name} ({country.iso_code})")

# Don't forget to close the channel when done
channel.close()
```

For more comprehensive examples, see the demo clients in `../../demo_clients/`.

## Development

### Building

The project uses the `uv_build` backend for building:

```bash
# Using uv (recommended)
uv build

# Or using Python build module
python -m build
```

### Working with uv

This project is configured for uv with the following features:

- **Build Backend:** `uv_build>=0.9.0,<=0.10.0`
- **Module Root:** `python/` (all Python gRPC code should be placed here)
- **Dependency Groups:** Development dependencies are organized in groups

#### Common uv commands:

```bash
# Sync dependencies
uv sync

# Sync with development dependencies
uv sync --all-groups

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Run a command in the uv environment
uv run python script.py

# Build the package
uv build
```

### Module Root

The Python module root is configured at `python/`, meaning all Python gRPC code should be placed in that directory.

## Documentation

- **Project Documentation**: [https://larasuite.gitlab.io/lara-django-base/](https://larasuite.gitlab.io/lara-django-base/)
- **Source Code**: [https://gitlab.com/larasuite/lara-django-base](https://gitlab.com/larasuite/lara-django-base)
- **Issue Tracker**: [https://gitlab.com/larasuite/lara-django-base/-/issues](https://gitlab.com/larasuite/lara-django-base/-/issues)
- **Protocol Buffer Definitions**: [../proto/lara_django_base_grpc/](../proto/lara_django_base_grpc/)

## Protocol Buffer Linting

The project uses Buf for linting and breaking change detection. Configuration is in `../buf.yaml`:

- Follows DEFAULT lint rules with specific exceptions
- Breaking change detection enabled
- Ignores certain Google type definitions

## Contributing

Contributions are welcome! Please see the [CONTRIBUTING.md](../../CONTRIBUTING.md) file in the project root for guidelines.

When modifying protobuf definitions:

1. Edit `.proto` files in `../proto/lara_django_base_grpc/`
2. Run `buf generate` to regenerate code
3. Update tests as needed
4. Run the test suite to ensure compatibility

## License

See the LICENSE file in the project root.