v0.7.0

Frequenz Client Base Library Release Notes

Summary

This release improves the BaseApiClient interface and introduces HTTP2 keep-alive, among other changes.

Upgrading

• GrpcStreamBroadcaster now takes a AsyncIterable instead of a AsyncIterator as the stream_method. This is to match the type of streaming methods generated by grpc, so no conversion to an AsyncIterator is needed.

• GrpcStreamBroadcaster no longer tries to reconnect when a server closes a connection. This behaviour can be overridden by passing retry_on_exhausted_stream=True when constructing GrpcStreamBroadcaster instances.

• gRPC URLs don't have a default port anymore, unless a default is set via ChannelOptions. If you want to set a default port for URLs, please pass custom ChannelOptions as defaults to parse_grpc_uri or as channel_defaults to BaseApiClient.

• The ExponentialBackoff and LinearBackoff classes now require keyword arguments for their constructor. This change was made to make the classes easier to use and to avoid confusion with the order of the arguments.

• HTTP2 keep-alive is now enabled by default, with an interval of 60 seconds between pings, and a 20 second timeout for responses from the service. These values are configurable and may be updated based on specific requirements.

• The BaseApiClient class is not generic anymore, and doesn't take a function to create the stub. Instead, subclasses should create their own stub right after calling the parent constructor. This enables subclasses to cast the stub to the generated XxxAsyncStub class, which have proper async type hints. To convert you client:

  # Old
  from my_service_pb2_grpc import MyServiceStub
  class MyApiClient(BaseApiClient[MyServiceStub]):
      def __init__(self, server_url: str, *, ...) -> None:
          super().__init__(server_url, MyServiceStub, ...)
          ...
  
  # New
  from __future__ import annotations
  from typing import cast
  import my_service_pb2_grpc
  class MyApiClient(BaseApiClient):
      def __init__(self, server_url: str, *, ...) -> None:
          super().__init__(server_url, connect=connect)
          self._stub = cast(
              my_service_pb2_grpc.MyServiceAsyncStub,
              my_service_pb2_grpc.MyServiceStub(self.channel),
          )
          ...
  
      @property
      def stub(self) -> my_service_pb2_grpc.MyServiceAsyncStub:
          if self.channel is None:
              raise ClientNotConnected(server_url=self.server_url, operation="stub")
          return self._stub

  You probably also need to ignore the no-member check from pylint, as pylint doesn't read *.pyi files, so it won't find the async stub and complain.

  [tool.pylint.messages_control]
  disable = [
    # [..]
    # Checked by mypy
    "no-member",
    # [..]
  ]

  After this, you should be able to remove a lot of casts or type: ignore from the code when calling the stub async methods.

New Features

• Added support for HTTP2 keep-alive.

What's Changed

• Clear release notes by @shsms in #83
• Replace the stream_method return to AsyncIterable by @llucax in #87
• Don't allow a default port in URLs by default by @llucax in #85
• Bump the required group with 9 updates by @dependabot in #89
• Don't retry by default when the stream is exhausted by @shsms in #91
• Support http2 keep-alive by @shsms in #90
• Remove generic type from BaseApiClient by @llucax in #92
• Prepare for v0.7.0 by @shsms in #93

Full Changelog: v0.6.1...v0.7.0

v0.6.1

Frequenz Client Base Library Release Notes

Bug Fixes

• Fixes a bug in creating grpc channels from ipv6 URIs.

What's Changed

• Clear release notes by @llucax in #76
• Bump the required group with 9 updates by @dependabot in #78
• Use netloc from urlparse to specify the host by @shsms in #79
• Prepare release notes for v0.6.1 by @shsms in #82

Full Changelog: v0.6.0...v0.6.1

v0.6.0

Frequenz Client Base Library Release Notes

Summary

This version removes grpclib support and adds new SSL options to the connection URI.

Upgrading

• grpclib was removed, if you used grpclib you should switch to grpcio instead.

  You should also update your dependency to frequenz-client-base (without any [grpclib] or [grpcio] suffix). Also, now there is no need to pass around the channel type to the BaseApiClient or the parse_grpc_uri function.

• The parse_grpc_uri function (and BaseApiClient constructor) now enables SSL by default (ssl=false should be passed to disable it).

