Install & Compatibility
Where this runs
tested against v0.1.21 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.638s · 68.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.376s · 67MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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.")
Debug
Known issues
breakingSupport 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.fixUpgrade Python to 3.8 or newer.
affects: >=0.1.19
gotchaThe 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.fixEnsure the gRPC server is configured to enable reflection. Alternatively, use `StubClient` if you have pre-generated `.proto` stubs.
affects: All versions
gotchaThere 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.fixCarefully 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.
affects: All versions, specific to dependency combinations
gotchaWhen 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.fixConsult the `grpc-requests` documentation or examples for the correct handling of request data and iterating over responses for different streaming types.
affects: All versions
Errors
Common errors & fixes
UNIMPLEMENTED: unknown service
The gRPC server does not have the requested service or method implemented, or gRPC reflection is not correctly exposing it. This can also happen due to a mismatch in client and server protobuf definitions or connecting to the wrong gRPC server.
fixEnsure the gRPC server implements the requested service and method, and that gRPC reflection is enabled and correctly configured on the server. Verify that the service and method names used in `grpc-requests.Client.request()` exactly match those defined in the server's `.proto` files. If you are certain the service and method exist, there might be a version mismatch between the client's understanding (via reflection) and the server's actual implementation.
UNIMPLEMENTED: Service 'grpc.reflection.v1alpha.ServerReflection' is unimplemented
The gRPC server you are connecting to has not enabled the gRPC reflection service, which `grpc-requests` uses to dynamically discover available services and methods without requiring pre-generated stubs.
fixEnable gRPC server reflection in your gRPC server application. For Python gRPC servers, this typically involves installing `grpcio-reflection` and adding `add_reflection_servicers(server)` with a list of service names. Consult the gRPC documentation for your specific server language on how to enable reflection.
ModuleNotFoundError: No module named 'grpc_requests'
The `grpc-requests` library, or one of its dependencies, is not installed in the Python environment where you are trying to use it.
fixInstall the library using pip: `pip install grpc-requests`. If you are using a virtual environment, ensure it is activated before installation. If the error persists, check your Python path and ensure `pip` is installing to the correct environment.
AttributeError: 'Client' object has no attribute 'some_method_name'
Developers might mistakenly try to call gRPC methods directly as attributes on the `grpc_requests.Client` object (e.g., `client.Greeter.SayHello()`) instead of using the `requests`-like API `client.request('ServiceName', 'MethodName', data)`. The `Client` object itself does not expose service or method names as direct attributes for invocation.
fixAccess gRPC methods using the `client.request(service_name, method_name, request_data)` method, providing the service name and method name as strings, and the request payload as a dictionary. For example: `response = client.request('helloworld.Greeter', 'SayHello', {'name': 'World'})`. grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE
This error indicates that the gRPC client could not connect to the server or the connection was lost/unavailable during the RPC call. Common reasons include the server not running, incorrect host/port, network issues (firewall, DNS), or the server being temporarily overloaded.
fixVerify that the gRPC server is running and accessible at the specified host and port. Check network connectivity, firewall rules, and DNS resolution. Ensure the `Client.get_by_endpoint()` call uses the correct address and `ssl` parameter (True for HTTPS, False for HTTP/plaintext gRPC). Consider implementing retry logic with exponential backoff for transient network issues.
Upgrade
Version history
0.1.21latest on PyPI · released Mar 23, 2025
Audit
Dependencies
grpciorequiredCore gRPC runtime for Python.
grpcio-reflectionrequiredProvides gRPC server reflection capabilities, which is a primary feature of grpc-requests.
protobufrequiredProtocol Buffers library for message serialization and deserialization.