lara-django-substances-grpc 0.2.86
gRPC interface to lara_django_substances
Requires Python: ==3.13.*

# LARA Django Substances - gRPC API

This directory contains the gRPC interface for the `lara-django-substances` application, providing a high-performance API for managing chemical substances, compounds, and related data in the LARA database.

## Overview

The gRPC API provides remote procedure call access to the LARA Django Substances 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-substances-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_substances_grpc/
        ├── lara_django_substances_data_model.py   # Data model definitions
        ├── lara_django_substances_interfaces.py   # High-level interface
        └── v1/
            └── *_pb2.py         # Generated protocol buffer code
```

```

## Installation

### Using uv (Recommended)

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

### Using uv

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

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

### Using pytest directly

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

# With coverage
pytest api/tests/ --cov
```

### Test Files

- `test_lara_django_substances_Chemical_grpc.py` - Chemical substance tests
- `test_lara_django_substances_Compound_grpc.py` - Compound tests
- `test_lara_django_substances_Substance_grpc.py` - Substance tests
- Additional test files for substances-related entities

## Usage Examples

### Python Client

```python
import grpc
from lara_django_substances_grpc import substance_pb2, substance_pb2_grpc

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

# Create a stub (client)
stub = substance_pb2_grpc.SubstanceServiceStub(channel)

# Make a request
response = stub.GetSubstance(substance_pb2.GetSubstanceRequest(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:

```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-substances/](https://larasuite.gitlab.io/lara-django-substances/)
- **Source Code**: [https://gitlab.com/larasuite/lara-django-substances](https://gitlab.com/larasuite/lara-django-substances)
- **Issue Tracker**: [https://gitlab.com/larasuite/lara-django-substances/-/issues](https://gitlab.com/larasuite/lara-django-substances/-/issues)
- **Protocol Buffer Definitions**: [../proto/lara_django_substances_grpc/](../proto/lara_django_substances_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_substances_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.