• The parse_grpc_uri and BaseApiClient function now accepts a set of defaults to use when the URI does not specify a value for a given option.

New Features

• The connection URI can now have a few new SSL options:

  • ssl_root_certificates_path to specify the path to the root certificates file.
  • ssl_private_key_path to specify the path to the private key file.
  • ssl_certificate_chain_path to specify the path to the certificate chain file.

What's Changed

• Clear release notes by @llucax in #64
• Use SSL by default by @llucax in #67
• Remove support for grpclib by @llucax in #71
• Bump the required group across 1 directory with 13 updates by @dependabot in #72
• Allow passing SSL options via server URL by @llucax in #73
• Prepare release notes for v0.6.0 by @llucax in #75

Full Changelog: v0.5.0...v0.6.0

v0.5.0

Frequenz Client Base Library Release Notes

Summary

The main features of this release is the new base class for API clients, gRPC exception wrappers and a new utility function to call stub methods.

Upgrading

• channel.parse_grpc_uri() takes an extra argument, the channel type (which can be either grpclib.client.Channel or grpcio.aio.Channel).

New Features

• Add a exception module to provide client exceptions, including gRPC errors with one subclass per gRPC error status code.
• channel.parse_grpc_uri() can now be used with grpcio too.
• A new BaseApiClient class is introduced to provide a base class for API clients. It is strongly recommended to use this class as a base class for all API clients.
• A new call_stub_method() function to simplify calling stub methods, converting gRPC errors to ApiClientErrors, checking if the client is connected and optionally wrapping the response.

What's Changed

• Clear the release notes by @llucax in #53
• Add client exceptions by @llucax in #55
• Bump the required group with 7 updates by @dependabot in #57
• Add grpcio support to parse_grpc_uri() by @llucax in #54
• Add a BaseApiClient class by @llucax in #56
• Improve type-checking for _grpchacks by @llucax in #59
• Add a function to call gRPC stubs and wrap errors by @llucax in #58
• Bump docker/build-push-action from 5 to 6 by @dependabot in #61
• Bump the required group with 9 updates by @dependabot in #60
• Bump brettcannon/check-for-changed-files from 1.2.0 to 1.2.1 by @dependabot in #62
• Prepare release notes for the 0.5 release by @llucax in #63

Full Changelog: v0.4.0...v0.5.0

v0.4.0

Frequenz Client Base Library Release Notes

Summary

Upgrading

• You should now install the dependency using frequenz-client-base[grpcio] (or frequenz-client-base[grpclib]) if you want to migrate to grpclib).
• GrpcStreamBroadcaster's stream_method callback now should return an AsyncIterator instead of a grpc.aio.UnaryStreamCall, this is so it is compatible with both grpcio and grpclib. Normally no changes should be needed, as a grpc.aio.UnaryStreamCall should be a AsyncIterator, but since grpcio doesn't have correct type hints, you might need to adjust the cast() if you are using one.

New Features

• GrpcStreamBroadcaster is now compatible with both grpcio and grpclib implementations of gRPC. Just install frequenz-client-base[grpcio] or frequenz-client-base[grpclib] to use the desired implementation and everything should work as expected.
• A new module channel with a function to parse URIs to create grpclib client Channel instances.

Bug Fixes

• Fixed retrying for GrpcStreamBroadcaster when the retry interval is set to 0 (before it would stop retrying if the interval was set to 0).

What's Changed

• Clear RELEASE_NOTES.md by @shsms in #36
• Bump types-protobuf from 4.24.0.20240129 to 4.24.0.20240311 by @dependabot in #39
• Bump nox from 2023.4.22 to 2024.3.2 by @dependabot in #38
• Update protobuf requirement from <5,>=4.21.6 to >=4.21.6,<6 by @dependabot in #40
• Bump the optional group with 10 updates by @dependabot in #43
• Bump the required group with 7 updates by @dependabot in #44
• Bump types-protobuf from 4.24.0.20240311 to 5.26.0.20240422 by @dependabot in #45
• Remove TODOs by @llucax in #46
• Bump repo-config to v0.9.2 by @llucax in #47
• Fix the condition to run the nox-(cross-arch-)?all jobs by @llucax in #48
• ci: Fix pip cache post step by @llucax in #50
• Make GrpcStreamBroadcaster compatible with both grpcio and grpclib by @llucax in #49
• Fix GrpcStreamBroadcaster retry with a 0 interval by @llucax in #52
• Add parsing of gRPC channel URIs by @llucax in #51

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

