v0.4.0

Frequenz Microgrid API Client Release Notes

Summary

This release migrates to use betterproto and grpclib instead of grpcio and protobuf internally. It also stops leaking these internal libraries to downstream users. It should now be possible to use the client without having to use grpclib or betterproto directly.

Upgrading

• The client now uses a string URL to connect to the server, the grpc_channel and target arguments are now replaced by server_url. The current accepted format is grpc://hostname[:<port:int=9090>][?ssl=<ssl:bool=false>], meaning that the port and ssl are optional and default to 9090 and false respectively. You will have to adapt the way you connect to the server in your code.

• The client is now using grpclib to connect to the server instead of grpcio. You might need to adapt your code if you are using grpcio directly.

• The client now doesn't raise grpc.aio.RpcError exceptions anymore. Instead, it raises its own exceptions, one per gRPC error status code, all inheriting from GrpcError, which in turn inherits from ClientError (as any other exception raised by this library in the future). GrpcErrors have the grpclib.GRPCError as their __cause__. You might need to adapt your error handling code to catch these specific exceptions instead of grpc.aio.RpcError.

  You can also access the underlying grpclib.GRPCError using the grpc_error attribute for GrpStatusError exceptions, but it is discouraged because it makes downstream projects dependant on grpclib too

• The client now uses protobuf/grpc bindings generated betterproto (frequenz-microgrid-betterproto) instead of grpcio (frequenz-api-microgrid). If you were using the bindings directly, you might need to do some minor adjustments to your code.

• If an unknown EV charger component state is received, it will now be set to EVChargerComponentState.UNKNOWN instead of EVChargerComponentState.UNSPECIFIED.

New Features

• The client now raises more specific exceptions based on the gRPC status code, so you can more easily handle different types of errors.

  For example:

  try:
     connections = await client.connections()
  except OperationTimedOut:
     ...

  instead of:

  try:
     connections = await client.connections()
  except grpc.aio.RpcError as e:
     if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        ...

• We now expose component errors as part of the streamed component data:

  • BatteryData.errors
  • InverterData.errors

• We now expose component states as part of the streamed component data:

  • BatteryData.component_state and BatteryData.relay_state
  • InverterData.component_state

• Added the missing EVChargerComponentState.UNKNOWN state.

Bug Fixes

• Fix a leakage of GrpcStreamBroadcaster instances.
• The user-passed retry strategy was not properly used by the data streaming methods.
• The client set_bounds() method might have not done anything and if it did, errors were not properly raised.

What's Changed

• Clear release notes by @llucax in #32
• Bump nox from 2023.4.22 to 2024.3.2 by @dependabot in #35
• Update protobuf requirement from <5,>=4.21.6 to >=4.21.6,<6 by @dependabot in #34
• Bump nox from 2024.3.2 to 2024.4.15 in the required group by @dependabot in #38
• Improve exception messages by @llucax in #43
• Fix a few bugs related to GrpcStreamBroadcaster by @llucax in #42
• Bump client-base to v0.4.0 by @llucax in #44
• Properly await for AddInclusionBounds by @llucax in #47
• Allow using None to specify the default retry strategy by @llucax in #46
• Raise a new ClientError instead of AioRpcError by @llucax in #48
• Convert to betterproto by @llucax in #37
• Make the client accept a server URL to connect to by @llucax in #49
• Add specific gRPC client errors by @llucax in #53
• Add missing state and error wrappers by @llucax in #54

Full Changelog: v0.3.0...v0.4.0