Lease

Lease clients

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

Bases: ResponseError

General class of errors for LeaseResponseError service.

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

Bases: LeaseResponseError

The provided lease is invalid.

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

Bases: LeaseResponseError

Lease is older than the current lease.

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

Bases: LeaseResponseError

Resource is not known to the LeaseService.

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

Bases: LeaseResponseError

LeaseService is not authoritative so Acquire should not work.

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

Bases: LeaseResponseError

Use TakeLease method to forcefully grab the already claimed lease.

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

Bases: LeaseResponseError

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

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

Bases: LeaseResponseError

LeaseService does not manage this resource.

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

Bases: LeaseResponseError

Lease is for the wrong epoch.

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

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

The requested lease does not exist.

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

Bases: Error

The lease is not owned by the wallet.

class bosdyn.client.lease.Lease(lease_proto, ignore_is_valid_check=False)[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.

Raises:

ValueError if lease_proto is not present or valid.

class CompareResult(value)[source]

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)[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.

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

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

static compare_result_to_lease_use_result_status(compare_result, allow_super_leases)[source]

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

Bases: object

State of lease ownership in the wallet.

Parameters:
  • lease_status (LeaseState.Status) – The ownership status of the lease.

  • lease_owner (lease_pb2.LeaseOwner) – The name of the owner of the lease.

  • lease (Lease) – The original lease used to initialize the LeaseState, before applying any subleasing/incrementing.

  • lease_current (Lease) – The newest version of the lease (subleased, and incremented from the original lease).

  • client_name (string) – The name of the client using this lease.

class Status(value)[source]

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()[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.

set_client_name(client_name)[source]

Set the client name that will be issuing the leases.

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

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

Acquire a lease for the given resource.

Parameters:

resource – 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:

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

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(include_full_lease_info=False, **kwargs)[source]

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:
list_leases_async(include_full_lease_info=False, **kwargs)[source]

Async version of the list_leases() function.

list_leases_full(include_full_lease_info=False, **kwargs)[source]

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:
list_leases_full_async(include_full_lease_info=False, **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 processor should add to requests. Default None to use the default resource.

mutate(request, resource_list=<object object>)[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, host_name='', on_failure_callback=None, warnings=True, must_acquire=False, return_at_exit=False)[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.

  • 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()[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.

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

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.