buildgrid.server.servicer module

class buildgrid.server.servicer.Instance

Bases: ABC

An Instance is the underlying implementation of a given Servicer.

SERVICE_NAME: ClassVar[str]

The expected FULL_NAME of the Service which will wrap this instance. This value should be declared on the class of any Instance implementations.

set_instance_name(instance_name: str) → None

Set the instance name associated with this instance. This method may be overriden if extra referencing is required.

Parameters:

instance_name (str) – The new instance’s name.

Raises:

AssertionError – if the instance is already registered.

property instance_name: str

The name of the instance

start() → None

A method called when the grpc service is starting.

This method may be overriden if startup logic is required.

stop() → None

A method called when the grpc service is shutting down.

This method may be overriden if shutdown logic is required.

class buildgrid.server.servicer.InstancedServicer

Bases: ABC, Generic[_Instance]

REGISTER_METHOD: ClassVar[Callable[[Any, Server], None]]

The method to be invoked when attaching the service to a grpc.Server instance. This value should be declared on the class of any Servicer implementations.

FULL_NAME: ClassVar[str]

The full name of the servicer, used to match instances to the servicer and configure reflection. This value should be declared on the class of any Servicer implementations.

setup_grpc(server: Server) → None

A method called when the Service is being attached to a grpc server.

start() → None

stop() → None

property enabled: bool

By default, a servicer is disabled if there are no registered instances. If a servicer is not enabled, it will not be attached to the grpc.Server instance.

This property may be overriden if servicer enablement follows other rules.

add_instance(name: str, instance: _Instance) → None

Adds an instance to the servicer.

This method may be overriden if adding an instance requires additional setup.

Parameters:

• name (str) – The name of the instance.

• instance (_Instance) – The instance implementation.

get_instance(instance_name: str) → _Instance

Provides a wrapper to access the instance, throwing a InvalidArgumentError if the instance requested does not exist.

This method may be overriden if you wish to create a custom error message.

Parameters:

instance_name (str) – The name of the instance.

Returns:

The requested instance.

Return type:

_Instance

cast(instance: Instance) → _Instance | None

A helper tool used by the BuildGrid Server startup logic to determine the correct servicer to attach an instance to. This method will also cast the instance to the correct type required by the servicer implementation.

Parameters:

instance (Instance) – The instance to check.

Returns:

The validated instance or None if invalid.

Return type:

Optional[_Instance]