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:

uv pip install -e ".[dev]"

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

cd api/grpc
uv sync --all-groups

Using pip

Alternatively, install with pip:

pip install lara-django-base-grpc

Or from the local directory:

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:

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

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

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

Using pytest directly

# 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

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:

# 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:

# 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/
• Source Code: https://gitlab.com/larasuite/lara-django-base
• Issue Tracker: https://gitlab.com/larasuite/lara-django-base/-/issues
• Protocol Buffer Definitions: ../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 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.