grpc-requests: gRPC for Humans

0.1.21 · active · verified Mon Apr 13

grpc-requests is a Python library that simplifies interaction with gRPC services, especially those that implement gRPC reflection. It aims to provide a `requests`-like API for gRPC, abstracting away much of the boilerplate associated with standard gRPC client code, allowing for more dynamic interaction without pre-generated stubs. The current version is 0.1.21, with a regular release cadence addressing compatibility, bug fixes, and new features.

Warnings

breaking Support for Python 3.7 was removed in version 0.1.19. Users on Python 3.7 or older must upgrade their Python version to use recent grpc-requests releases.
Fix: Upgrade Python to 3.8 or newer.
gotcha The primary `Client` functionality of `grpc-requests` relies heavily on gRPC Server Reflection. If the target gRPC server does not have reflection enabled, `grpc-requests` will not be able to discover services or methods, leading to errors.
Fix: Ensure the gRPC server is configured to enable reflection. Alternatively, use `StubClient` if you have pre-generated `.proto` stubs.
gotcha There are known compatibility issues between specific versions of `protobuf`, `grpcio`, and `grpcio-reflection`. For instance, `protobuf 4.25.4` is not compatible with `grpcio` / `grpcio-reflection >=1.66.0` (you should stick to `1.65.x`). Also, for Python 3.13, `protobuf` version `5.29.4` or above is required.
Fix: Carefully manage `protobuf`, `grpcio`, and `grpcio-reflection` versions to match documented compatibilities, especially when encountering `RuntimeError` or `ImportError` related to version mismatches. Refer to `grpc-requests`'s PyPI page or GitHub for the latest compatibility matrix.
gotcha When dealing with gRPC streaming methods (server-streaming, client-streaming, bidirectional-streaming), the interaction pattern with `grpc-requests` differs. For client-streaming, you typically pass an iterable of request messages. For server-streaming or bidirectional-streaming, the response will be an iterator of response messages.
Fix: Consult the `grpc-requests` documentation or examples for the correct handling of request data and iterating over responses for different streaming types.

Install

pip install grpc-requests Install latest version

Imports

Client
```
from grpc_requests import Client
```
For synchronous gRPC client interactions using reflection.
AsyncClient
```
from grpc_requests.aio import AsyncClient
```
For asynchronous gRPC client interactions using reflection.
StubClient
```
from grpc_requests import StubClient
```
Used when gRPC reflection is not available, requiring pre-defined service descriptors.

Quickstart

This quickstart demonstrates how to create a synchronous gRPC client using `grpc-requests` to interact with a server via reflection. It connects to a specified endpoint, retrieves available service names, and then makes a `SayHello` RPC call to a 'helloworld.Greeter' service. This requires a running gRPC server with reflection enabled and the 'helloworld.Greeter' service implemented.

import os
from grpc_requests import Client

# Replace with your gRPC server endpoint (e.g., 'localhost:50051')
# Ensure your gRPC server has reflection enabled.
GRPC_SERVER_ENDPOINT = os.environ.get('GRPC_SERVER_ENDPOINT', 'localhost:50051')

# Example: If your server requires TLS
# client = Client.get_by_endpoint(GRPC_SERVER_ENDPOINT, ssl=True)

client = Client.get_by_endpoint(GRPC_SERVER_ENDPOINT)

print(f"Connected to gRPC server at {GRPC_SERVER_ENDPOINT}")

# Assuming a 'helloworld.Greeter' service with a 'SayHello' method
# and that the server supports reflection and this service.
try:
    service_names = client.service_names
    if 'helloworld.Greeter' in service_names:
        print(f"Available services: {service_names}")
        request_data = {"name": "World"}
        response = client.request("helloworld.Greeter", "SayHello", request_data)
        print(f"Response from SayHello: {response}")
    else:
        print("helloworld.Greeter service not found on the server.")
except Exception as e:
    print(f"Error interacting with gRPC server: {e}")
    print("Ensure a gRPC server with reflection is running at the specified endpoint and 'helloworld.Greeter' service is available.")

view raw JSON →