buildgrid.server.job module

class buildgrid.server.job.Job(*, do_not_cache: bool, action: Action, action_digest: Digest, platform_requirements: Dict[str, Set[str]] | None = None, priority: int = 0, name: str | None = None, operation_names: Set[str] | None = None, cancelled_operation_names: Set[str] | None = None, lease: Lease | None = None, stage: OperationStage = OperationStage.UNKNOWN, cancelled: bool = False, queued_timestamp: Timestamp | None = None, queued_time_duration: Duration | None = None, worker_start_timestamp: Timestamp | None = None, worker_completed_timestamp: Timestamp | None = None, result: ExecuteResponse | None = None, worker_name: str | None = None, n_tries: int = 0, status_code: int | None = None, stdout_stream_name: str | None = None, stdout_stream_write_name: str | None = None, stderr_stream_name: str | None = None, stderr_stream_write_name: str | None = None)

Bases: object

property name: str
property cancelled: bool
property priority: int
set_priority(new_priority: int, *, data_store: DataStoreInterface) None
property done: bool
property platform_requirements: Dict[str, Set[str]]
property do_not_cache: bool
property action_digest: Digest
property action: Action
property operation_stage: OperationStage
property operation_metadata: ExecuteOperationMetadata
property action_result: ActionResult | None
property execute_response: ExecuteResponse
property holds_cached_result: bool
property queued_timestamp: Timestamp
property queued_timestamp_as_datetime: datetime | None
property queued_time_duration: Duration
property worker_start_timestamp: Timestamp
property worker_start_timestamp_as_datetime: datetime | None
property worker_completed_timestamp: Timestamp
property worker_completed_timestamp_as_datetime: datetime | None
mark_worker_started() None
get_metadata(writeable_streams: bool = False) ExecuteOperationMetadata
set_action_url(url: BrowserURL) None

Generates a CAS browser URL for the job’s action.

set_cached_result(action_result: ActionResult, data_store: DataStoreInterface) None

Allows specifying an action result from the action cache for the job.


This won’t trigger any Operation stage transition.


action_result (ActionResult) – The result from cache.

n_peers(watch_spec: JobWatchSpec | None) int
n_peers_for_operation(operation_name: str, watch_spec: JobWatchSpec | None) int
register_new_operation(*, data_store: DataStoreInterface, request_metadata: RequestMetadata | None = None, client_identity: ClientIdentityEntry | None = None) str

Subscribes to a new job’s Operation stage changes.


The name of the subscribed Operation.

Return type:


get_all_operations() List[Operation]

Gets all Operation objects related to a job.


A list of Operation objects.

Return type:


get_operation(operation_name: str) Operation
Returns a copy of the the job’s Operation

with all the fields populated from the job fields


operation_name (str) – the operation’s name.


NotFoundError – If no operation with operation_name exists.

update_operation_stage(stage: OperationStage, *, data_store: DataStoreInterface) None

Operates a stage transition for the job’s Operation.


stage (OperationStage) – the operation stage to transition to.

cancel_all_operations(*, data_store: DataStoreInterface) None
cancel_operation(operation_name: str, *, data_store: DataStoreInterface) None

Triggers a job’s Operation cancellation.

This may cancel any job’s Lease that may have been issued.


operation_name (str) – the operation’s name.


NotFoundError – If no operation with operation_name exists.

property lease: Lease | None
property lease_state: LeaseState | None
property lease_cancelled: bool
property n_tries: int
property status_code: int | None
create_lease(worker_name: str, bot_id: str | None = None, *, data_store: DataStoreInterface) Lease | None

Emits a new Lease for the job.

Only one Lease can be emitted for a given job. This method should only be used once, any further calls are ignored.

  • worker_name (string) – The name of the worker this lease is for.

  • bot_id (string) – The name of the corresponding bot for this job’s worker.

update_lease_state(state: LeaseState, status: Status | None = None, result: Any | None = None, action_cache: ActionCacheABC | None = None, *, data_store: DataStoreInterface, skip_lease_persistence: bool = False, skip_notify: bool = False) None

Operates a state transition for the job’s current Lease.

  • state (LeaseState) – the lease state to transition to.

  • status (google.rpc.Status, optional) – the lease execution status, only required if state is COMPLETED.

  • result (google.protobuf.Any, optional) – the lease execution result, only required if state is COMPLETED.

  • action_cache (ActionCache) – The ActionCache object, only needed to store results

  • skip_lease_persistence (bool) – Whether to skip storing the lease in the datastore for now

  • skip_notify (bool) – Whether to skip notifying of job changes

cancel_lease(*, data_store: DataStoreInterface) None

Triggers a job’s Lease cancellation.


This will not cancel the job’s Operation.

delete_lease() None

Discard the job’s Lease.


This will not cancel the job’s Operation.

set_stdout_stream(logstream: LogStream, *, data_store: DataStoreInterface) None
set_stderr_stream(logstream: LogStream, *, data_store: DataStoreInterface) None
query_queue_time() timedelta
query_n_retries() int
get_operation_update(operation_name: str) Tuple[CancelledError | None, Operation]

Get an operation update message tuple.

The returned tuple is of the form

(error, operation)