Lease

Lease clients

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

Bases: bosdyn.client.exceptions.ResponseError

General class of errors for LeaseResponseError service.

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

Bases: bosdyn.client.lease.LeaseResponseError

The provided lease is invalid.

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

Bases: bosdyn.client.lease.LeaseResponseError

Lease is older than the current lease.

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

Bases: bosdyn.client.lease.LeaseResponseError

Resource is not known to the LeaseService.

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

Bases: bosdyn.client.lease.LeaseResponseError

LeaseService is not authoritative so Acquire should not work.

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

Bases: bosdyn.client.lease.LeaseResponseError

Use TakeLease method to forcefully grab the already claimed lease.

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

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)[source]

Bases: bosdyn.client.lease.LeaseResponseError

LeaseService does not manage this resource.

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

Bases: bosdyn.client.lease.LeaseResponseError

Lease is for the wrong epoch.

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

Bases: bosdyn.client.lease.LeaseResponseError

Lease is not the active lease.

exception bosdyn.client.lease.Error[source]

Bases: Exception

Base non-response error for lease module.

exception bosdyn.client.lease.NoSuchLease(resource)[source]

Bases: bosdyn.client.lease.Error

The requested lease does not exist.

exception bosdyn.client.lease.LeaseNotOwnedByWallet(resource, lease_state)[source]

Bases: bosdyn.client.lease.Error

The lease is not owned by the wallet.

class bosdyn.client.lease.Lease(lease_proto)[source]

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)[source]

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)[source]

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()[source]

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()[source]

Creates a sublease of this lease.

Returns

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

static is_valid_proto(lease_proto)[source]

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)[source]

Bases: object

class Status(value)[source]

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()[source]

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)[source]

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[source]

Bases: object

Thread-safe storage of Leases.

add(lease)[source]

Add lease in the wallet.

Parameters

lease – Lease to add in the wallet.

remove(lease)[source]

Remove lease from the wallet.

Parameters

lease – Lease to remove from the wallet.

advance(resource='body')[source]

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')[source]

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')[source]

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)[source]

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.

class bosdyn.client.lease.LeaseClient(lease_wallet=None)[source]

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)[source]

Acquire a lease for the given resource.

Parameters

resorce – Resource for the lease.

Returns

Acquired Lease object.

Raises
acquire_async(resource='body', **kwargs)[source]

Async version of acquire() function.

take(resource='body', **kwargs)[source]

Take the lease for the given resource.

Parameters

resorce – Resource for the lease.

Returns

Taken Lease object.

Raises
take_async(resource='body', **kwargs)[source]

Async version of the take() function.

return_lease(lease, **kwargs)[source]

Return an acquired lease.

Parameters

lease – Lease to return.

Raises
return_lease_async(lease, **kwargs)[source]

Async version of the return_lease() function.

retain_lease(lease, **kwargs)[source]

Retain the lease.

Parameters

lease – Lease to retain.

Raises
retain_lease_async(lease, **kwargs)[source]

Async version of the retain_lease() function.

list_leases(**kwargs)[source]

Get a list of the leases.

Returns

List of lease resources.

Raises
list_leases_async(**kwargs)[source]

Async version of the list_leases() function.

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

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)[source]

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

static get_lease_state(request)[source]

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

class bosdyn.client.lease.LeaseWalletResponseProcessor(lease_wallet)[source]

Bases: object

LeaseWalletResponseProcessor updates the wallet with a LeaseUseResult.

Parameters

lease_wallet – Lease wallet to use.

mutate(response)[source]

Update the wallet if a response has a lease_use_result.

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

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)[source]

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()[source]

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()[source]
property lease_wallet
wait_until_done()[source]

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.