LARA Django Organisms - gRPC API

This directory contains the gRPC interface for the lara-django-organisms application, providing a high-performance API for managing organism taxonomic data in the LARA database.

Overview

The gRPC API provides remote procedure call access to the LARA Django Organisms 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-organisms-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_organisms_grpc/
        ├── lara_django_organisms_data_model.py   # Data model definitions
        ├── lara_django_organisms_interfaces.py   # High-level interface
        └── v1/
            └── *_pb2.py         # Generated protocol buffer code

## Installation

### Using uv (Recommended)

Install the `lara-django-organisms-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-organisms-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_organisms_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/ and includes tests for all major entities:

Using uv

# From the api/grpc directory
uv run pytest api/tests/

# With coverage
uv run pytest api/tests/ --cov

Using pytest directly

# From the api/grpc directory
pytest api/tests/

# With coverage
pytest api/tests/ --cov

Test Files

• test_lara_django_organisms_Classis_grpc.py - Classis (class) tests
• test_lara_django_organisms_Cultivar_grpc.py - Cultivar tests
• test_lara_django_organisms_Domain_grpc.py - Domain tests
• test_lara_django_organisms_ExtraData_grpc.py - Extra data tests
• test_lara_django_organisms_Familia_grpc.py - Familia (family) tests
• And other taxonomic entity tests

Usage Examples

Python Client

import grpc
from lara_django_organisms_grpc import domain_pb2, domain_pb2_grpc

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

# Create a stub (client)
stub = domain_pb2_grpc.DomainServiceStub(channel)

# Make a request
response = stub.GetDomain(domain_pb2.GetDomainRequest(id=1))
print(response)

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