frequenz-floss / frequenz-client-base-python

Base gRPC client

Frequenz Client Base Library

Introduction

Utilities for writing Frequenz API clients

Supported Platforms

The following platforms are officially supported (tested):

• Python: 3.11
• Operating System: Ubuntu Linux 20.04
• Architectures: amd64, arm64

Contributing

If you want to know how to build this project and contribute to it, please check out the Contributing Guide.

frequenz-client-base-python's Issues

Add wrappers for gRPC errors

What's needed?

We need to make sure gRPC errors are properly wrapped so we don't leak the use of grpc/protobuf to client users.

From frequenz-floss/frequenz-api-dispatch#144:

gRPC errors in Python are raised as grpc.RpcError exceptions. Here's how to handle them:

import grpc

try:
    response = await self._stub.GetMicrogridDispatch(request)
    # Process the successful response here

except grpc.RpcError as error:
    status_code = error.code()  # Get the gRPC status code
    details = error.details()   # Optional error details as a string 

    # Example of handling based on status code
    if status_code == grpc.StatusCode.NOT_FOUND:
        print("Resource not found!")
    elif status_code == grpc.StatusCode.PERMISSION_DENIED:
        print("Insufficient permissions")
    else: 
        print(f"Error occurred: {status_code} - {details}")

Proposed solution

Add wrapper error classes for the relevant gRPC errors raised by clients.

Some of these errors should inherit from specific Python built-in errors, like INVALID_ARGUMENT should inherit from ValueError, NOT_FOUND and ALREADY_EXISTS should probably inherit from KeyError, etc.

For errors that should never occur (because the client is doing some sanity checks to prevent them from happening), we should probably still have a wrapper in the client, like UnexpectedError, because a server could always misbehave for some reason.

When raising these errors in the client, we can still attach the original gRPC error using the raise OurClientError(...) from grpc_error syntax, which could be very useful for debugging purposes.

Additional context

• frequenz-floss/frequenz-api-dispatch#144 (comment)

Create a `GrpcApiClient` base class

What's needed?

We need to standarize how we create clients, how to pass the destination to connect too, and how we close/cleanup the clients.

Proposed solution

Create a new base class called GrpcApiClient with at least some basic functionality, like:

class GrpcApiClient(Generic[T]):
        def __init__(self, target: str, create_stub: Callable[[GrpcChannel], T]):
            self._target = target
            self._channel = grpcaio.insecure_channel(target)
            self._stub: T = create_stub(self._grpc_channel)

    async def close(self, timeout: timedelta | None = None) -> None:
        await self._channel.close(grace=timeout.total_seconds() if timeout else None)

    async def __aenter__(self) -> "ReportingClient":
        return self

    async def __aexit__(
        self,
        _exc_type: Type[BaseException] | None,
        _exc_val: BaseException | None,
        _exc_tb: Any | None,
    ) -> bool | None:
        await self.close()
        return None

Use cases

No response

Alternatives and workarounds

Some clients take a grpc channel, and some a connection string. The advantage of taking a channel is users can chose which type of channel to use (insecure vs. secure for example), the disadvantage is we'll leak the dependency to grpc.

We could extend the connection string to chose if the channel should be secure or insecure, so we could have the best of both world. This would also enable to take connection strings directly from configuration files.

We might need a bit more research, maybe something like that already exists.

Additional context

• frequenz-floss/frequenz-client-reporting-python#16 (comment)

Investigate and add tools to mock the grpc service to write unit tests

What's needed?

We need to be able to easily and reliably write unit tests for all API clients without having to spin up a server (real or mocked) for the tests.

Proposed solution

Add some utilities to mock the main grpc service, so we can somehow inject replies it should provide when some request is sent.

Use cases

No response

Alternatives and workarounds

Long term we could explore doing a more capable framework, [pytest-httpserver](https://pytest-httpserver.readthedocs.io/en/latest/ or even )like vcr (maybe it can be extended?) to record real responses from the server and then replay them in unit tests.

Additional context

No response