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.
- 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.
- 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
- 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¶
- class bosdyn.client.lease.LeaseWallet[source]¶
Bases:
object
Thread-safe storage of Leases.
- 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.
- 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
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.
- take(resource='body', **kwargs)[source]¶
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.
- 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
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.
- retain_lease(lease, **kwargs)[source]¶
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.
- 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
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)[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
InternalServerError – Service experienced an unexpected error state.
LeaseUseError – Request was rejected due to using an invalid lease.
- 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.
- class bosdyn.client.lease.LeaseWalletResponseProcessor(lease_wallet)[source]¶
Bases:
object
LeaseWalletResponseProcessor updates the wallet with a LeaseUseResult.
- Parameters
lease_wallet – Lease wallet to use.
- 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.
- property lease_wallet¶
- 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.