From 619c6fd726890d8faa49cbc5177bc0b73da9bdfc Mon Sep 17 00:00:00 2001 From: ivanauth Date: Wed, 8 Jul 2026 20:45:08 -0400 Subject: [PATCH] docs: add upgrade note for broken google imports Wheels for v1.23.0 through v1.24.3 vendored modules under the google namespace at the same paths owned by googleapis-common-protos, so uninstalling those versions during an upgrade deletes files that googleapis-common-protos needs and imports like google.api.annotations_pb2 start failing. Document how to restore the missing files. Signed-off-by: ivanauth --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 1a8233f..dfcd90f 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,25 @@ pip install authzed [Python Package Index]: https://pypi.org/project/authzed [pip]: https://pip.pypa.io +#### Upgrading from v1.23.0 through v1.24.3 + +Releases v1.23.0 through v1.24.3 (and the earlier v1.22.2 release candidates) bundled modules in the `google` namespace that are also provided by the `googleapis-common-protos` package; v1.24.4 and later no longer do. +Because of this, upgrading from one of those releases deletes files that `googleapis-common-protos` needs, resulting in errors such as: + +``` +ImportError: cannot import name 'annotations_pb2' from 'google.api' (unknown location) +``` + +If you see this error after upgrading, reinstall `googleapis-common-protos` to restore the missing files: + +```sh +pip install --force-reinstall --no-deps googleapis-common-protos +``` + +If you use another package manager, use its equivalent reinstall command (with [uv], `uv pip install --reinstall-package googleapis-common-protos googleapis-common-protos`) or recreate your virtual environment. + +[uv]: https://docs.astral.sh/uv/ + ### Initializing a client With the exception of [gRPC] utility functions found in `grpcutil`, everything required to connect and make API calls is located in a module respective to API version.