Merge pull request #4 from dan-hipschman-od/renames

Better class names and module organization

README.md

@@ -32,9 +32,10 @@ $ pip install grpc-interceptor[testing]
 To define your own interceptor (we can use `ExceptionToStatusInterceptor` as an example):
 
 ```python
-from grpc_interceptor.base import ServiceInterceptor
+from grpc_interceptor import ServerInterceptor
+from grpc_interceptor.exceptions import GrpcException
 
-class ExceptionToStatusInterceptor(ServiceInterceptor):
+class ExceptionToStatusInterceptor(ServerInterceptor):
     def intercept(
         self,
         method: Callable,

docs/index.rst

@@ -25,12 +25,14 @@ dependencies to a minimum. The only core dependency is the ``grpc`` package, and
 
 The ``grpc_interceptor`` package provides the following:
 
-* A ``ServiceInterceptor`` base class, to make it easy to define your own service interceptors.
+* A ``ServerInterceptor`` base class, to make it easy to define your own server-side interceptors.
+  Do not confuse this with the ``grpc.ServerInterceptor`` class.
 * An ``ExceptionToStatusInterceptor`` interceptor, so your service can raise exceptions
   that set the gRPC status code correctly (rather than the default of every exception
   resulting in an ``UNKNOWN`` status code). This is something for which pretty much any
   service will have a use.
 * An optional testing framework. If you're writing your own interceptors, this is useful.
+  If you're just using ``ExceptionToStatusInterceptor`` then you don't need this.
 
 Installation
 ------------
@@ -55,9 +57,10 @@ To define your own interceptor (we can use a simplified version of
 
 .. code-block:: python
 
-   from grpc_interceptor.base import Interceptor
+   from grpc_interceptor import ServerInterceptor
+   from grpc_interceptor.exceptions import GrpcException
 
-   class ExceptionToStatusInterceptor(ServiceInterceptor):
+   class ExceptionToStatusInterceptor(ServerInterceptor):
 
        def intercept(
            self,
@@ -141,8 +144,8 @@ dict. This allows you to test things like exceptions being thrown. Here's an exa
 
 .. code-block:: python
 
+   from grpc_interceptor import ExceptionToStatusInterceptor
    from grpc_interceptor.exceptions import NotFound
-   from grpc_interceptor.exception_to_status import ExceptionToStatusInterceptor
    from grpc_interceptor.testing import dummy_client, DummyRequest, raises
 
    def test_exception():
@@ -162,5 +165,5 @@ Limitations
 These are the current limitations, although supporting these is possible. Contributions
 or requests are welcome.
 
-* ``ServiceInterceptor`` currently only supports unary-unary RPCs.
+* ``ServerInterceptor`` currently only supports unary-unary RPCs.
 * The package only provides service interceptors.

docs/reference.rst

@@ -5,16 +5,10 @@ Reference
     :local:
     :backlinks: none
 
-grpc_interceptor.base
+grpc_interceptor
 ---------------------
 
-.. automodule:: grpc_interceptor.base
-   :members:
-
-grpc_interceptor.exception_to_status
-------------------------------------
-
-.. automodule:: grpc_interceptor.exception_to_status
+.. automodule:: grpc_interceptor
    :members:
 
 grpc_interceptor.exceptions

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "grpc-interceptor"
-version = "0.10.0"
+version = "0.11.0"
 description = "Simplifies gRPC interceptors"
 license = "MIT"
 readme = "README.md"

src/grpc_interceptor/__init__.py

@@ -1 +1,12 @@
 """Simplified Python gRPC interceptors."""
+
+from grpc_interceptor.exception_to_status import ExceptionToStatusInterceptor
+from grpc_interceptor.server import MethodName, parse_method_name, ServerInterceptor
+
+
+__all__ = [
+    "ExceptionToStatusInterceptor",
+    "MethodName",
+    "parse_method_name",
+    "ServerInterceptor",
+]

src/grpc_interceptor/exception_to_status.py

@@ -4,11 +4,11 @@
 
 import grpc
 
-from grpc_interceptor.base import ServiceInterceptor
 from grpc_interceptor.exceptions import GrpcException
+from grpc_interceptor.server import ServerInterceptor
 
 
-class ExceptionToStatusInterceptor(ServiceInterceptor):
+class ExceptionToStatusInterceptor(ServerInterceptor):
     """An interceptor that catches exceptions and sets the RPC status and details.
 
     ExceptionToStatusInterceptor will catch any subclass of GrpcException and set the

src/grpc_interceptor/base.py → src/grpc_interceptor/server.py

@@ -6,7 +6,7 @@
 import grpc
 
 
-class ServiceInterceptor(grpc.ServerInterceptor, metaclass=abc.ABCMeta):
+class ServerInterceptor(grpc.ServerInterceptor, metaclass=abc.ABCMeta):
     """Base class for server-side interceptors.
 
     To implement an interceptor, subclass this class and override the intercept method.
@@ -43,13 +43,13 @@ def intercept(
     def intercept_service(self, continuation, handler_call_details):
         """Implementation of grpc.ServerInterceptor.
 
-        This is not part of the ServiceInterceptor API, but must have a public name.
-        Do not override it, unless you know what you're doing.
+        This is not part of the grpc_interceptor.ServerInterceptor API, but must have
+        a public name. Do not override it, unless you know what you're doing.
         """
         next_handler = continuation(handler_call_details)
         # Make sure it's unary_unary:
         if next_handler.request_streaming or next_handler.response_streaming:
-            raise ValueError("ServiceInterceptor only handles unary_unary")
+            raise ValueError("ServerInterceptor only handles unary_unary")
 
         def invoke_intercept_method(request, context):
             next_interceptor_or_implementation = next_handler.unary_unary
@@ -100,7 +100,7 @@ def parse_method_name(method_name: str) -> MethodName:
 
     Arguments:
         method_name: A string of the form "/foo.bar.SearchService/Search", as passed to
-            ServiceInterceptor.intercept().
+            ServerInterceptor.intercept().
 
     Returns:
         A MethodName object.

src/grpc_interceptor/testing/dummy_client.py

@@ -9,7 +9,7 @@
 
 import grpc
 
-from grpc_interceptor.base import ServiceInterceptor
+from grpc_interceptor.server import ServerInterceptor
 from grpc_interceptor.testing.protos import dummy_pb2_grpc
 from grpc_interceptor.testing.protos.dummy_pb2 import DummyRequest, DummyResponse
 
@@ -45,7 +45,7 @@ def Execute(
 @contextmanager
 def dummy_client(
     special_cases: Dict[str, SpecialCaseFunction],
-    interceptors: List[ServiceInterceptor],
+    interceptors: List[ServerInterceptor],
 ):
     """A context manager that returns a gRPC client connected to a DummyService."""
     server = grpc.server(

tests/test_base.py → tests/test_server.py

@@ -1,15 +1,15 @@
-"""Test cases for the grpc-interceptor base ServiceInterceptor."""
+"""Test cases for the grpc-interceptor base ServerInterceptor."""
 
 from collections import defaultdict
 
 import grpc
 import pytest
 
-from grpc_interceptor.base import MethodName, parse_method_name, ServiceInterceptor
+from grpc_interceptor import MethodName, parse_method_name, ServerInterceptor
 from grpc_interceptor.testing import dummy_client, DummyRequest
 
 
-class CountingInterceptor(ServiceInterceptor):
+class CountingInterceptor(ServerInterceptor):
     """A test interceptor that counts calls and exceptions."""
 
     def __init__(self):
@@ -26,7 +26,7 @@ def intercept(self, method, request, context, method_name):
             raise
 
 
-class SideEffectInterceptor(ServiceInterceptor):
+class SideEffectInterceptor(ServerInterceptor):
     """A test interceptor that calls a function for the side effect."""
 
     def __init__(self, side_effect):
@@ -38,7 +38,7 @@ def intercept(self, method, request, context, method_name):
         return method(request, context)
 
 
-class UppercasingInterceptor(ServiceInterceptor):
+class UppercasingInterceptor(ServerInterceptor):
     """A test interceptor that modifies the request by uppercasing the input field."""
 
     def intercept(self, method, request, context, method_name):
@@ -47,7 +47,7 @@ def intercept(self, method, request, context, method_name):
         return method(request, context)
 
 
-class AbortingInterceptor(ServiceInterceptor):
+class AbortingInterceptor(ServerInterceptor):
     """A test interceptor that aborts before calling the handler."""
 
     def __init__(self, message):