Lease

Lease clients

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

Bases: ResponseError

General class of errors for LeaseResponseError service.

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

Bases: LeaseResponseError

The provided lease is invalid.

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

Bases: LeaseResponseError

Lease is older than the current lease.

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

Bases: LeaseResponseError

Resource is not known to the LeaseService.

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

Bases: LeaseResponseError

LeaseService is not authoritative so Acquire should not work.

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

Bases: LeaseResponseError

Use TakeLease method to forcefully grab the already claimed lease.

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

Bases: LeaseResponseError

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

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

Bases: LeaseResponseError

LeaseService does not manage this resource.

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

Bases: LeaseResponseError

Lease is for the wrong epoch.

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

Bases: 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: Error

The requested lease does not exist.

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

Bases: Error

The lease is not owned by the wallet.

class bosdyn.client.lease.Lease(lease_proto, ignore_is_valid_check=False)

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 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, ignore_resources=False)

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.

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.

is_valid_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.

static compare_result_to_lease_use_result_status(compare_result, allow_super_leases)

Determines the comparable LeaseUseResult.Status enum value based on the CompareResult enum.

Parameters

allow_super_leases (boolean) – If true, a super lease will still be considered as “ok”/ newer when compared to the active lease.

Raises

bosdyn.client.lease.Error – Raised if there is an unknown compare result enum value.

Returns

The corresponding LeaseUseResult.Status enum value.

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

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: 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 object) – Lease to return. This should be a Lease class object, and not the proto.

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.

list_leases_full(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

The complete ListLeasesResponse message.

Raises

• InternalServerError – Service experienced an unexpected error state.

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

list_leases_full_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 processor should add to requests. Default None to use the default resource.

mutate(request, resource_list=<object object>)

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, host_name='', on_failure_callback=None, warnings=True, must_acquire=False, return_at_exit=False)

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.

• on_failure_callback – If specified, this should be a callable function object which takes the error/exception as an input. The function does not need to return anything. This function can be used to action on any failures during the keepalive from the RetainLease RPC.

• warnings (bool) – Used to determine if the _periodic_check_in function will print lease check-in errors.

• must_acquire (bool) – If True, exceptions when trying to acquire the lease will not be caught.

• return_at_exit (bool) – If True, return the lease when shutting down.

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.

bosdyn.client.lease.test_active_lease(incoming_lease_proto, active_lease, sublease_name=None, allow_super_leases=False)

Check if an incoming lease is newer than the current lease.

Parameters

• incoming_lease_proto (lease_pb2.Lease) – The incoming lease proto.

• active_lease (Lease) – A lease object representing the most recent/newest known lease that the incoming lease should be compared against.

• sublease_name (string) – If not NoneType, a sublease of the incoming lease will be created (with sublease_name as the client name) and used to compare to the active lease.

• allow_super_leases (boolean) – If true, a super lease will still be considered as “ok”/ newer when compared to the active lease.

Returns

A tuple containing the lease use result from comparing the incoming and active leases, and then a Lease object made from the incoming lease proto. The lease object will be None if the incoming lease proto was invalid. The lease object will be a sublease of the incoming lease proto if sublease_name is not NoneType.