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
(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.
-
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.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
-
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:
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
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 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.
-
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.
-
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.
-
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)[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.
-
property
lease_wallet
¶