Install & Compatibility
Where this runs
tested against v0.32.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 54.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.9s · import 0.000s · 53MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgentStub
✓ from isolate_proto import AgentStub
✗ from isolate_controller_pb2_grpc import IsolateServiceStub
AgentServicer
✓ from isolate_proto import AgentServicer
CreateEnvironmentRequest
✓ from isolate_proto import CreateEnvironmentRequest
This quickstart demonstrates a typical client-side interaction with an Isolate Controller gRPC service. It assumes the necessary Python protobuf and gRPC stub files (`_pb2.py` and `_pb2_grpc.py`) have been generated from the official `.proto` definitions. Users would then import the specific service stubs and message types to make RPC calls to a running Isolate Controller gRPC server.
import grpc
# Assuming you have generated isolate_controller_pb2.py and isolate_controller_pb2_grpc.py
# from the official .proto definitions. These files would typically be
# created by running 'python -m grpc_tools.protoc ...' against the .proto files.
# Placeholder imports - replace with actual generated module names and symbols
# based on the Isolate Controller's .proto files.
try:
from isolate_controller_pb2 import IsolateRequest, IsolateResponse
from isolate_controller_pb2_grpc import IsolateServiceStub
except ImportError:
print("Generated protobuf files (e.g., isolate_controller_pb2.py) not found.")
print("Please ensure you have generated them from the official .proto definitions using grpc_tools.protoc.")
exit(1)
def run_client():
# Replace 'localhost:50051' with the actual Isolate Controller gRPC server address
with grpc.insecure_channel('localhost:50051') as channel:
stub = IsolateServiceStub(channel)
try:
# Example request - replace with actual fields from IsolateRequest
request = IsolateRequest(name="example_task", payload=b"some_data")
response = stub.ExecuteTask(request)
print(f"Isolate Controller Response: {response.status}")
except grpc.RpcError as e:
print(f"Error communicating with Isolate Controller: {e.details}")
if __name__ == '__main__':
# This quickstart demonstrates client-side usage of the generated stubs.
# To run this, you'd also need a running gRPC server implementing the
# IsolateService as defined in the .proto files.
print("This is a placeholder quickstart. Actual usage requires generated")
print("protobuf files and a running Isolate Controller gRPC server.")
run_client()
Debug
Known issues
gotchaThis package is described as providing '(internal) gRPC definitions' on PyPI. This implies it might not be intended for general public consumption, potentially leading to a lack of comprehensive external documentation, breaking changes without public announcements, or limited support for external users.fixExercise caution when using this internal library for external projects. Monitor changes in the upstream 'Isolate' project (if applicable) for potential breaking changes or API shifts.
affects: All versions
breakingProtobuf definitions are sensitive to changes. Renaming fields, changing field numbers, altering data types, or removing fields in `.proto` files can lead to backward incompatibility, causing deserialization failures or incorrect data interpretation in existing clients and services.fixStrictly follow protobuf compatibility guidelines. Use tools like `buf` or `protoc` with `--check_compatibility` flags in CI/CD pipelines to detect breaking changes before deployment. Introduce new versions of services/messages for incompatible changes (e.g., `ServiceV2`).
affects: All versions
gotchaThe `isolate-proto` package lists `Python >=3.8` as a requirement, but the core `protobuf` runtime library (a necessary dependency for generated `.proto` code) officially requires `Python >=3.10` since version 7.x (e.g., protobuf 7.34.1). This discrepancy can lead to `ImportError` or runtime issues on Python 3.8 or 3.9 environments if a recent `protobuf` version is installed.fixEnsure your Python environment is `3.10` or higher to avoid compatibility issues with the `protobuf` runtime. If a lower Python version must be used, try to pin an older compatible `protobuf` version, though this may limit functionality or security updates.
affects: 0.x.x, especially when used with `protobuf` versions >= 7.0
gotchaTo generate Python client/server code from `.proto` files, you need `grpcio-tools` and the `protoc` compiler. While `isolate-proto` provides pre-generated code, understanding and being able to regenerate these files is crucial for development, debugging, or integrating with custom `.proto` definitions.fixInstall `grpcio-tools` (`pip install grpcio-tools`) and ensure `protoc` is available in your PATH. Familiarize yourself with how to compile `.proto` files into Python stubs: `python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. your_service.proto`.
affects: All versions
Upgrade
Version history
0.32.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
protobufrequiredRequired runtime library for working with Protocol Buffers generated code.
grpciorequiredRequired runtime library for gRPC communication.