Install & Compatibility
Where this runs
tested against v1.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 40.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.000s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FoyerV1Pb2
✓ import ghome_foyer_api
✗ import ghome_foyer_api.foyer_v1_pb2
Demonstrates how to import the generated stubs and create a gRPC client stub for the Foyer service. This quickstart assumes a gRPC server implementing the Google Home Foyer API is running and accessible at the specified `SERVER_ADDRESS`.
import grpc
from ghome_foyer_api import foyer_v1_pb2_grpc, foyer_v1_pb2
import os
# This library provides generated protobuf/gRPC stubs for the Google Home Foyer API.
# It requires a running gRPC server that implements this API (e.g., a Google Home device
# exposing the Foyer API on the local network) to be functional.
# Replace with the actual address of your Google Home Foyer API server.
# For local testing or development, 'localhost:50051' is a common placeholder.
SERVER_ADDRESS = os.environ.get('GHOME_FOYER_API_SERVER_ADDRESS', 'localhost:50051')
try:
# Establish an insecure gRPC channel to the server.
# For production environments, consider secure channels (e.g., `grpc.ssl_channel`).
with grpc.insecure_channel(SERVER_ADDRESS) as channel:
# Create a stub for the Foyer service.
# This object exposes the RPC methods defined in the Foyer API.
stub = foyer_v1_pb2_grpc.FoyerStub(channel)
print(f"Successfully created FoyerStub for server at {SERVER_ADDRESS}")
print("To interact, call specific RPC methods defined in the Foyer API using 'stub.'")
# Example (illustrative, actual method names and parameters vary per API):
# request = foyer_v1_pb2.GetDeviceInfoRequest(device_id='some_id')
# response = stub.GetDeviceInfo(request)
# print(f"Device Info: {response}")
except grpc.RpcError as e:
print(f"Error connecting or calling gRPC: {e.code().name} - {e.details()}")
print("Ensure the gRPC server is running and accessible at the specified address.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingProtobuf version compatibility is critical. This library is sensitive to the `protobuf` and `grpcio` versions installed. Mismatches can lead to serialization errors or runtime crashes. Check the `pyproject.toml` or `setup.py` for exact dependency ranges.fixEnsure `protobuf` and `grpcio` versions installed align with the `ghome-foyer-api`'s declared dependencies. Consider using a `pip compile` workflow or virtual environments to manage dependencies strictly.
affects: All versions, especially when upgrading `protobuf` or `grpcio` separately.
gotchaThis library provides only generated *stubs* for the Google Home Foyer API. It does not implement the API itself or provide a direct connection to public Google services. You must have access to a gRPC server (e.g., a local Google Home device or an emulator) that exposes the Foyer API for these stubs to be functional.fixUnderstand that this is a client-side stub library. You need a separate gRPC server implementing the Foyer API to connect to. This is often an internal API used on local networks.
affects: All versions.
deprecatedOlder versions (prior to v1.1.0) only supported Protobuf v4. Version v1.1.0 added support for Protobuf v5, and v1.2.0 added support for Protobuf v6. Using an older version of this library with newer Protobuf installations, or vice versa, can lead to incompatibility issues.fixUpgrade to the latest version of `ghome-foyer-api` (>=1.2.0) to ensure compatibility with Protobuf v5 and v6. Always ensure your `grpcio` and `protobuf` versions are within the library's specified ranges.
affects: <1.2.0 (for protobuf v6), <1.1.0 (for protobuf v5)
Upgrade
Version history
1.2.2latest on PyPI · released May 30, 2025
Audit
Dependencies
protobufrequiredRequired runtime dependency for protobuf message serialization/deserialization.
grpciorequiredRequired runtime dependency for gRPC communication.