Lease

Lease clients

exception bosdyn.client.lease.LeaseResponseError(response, error_message=None)

Bases: bosdyn.client.exceptions.ResponseError

General class of errors for LeaseResponseError service.

exception bosdyn.client.lease.InvalidLeaseError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

The provided lease is invalid.

exception bosdyn.client.lease.DisplacedLeaseError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Lease is older than the current lease.

exception bosdyn.client.lease.InvalidResourceError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Resource is not known to the LeaseService.

exception bosdyn.client.lease.NotAuthoritativeServiceError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

LeaseService is not authoritative so Acquire should not work.

exception bosdyn.client.lease.ResourceAlreadyClaimedError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Use TakeLease method to forcefully grab the already claimed lease.

exception bosdyn.client.lease.RevokedLeaseError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Lease is stale cause lease holder did not check in regularly enough.

exception bosdyn.client.lease.UnmanagedResourceError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

LeaseService does not manage this resource.

exception bosdyn.client.lease.WrongEpochError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Lease is for the wrong epoch.

exception bosdyn.client.lease.NotActiveLeaseError(response, error_message=None)

Bases: bosdyn.client.lease.LeaseResponseError

Lease is not the active lease.

exception bosdyn.client.lease.Error

Bases: Exception

Base non-response error for lease module.

exception bosdyn.client.lease.NoSuchLease(resource)

Bases: bosdyn.client.lease.Error

The requested lease does not exist.

exception bosdyn.client.lease.LeaseNotOwnedByWallet(resource, lease_state)

Bases: bosdyn.client.lease.Error

The lease is not owned by the wallet.

class bosdyn.client.lease.Lease(lease_proto)

Bases: object

Leases are used to coordinate access to shared resources on a Boston Dynamics robot.

A service will grant access to the shared resource if the lease which accompanies a request is “more recent” than any previously seen leases. Recency is determined using a sequence of monotonically increasing numbers, similar to a Lamport logical clock.

Parameters

lease_proto – bosdyn.api.Lease protobuf object.

class CompareResult(value)

Bases: enum.Enum

Enum for comparison results between two leases.

SAME = 1

SUPER_LEASE = 2

SUB_LEASE = 3

OLDER = 4

NEWER = 5

DIFFERENT_RESOURCES = 6

DIFFERENT_EPOCHS = 7

compare(other_lease)

Compare two different lease objects.

Parameters

other_lease – The lease to compare this lease with.

Returns

• CompareResult.SAME if this lease is exactly the same as other_lease.

• CompareResult.SUPER_LEASE if this lease is a “super-lease” of the other lease - in other words, the other lease is a sublease of this lease.

• CompareResult.SUB_LEASE if this lease is a “sub-lease” of the other lease.

• CompareResult.OLDER if this lease is older than other_lease. other_lease may be a sublease of this lease.

• CompareResult.NEWER if this is lease is newer than other_lease. This lease may be a sublease of other_lease.

• CompareResult.DIFFERENT_RESOURCES if this lease is for a different resource than other_lease. There is no way to compare recency/time of Leases for two different resources.

• CompareResult.DIFFERENT_EPOCHS if this lease is for a different epoch than other_lease. There is no way to compare recency/time of Leases for two different epochs.

• CompareResult.INVALID if either this or other_lease is invalid.

create_newer()

Creates a new Lease which is newer than this Lease.

Returns

A new Lease object where self.compare(returned_lease) would return OLDER.

create_sublease(client_name=None)

Creates a sublease of this lease.

Parameters

client_name (string) – Optional argument to pass a client name to be appended to the new lease’s set of clients which have used it.

Returns

A new Lease object where self.compare(returned_lease) would return SUB_LEASE.

static is_valid_proto(lease_proto)

Checks whether this lease is valid.

Returns

bool indicating that this lease has a valid resource and sequence.

class bosdyn.client.lease.LeaseState(lease_status, lease_owner=None, lease=None, lease_current=None, client_name=None)

Bases: object

class Status(value)

Bases: enum.Enum

An enumeration.

UNOWNED = 0

REVOKED = 1

SELF_OWNER = 2

OTHER_OWNER = 3

NOT_MANAGED = 4

STATUS_UNOWNED = 0

STATUS_REVOKED = 1

STATUS_SELF_OWNER = 2

STATUS_OTHER_OWNER = 3

STATUS_NOT_MANAGED = 4

create_newer()

Create newer version of the Lease.

Returns

Instance of itself if lease_current was not passed, or a new LeaseState.

update_from_lease_use_result(lease_use_result)

Update internal instance of LeaseState from given lease.

Parameters

lease_use_result – LeaseUseResult from the server.

Returns

Updated internal instance of LeaseState.

class bosdyn.client.lease.LeaseWallet

Bases: object

Thread-safe storage of Leases.

add(lease)

Add lease in the wallet.

Parameters

lease – Lease to add in the wallet.

remove(lease)

Remove lease from the wallet.

Parameters

lease – Lease to remove from the wallet.

advance(resource='body')

Advance the lease for a specific resource.

Parameters

resource – The resource that the Lease is for.

Returns

Advanced lease for the resource.

Raises

LeaseNotOwnedByWallet – The lease is not owned by the wallet.

get_lease(resource='body')

Get the lease for a specific resource.

Parameters

resource – The resource that the Lease is for.

Returns

Lease for the resource.

Raises

LeaseNotOwnedByWallet – The lease is not owned by the wallet.

get_lease_state(resource='body')

Get the lease state for a specific resource.

Parameters

resource – The resource that the Lease is for.

Returns

Lease state for the resource.

Raises

NoSuchLease – The requested lease does not exist.

on_lease_use_result(lease_use_result, resource=None)

