[](https://github.com/d5h-foss/grpc-interceptor/actions?workflow=Tests)
[](https://codecov.io/gh/d5h-foss/grpc-interceptor)
[](https://grpc-interceptor.readthedocs.io/)
[](https://pypi.org/project/grpc-interceptor/)
# Summary
Simplified Python gRPC interceptors.
The Python `grpc` package provides service interceptors, but they're a bit hard to
use because of their flexibility. The `grpc` interceptors don't have direct access
to the request and response objects, or the service context. Access to these are often
desired, to be able to log data in the request or response, or set status codes on the
context.
# Installation
To just get the interceptors (and probably not write your own):
```console
$ pip install grpc-interceptor
```
To also get the testing framework, which is good if you're writing your own interceptors:
```console
$ pip install grpc-interceptor[testing]
```
# Usage
## Server Interceptor
To define your own interceptor (we can use `ExceptionToStatusInterceptor` as an example):
```python
from grpc_interceptor import ServerInterceptor
from grpc_interceptor.exceptions import GrpcException
class ExceptionToStatusInterceptor(ServerInterceptor):
def intercept(
self,
method: Callable,
request_or_iterator: Any,
context: grpc.ServicerContext,
method_name: str,
) -> Any:
"""Override this method to implement a custom interceptor.
You should call method(request_or_iterator, context) to invoke the
next handler (either the RPC method implementation, or the
next interceptor in the list).
Args:
method: The next interceptor, or method implementation.
request_or_iterator: The RPC request, as a protobuf message.
context: The ServicerContext pass by gRPC to the service.
method_name: A string of the form
"/protobuf.package.Service/Method"
Returns:
This should generally return the result of
method(request_or_iterator, context), which is typically the RPC
method response, as a protobuf message. The interceptor
is free to modify this in some way, however.
"""
try:
return method(request_or_iterator, context)
except GrpcException as e:
context.set_code(e.status_code)
context.set_details(e.details)
raise
```
Then inject your interceptor when you create the `grpc` server:
```python
interceptors = [ExceptionToStatusInterceptor()]
server = grpc.server(
futures.ThreadPoolExecutor(max_workers=10),
interceptors=interceptors
)
```
To use `ExceptionToStatusInterceptor`:
```python
from grpc_interceptor.exceptions import NotFound
class MyService(my_pb2_grpc.MyServiceServicer):
def MyRpcMethod(
self, request: MyRequest, context: grpc.ServicerContext
) -> MyResponse:
thing = lookup_thing()
if not thing:
raise NotFound("Sorry, your thing is missing")
...
```
This results in the gRPC status status code being set to `NOT_FOUND`,
and the details `"Sorry, your thing is missing"`. This saves you the hassle of
catching exceptions in your service handler, or passing the context down into
helper functions so they can call `context.abort` or `context.set_code`. It allows
the more Pythonic approach of just raising an exception from anywhere in the code,
and having it be handled automatically.
## Client Interceptor
We will use an invocation metadata injecting interceptor as an example of defining
a client interceptor:
```python
from grpc_interceptor import ClientCallDetails, ClientInterceptor
class MetadataClientInterceptor(ClientInterceptor):
def intercept(
self,
method: Callable,
request_or_iterator: Any,
call_details: grpc.ClientCallDetails,
):
"""Override this method to implement a custom interceptor.
This method is called for all unary and streaming RPCs. The interceptor
implementation should call `method` using a `grpc.ClientCallDetails` and the
`request_or_iterator` object as parameters. The `request_or_iterator`
parameter may be type checked to determine if this is a singluar request
for unary RPCs or an iterator for client-streaming or client-server streaming
RPCs.
Args:
method: A function that proceeds with the invocation by executing the next
interceptor in the chain or invoking the actual RPC on the underlying
channel.
request_or_iterator: RPC request message or iterator of request messages
for streaming requests.
call_details: Describes an RPC to be invoked.
Returns:
The type of the return should match the type of the return value received
by calling `method`. This is an object that is both a
`Call <https://grpc.github.io/grpc/python/grpc.html#grpc.Call>`_ for the
RPC and a `Future <https://grpc.github.io/grpc/python/grpc.html#grpc.Future>`_.
The actual result from the RPC can be got by calling `.result()` on the
value returned from `method`.
"""
new_details = ClientCallDetails(
call_details.method,
call_details.timeout,
[("authorization", "Bearer mysecrettoken")],
call_details.credentials,
call_details.wait_for_ready,
call_details.compression,
)
return method(request_or_iterator, new_details)
```
Now inject your interceptor when you create the ``grpc`` channel:
```python
interceptors = [MetadataClientInterceptor()]
with grpc.insecure_channel("grpc-server:50051") as channel:
channel = grpc.intercept_channel(channel, *interceptors)
...
```
Client interceptors can also be used to
[retry RPCs](https://github.com/d5h-foss/grpc-interceptor/blob/4b6bb6a59aae97aec058c0d4072dd19de8f408bc/tests/test_client.py#L39-L56)
that fail due to specific errors, or a host of other use cases. There are some basic
approaches in
[the tests](https://github.com/d5h-foss/grpc-interceptor/blob/master/tests/test_client.py)
to get you started.
Note: The `method` in a client interceptor is a `continuation` as described in the
[client interceptor section of the gRPC docs](https://grpc.github.io/grpc/python/grpc.html#grpc.UnaryUnaryClientInterceptor.intercept_unary_unary).
When you invoke the continuation, you get a future back, which resolves to either the
result, or exception. This is different than invoking a client stub, which returns the
result directly. If the interceptor needs the value returned by the call, or to catch
exceptions, then you'll need to do `future = method(request_or_iterator, call_details)`,
followed by `future.result()`. Check out the tests for
[examples](https://github.com/d5h-foss/grpc-interceptor/blob/4b6bb6a59aae97aec058c0d4072dd19de8f408bc/tests/test_client.py#L39-L56).
# Documentation
The examples above showed usage for simple unary-unary RPC calls. For examples of
streaming and asyncio RPCs, read the
[complete documentation here](https://grpc-interceptor.readthedocs.io/).
Note that there is no asyncio client interceptors at the moment, though contributions
are welcome.
Raw data
{
"_id": null,
"home_page": "https://github.com/d5h-foss/grpc-interceptor",
"name": "grpc-interceptor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "grpc,interceptor",
"author": "Dan Hipschman",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/9f/28/57449d5567adf4c1d3e216aaca545913fbc21a915f2da6790d6734aac76e/grpc-interceptor-0.15.4.tar.gz",
"platform": null,
"description": "[](https://github.com/d5h-foss/grpc-interceptor/actions?workflow=Tests)\n[](https://codecov.io/gh/d5h-foss/grpc-interceptor)\n[](https://grpc-interceptor.readthedocs.io/)\n[](https://pypi.org/project/grpc-interceptor/)\n\n# Summary\n\nSimplified Python gRPC interceptors.\n\nThe Python `grpc` package provides service interceptors, but they're a bit hard to\nuse because of their flexibility. The `grpc` interceptors don't have direct access\nto the request and response objects, or the service context. Access to these are often\ndesired, to be able to log data in the request or response, or set status codes on the\ncontext.\n\n# Installation\n\nTo just get the interceptors (and probably not write your own):\n\n```console\n$ pip install grpc-interceptor\n```\n\nTo also get the testing framework, which is good if you're writing your own interceptors:\n\n```console\n$ pip install grpc-interceptor[testing]\n```\n\n# Usage\n\n## Server Interceptor\n\nTo define your own interceptor (we can use `ExceptionToStatusInterceptor` as an example):\n\n```python\nfrom grpc_interceptor import ServerInterceptor\nfrom grpc_interceptor.exceptions import GrpcException\n\nclass ExceptionToStatusInterceptor(ServerInterceptor):\n def intercept(\n self,\n method: Callable,\n request_or_iterator: Any,\n context: grpc.ServicerContext,\n method_name: str,\n ) -> Any:\n \"\"\"Override this method to implement a custom interceptor.\n You should call method(request_or_iterator, context) to invoke the\n next handler (either the RPC method implementation, or the\n next interceptor in the list).\n Args:\n method: The next interceptor, or method implementation.\n request_or_iterator: The RPC request, as a protobuf message.\n context: The ServicerContext pass by gRPC to the service.\n method_name: A string of the form\n \"/protobuf.package.Service/Method\"\n Returns:\n This should generally return the result of\n method(request_or_iterator, context), which is typically the RPC\n method response, as a protobuf message. The interceptor\n is free to modify this in some way, however.\n \"\"\"\n try:\n return method(request_or_iterator, context)\n except GrpcException as e:\n context.set_code(e.status_code)\n context.set_details(e.details)\n raise\n```\n\nThen inject your interceptor when you create the `grpc` server:\n\n```python\ninterceptors = [ExceptionToStatusInterceptor()]\nserver = grpc.server(\n futures.ThreadPoolExecutor(max_workers=10),\n interceptors=interceptors\n)\n```\n\nTo use `ExceptionToStatusInterceptor`:\n\n```python\nfrom grpc_interceptor.exceptions import NotFound\n\nclass MyService(my_pb2_grpc.MyServiceServicer):\n def MyRpcMethod(\n self, request: MyRequest, context: grpc.ServicerContext\n ) -> MyResponse:\n thing = lookup_thing()\n if not thing:\n raise NotFound(\"Sorry, your thing is missing\")\n ...\n```\n\nThis results in the gRPC status status code being set to `NOT_FOUND`,\nand the details `\"Sorry, your thing is missing\"`. This saves you the hassle of\ncatching exceptions in your service handler, or passing the context down into\nhelper functions so they can call `context.abort` or `context.set_code`. It allows\nthe more Pythonic approach of just raising an exception from anywhere in the code,\nand having it be handled automatically.\n\n## Client Interceptor\n\nWe will use an invocation metadata injecting interceptor as an example of defining\na client interceptor:\n\n```python\nfrom grpc_interceptor import ClientCallDetails, ClientInterceptor\n\nclass MetadataClientInterceptor(ClientInterceptor):\n\n def intercept(\n self,\n method: Callable,\n request_or_iterator: Any,\n call_details: grpc.ClientCallDetails,\n ):\n \"\"\"Override this method to implement a custom interceptor.\n\n This method is called for all unary and streaming RPCs. The interceptor\n implementation should call `method` using a `grpc.ClientCallDetails` and the\n `request_or_iterator` object as parameters. The `request_or_iterator`\n parameter may be type checked to determine if this is a singluar request\n for unary RPCs or an iterator for client-streaming or client-server streaming\n RPCs.\n\n Args:\n method: A function that proceeds with the invocation by executing the next\n interceptor in the chain or invoking the actual RPC on the underlying\n channel.\n request_or_iterator: RPC request message or iterator of request messages\n for streaming requests.\n call_details: Describes an RPC to be invoked.\n\n Returns:\n The type of the return should match the type of the return value received\n by calling `method`. This is an object that is both a\n `Call <https://grpc.github.io/grpc/python/grpc.html#grpc.Call>`_ for the\n RPC and a `Future <https://grpc.github.io/grpc/python/grpc.html#grpc.Future>`_.\n\n The actual result from the RPC can be got by calling `.result()` on the\n value returned from `method`.\n \"\"\"\n new_details = ClientCallDetails(\n call_details.method,\n call_details.timeout,\n [(\"authorization\", \"Bearer mysecrettoken\")],\n call_details.credentials,\n call_details.wait_for_ready,\n call_details.compression,\n )\n\n return method(request_or_iterator, new_details)\n```\n\nNow inject your interceptor when you create the ``grpc`` channel:\n\n```python\ninterceptors = [MetadataClientInterceptor()]\nwith grpc.insecure_channel(\"grpc-server:50051\") as channel:\n channel = grpc.intercept_channel(channel, *interceptors)\n ...\n```\n\nClient interceptors can also be used to\n[retry RPCs](https://github.com/d5h-foss/grpc-interceptor/blob/4b6bb6a59aae97aec058c0d4072dd19de8f408bc/tests/test_client.py#L39-L56)\nthat fail due to specific errors, or a host of other use cases. There are some basic\napproaches in\n[the tests](https://github.com/d5h-foss/grpc-interceptor/blob/master/tests/test_client.py)\nto get you started.\n\nNote: The `method` in a client interceptor is a `continuation` as described in the\n[client interceptor section of the gRPC docs](https://grpc.github.io/grpc/python/grpc.html#grpc.UnaryUnaryClientInterceptor.intercept_unary_unary).\nWhen you invoke the continuation, you get a future back, which resolves to either the\nresult, or exception. This is different than invoking a client stub, which returns the\nresult directly. If the interceptor needs the value returned by the call, or to catch\nexceptions, then you'll need to do `future = method(request_or_iterator, call_details)`,\nfollowed by `future.result()`. Check out the tests for\n[examples](https://github.com/d5h-foss/grpc-interceptor/blob/4b6bb6a59aae97aec058c0d4072dd19de8f408bc/tests/test_client.py#L39-L56).\n\n\n# Documentation\n\nThe examples above showed usage for simple unary-unary RPC calls. For examples of\nstreaming and asyncio RPCs, read the\n[complete documentation here](https://grpc-interceptor.readthedocs.io/).\n\nNote that there is no asyncio client interceptors at the moment, though contributions\nare welcome.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simplifies gRPC interceptors",
"version": "0.15.4",
"project_urls": {
"Documentation": "https://grpc-interceptor.readthedocs.io",
"Homepage": "https://github.com/d5h-foss/grpc-interceptor",
"Repository": "https://github.com/d5h-foss/grpc-interceptor"
},
"split_keywords": [
"grpc",
"interceptor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15ac8d53f230a7443401ce81791ec50a3b0e54924bf615ad287654fa4a2f5cdc",
"md5": "febcd5923ae03f684c4688103986c606",
"sha256": "0035f33228693ed3767ee49d937bac424318db173fef4d2d0170b3215f254d9d"
},
"downloads": -1,
"filename": "grpc_interceptor-0.15.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "febcd5923ae03f684c4688103986c606",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 20848,
"upload_time": "2023-11-16T02:05:40",
"upload_time_iso_8601": "2023-11-16T02:05:40.913603Z",
"url": "https://files.pythonhosted.org/packages/15/ac/8d53f230a7443401ce81791ec50a3b0e54924bf615ad287654fa4a2f5cdc/grpc_interceptor-0.15.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f2857449d5567adf4c1d3e216aaca545913fbc21a915f2da6790d6734aac76e",
"md5": "8292517d064eddb54bd6b73c4d556157",
"sha256": "1f45c0bcb58b6f332f37c637632247c9b02bc6af0fdceb7ba7ce8d2ebbfb0926"
},
"downloads": -1,
"filename": "grpc-interceptor-0.15.4.tar.gz",
"has_sig": false,
"md5_digest": "8292517d064eddb54bd6b73c4d556157",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 19322,
"upload_time": "2023-11-16T02:05:42",
"upload_time_iso_8601": "2023-11-16T02:05:42.459175Z",
"url": "https://files.pythonhosted.org/packages/9f/28/57449d5567adf4c1d3e216aaca545913fbc21a915f2da6790d6734aac76e/grpc-interceptor-0.15.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-16 02:05:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d5h-foss",
"github_project": "grpc-interceptor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "grpc-interceptor"
}
JSON