v0.3.0

Frequenz Client Base Library Release Notes

Summary

This release updates the minimum required frequenz-channels version is updated
to v1.0.0-rc1. This is a breaking change, because the channels API has changed.

Upgrading

Follow the upgrading instructions from the new channel release: v1.0.0-rc1.

What's Changed

• Don't create nox sessions twice in cross-arch tests by @llucax in #34
• Clear release notes by @llucax in #33
• Update minimum frequenz-channels version to v1.0.0-rc1 by @shsms in #35

Full Changelog: v0.2.1...v0.3.0

v0.2.1

Frequenz Client Base Library Release Notes

Summary

• The generated docs now show the type of symbol in the table of contents and have cross-linking to the protobuf and channels documentation.
• The minimum supported version of protobuf was downgraded to 4.21.6, so downstream projects having this older version as minimum requirements can still use this release.

What's Changed

• Clear release notes by @llucax in #28
• Bump the optional group with 10 updates by @dependabot in #29
• Downgrade minimum protobuf to 4.21.6 by @llucax in #30
• Improve generated docs by @llucax in #31
• Prepare release notes for v0.2.1 by @llucax in #32

Full Changelog: v0.2.0...v0.2.1

v0.2.0

Frequenz Client Base Library Release Notes

Summary

This release does a bit of restructuring and renaming of classes and modules. It also adds some new features and fixes some bugs.

Upgrading

The project structure was updated to use more consistent and shorter modules and class names.

• frequenz.client.base.grpc_streaming_helper was renamed to frequenz.client.base.streaming.

  • The GrpcStreamingHelper class was renamed to GrpcStreamBroadcaster.

    • The constructor argument retry_spec was renamed to retry_strategy.

• frequenz.client.base.retry_strategy was renamed to frequenz.client.base.retry.

  • The RetryStrategy class was renamed to Strategy.

New Features

• Functions to convert to datetime and protobufs Timestamp have been added.
• The generated documentation was improved to include information on defaults and generic parameters.

Bug Fixes

• When copying RetryStrategys, the type now will be correctly set to the original type.

What's Changed

• Clear RELEASE_NOTES.md by @shsms in #7
• Bump the optional group with 16 updates by @dependabot in #8
• Bump actions/cache from 3 to 4 by @dependabot in #17
• Bump the optional group with 4 updates by @dependabot in #12
• Bump types-markdown from 3.5.0.3 to 3.5.0.20240129 by @dependabot in #14
• Bump flake8 from 6.1.0 to 7.0.0 by @dependabot in #16
• Bump black from 23.12.1 to 24.1.1 by @dependabot in #13
• Bump actions/setup-python from 4 to 5 by @dependabot in #2
• Update to channels v1.0.0-beta.1 by @Marenz in #18
• Bump actions/{download,upload}-artifact from 3 to 4 by @dependabot in #10
• Fix typo Freqenz -> Frequenz by @llucax in #21
• docs: Add cross-referencing for gRPC by @llucax in #22
• Add datetime and Timestamp conversion functions by @Marenz in #20
• Bump actions/labeler from 4.3.0 to 5.0.0 by @dependabot in #1
• Improve docs and fix copy() type by @llucax in #23
• Restructure modules and class names by @llucax in #25
• Prepare release notes for v0.2.0 by @llucax in #27

New Contributors

• @dependabot made their first contribution in #8
• @Marenz made their first contribution in #18
• @llucax made their first contribution in #21

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Freqenz Client Base Library Release Notes

Summary

First release of the Freqenz Client Base Library, that exposes a retry strategy implementations and a generic grpc streaming helper.

Upgrading

New Features

• Imports retry strategies and the generic grpc streaming helper from the SDK.

Bug Fixes

What's Changed

• Add a grpc streaming helper by @shsms in #4
• Release preparation by @shsms in #6

New Contributors

• @shsms made their first contribution in #4

Full Changelog: https://github.com/frequenz-floss/frequenz-client-base-python/commits/v0.1.0