Update the lease state based on result of using the lease.

Parameters

• lease_use_result – LeaseUseResult from the server.

• resource – Resource to update, e.g. ‘body’. Default to None to use the resource specified by the lease_use_result.

set_client_name(client_name)

Set the client name that will be issuing the leases.

class bosdyn.client.lease.LeaseClient(lease_wallet=None)

Bases: bosdyn.client.common.BaseClient

Client to the lease service.

Parameters

lease_wallet – Lease wallet to use.

default_service_name = 'lease'

service_type = 'bosdyn.api.LeaseService'

acquire(resource='body', **kwargs)

Acquire a lease for the given resource.

Parameters

resource – Resource for the lease.

Returns

Acquired Lease object.

Raises

• ResourceAlreadyClaimedError – Use TakeLease method to forcefully grab the already claimed lease.

• InvalidResourceError – Resource is not known to the LeaseService.

• NotAuthoritativeServiceError – LeaseService is not authoritative so Acquire should not work.

acquire_async(resource='body', **kwargs)

Async version of acquire() function.

take(resource='body', **kwargs)

Take the lease for the given resource.

Parameters

resource – Resource for the lease.

Returns

Taken Lease object.

Raises

• InvalidResourceError – Resource is not known to the LeaseService.

• NotAuthoritativeServiceError – LeaseService is not authoritative so Acquire should not work.

take_async(resource='body', **kwargs)

Async version of the take() function.

return_lease(lease, **kwargs)

Return an acquired lease.

Parameters

lease – Lease to return.

Raises

• InvalidResourceError – Resource is not known to the LeaseService.

• NotActiveLeaseError – Lease is not the active lease.

• NotAuthoritativeServiceError – LeaseService is not authoritative so Acquire should not work.

return_lease_async(lease, **kwargs)

Async version of the return_lease() function.

retain_lease(lease, **kwargs)

Retain the lease.

Parameters

lease – Lease to retain.

Raises

• InternalServerError – Service experienced an unexpected error state.

• LeaseUseError – Request was rejected due to using an invalid lease.

retain_lease_async(lease, **kwargs)

Async version of the retain_lease() function.

list_leases(include_full_lease_info=False, **kwargs)

Get a list of the leases.

Parameters

include_full_lease_info – Whether the returned list of LeaseResources should include all of the available information about the last lease used. Defaults to False.

Returns

List of lease resources.

Raises

• InternalServerError – Service experienced an unexpected error state.

• LeaseUseError – Request was rejected due to using an invalid lease.

list_leases_async(include_full_lease_info=False, **kwargs)

Async version of the list_leases() function.

class bosdyn.client.lease.LeaseWalletRequestProcessor(lease_wallet, resource_list=None)

Bases: object

LeaseWalletRequestProcessor adds a lease from a wallet to a request.

Parameters

• lease_wallet – The LeaseWallet to read leases from.

• resource_list – List of resources this processors should add to requests. Default None to use the default resource.

mutate(request)

Add the leases for the necessary resources if no leases have been specified yet.

static get_lease_state(request)

Returns a tuple of (“are there multiple leases in request?”, “are they set already?”)

class bosdyn.client.lease.LeaseWalletResponseProcessor(lease_wallet)

Bases: object

LeaseWalletResponseProcessor updates the wallet with a LeaseUseResult.

Parameters

lease_wallet – Lease wallet to use.

mutate(response)

Update the wallet if a response has a lease_use_result.

bosdyn.client.lease.add_lease_wallet_processors(client, lease_wallet, resource_list=None)

Adds LeaseWallet related processors to a gRPC client.

For services which use leases for access control, this does two things:

• Advance the lease from the LeaseWallet and attach to a request.

• Handle the LeaseUseResult from a response and update LeaseWallet.

Parameters

• client (*) – BaseClient derived class for a single service.

• lease_wallet (*) – The LeaseWallet to track from, must be non-None.

• resource_list (*) – List of resources these processors should add to requests. Default None to use a default resource.

class bosdyn.client.lease.LeaseKeepAlive(lease_client, lease_wallet=None, resource='body', rpc_interval_seconds=2, keep_running_cb=None)

Bases: object

LeaseKeepAlive issues lease liveness checks on a background thread.

The robot’s lease system expects lease holders to check in at a regular cadence. If the check-ins do not happen, the robot will treat it as a communications loss. Typically this will result in the robot stopping, powering off, and the lease holder getting their lease revoked.

Using a LeaseKeepAlive object hides most of the details of issuing the lease liveness check. Developers can also manage liveness checks directly by using the retain_lease methods on the LeaseClient object.

Parameters

• lease_client – The LeaseClient object to issue requests on.

• lease_wallet – The LeaseWallet to retrieve current leases from, and to handle any bad LeaseUseResults from. If not specified, the lease_client’s lease_wallet will be used.

• resource – The resource to do liveness checks for.

• rpc_interval_seconds – Duration in seconds between liveness checks.

• keep_running_cb – If specified, should be a callable object that returns True if the liveness checks should proceed, False otherwise. LeaseKeepAlive will invoke keep_running_cb on its background thread. One example of where this could be used is in an interactive UI - keep_running_cb could stall or return False if the UI thread is wedged, which prevents the application from continuing to keep the Lease alive when it is no longer in a good state.

shutdown()

Shut the background thread down and stop the liveness checks.

Can be called multiple times, but subsequent calls are no-ops. Blocks until the background thread completes.

is_alive()

property lease_wallet

wait_until_done()

Waits until the background thread exits.

Most client code should exit the background thread by using shutdown or by passing in a keep_running_cb callback in the constructor.

However, this can be useful in unit tests for ensuring exits.