{"id":5243,"library":"grpc-requests","title":"grpc-requests: gRPC for Humans","description":"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.","status":"active","version":"0.1.21","language":"python","source_language":"en","source_url":"https://github.com/grpc-requests/grpc_requests","tags":["grpc","client","reflection","protobuf","rpc","asyncio"],"install":[{"cmd":"pip install grpc-requests","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core gRPC runtime for Python.","package":"grpcio","optional":false},{"reason":"Provides gRPC server reflection capabilities, which is a primary feature of grpc-requests.","package":"grpcio-reflection","optional":false},{"reason":"Protocol Buffers library for message serialization and deserialization.","package":"protobuf","optional":false}],"imports":[{"note":"For synchronous gRPC client interactions using reflection.","symbol":"Client","correct":"from grpc_requests import Client"},{"note":"For asynchronous gRPC client interactions using reflection.","symbol":"AsyncClient","correct":"from grpc_requests.aio import AsyncClient"},{"note":"Used when gRPC reflection is not available, requiring pre-defined service descriptors.","symbol":"StubClient","correct":"from grpc_requests import StubClient"}],"quickstart":{"code":"import os\nfrom grpc_requests import Client\n\n# Replace with your gRPC server endpoint (e.g., 'localhost:50051')\n# Ensure your gRPC server has reflection enabled.\nGRPC_SERVER_ENDPOINT = os.environ.get('GRPC_SERVER_ENDPOINT', 'localhost:50051')\n\n# Example: If your server requires TLS\n# client = Client.get_by_endpoint(GRPC_SERVER_ENDPOINT, ssl=True)\n\nclient = Client.get_by_endpoint(GRPC_SERVER_ENDPOINT)\n\nprint(f\"Connected to gRPC server at {GRPC_SERVER_ENDPOINT}\")\n\n# Assuming a 'helloworld.Greeter' service with a 'SayHello' method\n# and that the server supports reflection and this service.\ntry:\n    service_names = client.service_names\n    if 'helloworld.Greeter' in service_names:\n        print(f\"Available services: {service_names}\")\n        request_data = {\"name\": \"World\"}\n        response = client.request(\"helloworld.Greeter\", \"SayHello\", request_data)\n        print(f\"Response from SayHello: {response}\")\n    else:\n        print(\"helloworld.Greeter service not found on the server.\")\nexcept Exception as e:\n    print(f\"Error interacting with gRPC server: {e}\")\n    print(\"Ensure a gRPC server with reflection is running at the specified endpoint and 'helloworld.Greeter' service is available.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.8 or newer.","message":"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.","severity":"breaking","affected_versions":">=0.1.19"},{"fix":"Ensure the gRPC server is configured to enable reflection. Alternatively, use `StubClient` if you have pre-generated `.proto` stubs.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, specific to dependency combinations"},{"fix":"Consult the `grpc-requests` documentation or examples for the correct handling of request data and iterating over responses for different streaming types.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.1.21':62 'abstract':36 'address':68 'aim':27 'allow':48 'api':33 'associ':42 'asyncio':80 'away':37 'boilerpl':41 'bug':70 'cadenc':67 'client':46,76 'code':47 'compat':69 'current':59 'dynam':51 'especi':20 'featur':74 'fix':71 'generat':56 'grpc':2,4,8,18,24,35,45,75 'grpc-request':1,7 'human':6 'implement':23 'interact':16,52 'librari':13 'like':32 'much':38 'new':73 'pre':55 'pre-gener':54 'protobuf':78 'provid':29 'python':12 'reflect':25,77 'regular':65 'releas':66 'request':3,9,31 'rpc':79 'servic':19 'simplifi':15 'standard':44 'stub':57 'version':60 'without':53","created_at":"2026-04-14T01:25:23.880822+00:00","updated_at":"2026-04-16T15:29:20.536404+00:00","problems":[{"fix":"Ensure 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.","cause":"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.","error":"UNIMPLEMENTED: unknown service"},{"fix":"Enable 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.","cause":"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.","error":"UNIMPLEMENTED: Service 'grpc.reflection.v1alpha.ServerReflection' is unimplemented"},{"fix":"Install 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.","cause":"The `grpc-requests` library, or one of its dependencies, is not installed in the Python environment where you are trying to use it.","error":"ModuleNotFoundError: No module named 'grpc_requests'"},{"fix":"Access 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'})`.","cause":"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.","error":"AttributeError: 'Client' object has no attribute 'some_method_name'"},{"fix":"Verify 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.","cause":"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.","error":"grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.21","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/grpc-requests/grpc_requests","docs":null,"changelog":null,"pypi":"https://pypi.org/project/grpc-requests/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}