LARA Django Material - gRPC API

This directory contains the gRPC interface for the lara-django-material application, providing a high-performance API for experimental material handling in the LARA database.

Overview

The gRPC API provides remote procedure call access to the LARA Django Material 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-material-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_material_grpc/
        ├── lara_django_material_data_model.py    # Data model definitions
        ├── lara_django_material_interface.py     # High-level interface
        ├── filter_search.py                     # Filter and search capabilities
        └── v1/
            └── *_pb2.py         # Generated protocol buffer code

Installation

Using uv (Recommended)

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

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-material-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_material_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 functionalities:

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

Usage Examples

Python Client

import grpc
from lara_django_material_grpc import material_pb2, material_pb2_grpc

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

# Create a stub (client)
stub = material_pb2_grpc.MaterialServiceStub(channel)

# Make a request
response = stub.GetMaterial(material_pb2.GetMaterialRequest(id=1))
print(response)

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

For more comprehensive examples, see the demo clients in `../../ 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-material/
• Source Code: https://gitlab.com/larasuite/lara-django-material
• Issue Tracker: https://gitlab.com/larasuite/lara-django-material/-/issues
• Protocol Buffer Definitions: ../proto/lara_django_material_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_material_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.