Util

Helper functions and classes for creating client applications.

bosdyn.client.util.cli_login_prompt(username=None, password=None)

Interactive CLI for scripting conveniences.

bosdyn.client.util.cli_auth(robot, username=None, password=None)

Interactive CLI for authenticating with the robot.

bosdyn.client.util.authenticate(robot, askpass=None)

Generic function for authenticating with the robot.

Tries to authenticate using the following methods, in order:

• An existing auth token

• Username/Password supplied in the environment

• With a specified callback function, returning a username and password.

• A command line prompt, if possible (stdin is a tty).

Parameters:

askpass – A function that retrieves authentication credentials if none are specified via environment variables.

class bosdyn.client.util.DedupLoggingMessages(always_print_logger_levels={40, 50})

Bases: Filter

Logger filter to prevent duplicated messages from being logged.

Parameters:

always_print_logger_levels (set[logging.Level]) – A set of logging levels which any logged message at that level will always be logged.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

bosdyn.client.util.setup_logging(verbose=False, include_dedup_filter=False, always_print_logger_levels={40, 50})

Set up a basic streaming console handler at the root logger.

Parameters:

• verbose (boolean) – if False (default) show messages at INFO level and above, if True show messages at DEBUG level and above.

• include_dedup_filter (boolean) – If true, the logger includes a filter which will prevent repeated duplicated messages from being logged.

• always_print_logger_levels (set[logging.Level]) – A set of logging levels which any logged message at that level will always be logged.

bosdyn.client.util.does_dedup_filter_exist(logger, always_print_logger_levels)

Check if the DedupLoggingMessages filter exists for a logger.

Returns:

Boolean indicating if the DedupLoggingMessages filter already exists and matches the new parameters.

bosdyn.client.util.get_logger()

bosdyn.client.util.add_base_arguments(parser)

Add hostname argument to parser.

Parameters:

parser – Argument parser object.

bosdyn.client.util.add_credentials_arguments(parser, credentials_no_warn=False)

Add username/password flags to parser.

This function is marked deprecated and will be removed in a future release.

Parameters:

parser – Argument parser object.

bosdyn.client.util.add_common_arguments(parser, credentials_no_warn=False)

Add arguments common to most applications used for authentication.

This function is marked deprecated and will be removed in a future release. Users should use add_base_arguments instead.

Parameters:

parser – Argument parser object.

bosdyn.client.util.read_payload_credentials(filename)

Read the guid and secret from a file that already exists. The file should have the guid and secret as the first and second lines in the file.

Parameters:

filename – Name of the file to read.

Returns:

Tuple of (guid, secret)

Raises:

• OSError if the credential file cannot be read. –

• ValueError if the guid or secret are missing from the file. –

bosdyn.client.util.read_or_create_payload_credentials(filename)

Only for use when attempting to register a payload. If simply trying to authenticate, use get_guid_or_secret or read_payload_credentials instead.

When registering, attempt to read the payload’s guid and secret from the specified file. If this file exists, it should have the guid and secret as the first and second lines in the file. If the file does not exist, this function creates a valid credentials file at filename.

Parameters:

filename – Name of the file to read. Its parent directories should already exist and it should have the right permissions to be read by the payload registration service. If running on a CORE I/O, also ensure that this location is mounted as a volume to the CORE I/O’s /data or /persist locations.

Returns:

Tuple of (guid, secret)

Raises:

• OSError if the credential file cannot be read. –

• ValueError if the guid or secret are missing from the file. –

bosdyn.client.util.get_guid_and_secret(parsed_options)

Get the guid and secret for a payload, based on the options that were added via add_payload_credentials_arguments().

Parameters:

parsed_options – Namespace result of parser.parse_args()

Returns:

Tuple of (guid, secret)

Raises:

• OSError if the credential file cannot be read. –

• Exception if no applicable arguments are given. –

bosdyn.client.util.add_payload_credentials_file_argument(parser)

Add argument for payload_credentials_file to an ArgumentParser or argument group.

This file is where the payload’s GUID and secret are stored. The GUID and secret can be securely generated on a per-robot basis and written to this file with read_or_create_payload_credentials(filename).

Parameters:

parser – Argument parser object

bosdyn.client.util.add_payload_credentials_arguments(parser, required=True)

Add arguments common to most payload related applications. Use get_guid_and_secret() to get the guid and secret from the resulting parse.

Parameters:

• parser – Argument parser object.

• required – Require either the guid/secret or file arguments to be provided.

bosdyn.client.util.add_service_hosting_arguments(parser)

Add arguments common to most applications hosting a GRPC service.

Parameters:

parser – Argument parser object.

bosdyn.client.util.add_service_endpoint_arguments(parser)

Add arguments common to most applications defining a GRPC service endpoint.

Parameters:

parser – Argument parser object.

bosdyn.client.util.safe_pb_enum_to_string(value, pb_enum_obj)

Safe wrapper to convert a protobuf enum object to its string representation. Avoids throughing an exception if the status is unknown by the enum object.

Parameters:

• value – The enum value to convert

• pb_enum_obj – The protobuf enum object to decode the value

class bosdyn.client.util.GrpcServiceRunner(*args, **kwargs)

Bases: object

A runner to start a gRPC server on a background thread and allow easy cleanup.

Parameters:

• service_servicer (custom servicer class derived from ServiceServicer) – Servicer that defines server behavior.

• add_servicer_to_server_fn (function) – Function generated by gRPC compilation that attaches the servicer to the gRPC server.

• port (int) – The port number the service can be accessed through on the host system. Defaults to 0, which will assign an ephemeral port.

• max_send_message_length (int) – Max message length (bytes) allowed for messages sent.

• max_receive_message_length (int) – Max message length (bytes) allowed for messages received.

• timeout_secs (int) – Number of seconds to wait for a clean server shutdown.

• force_sigint_capture (bool) – Re-assign the SIGINT handler to default in order to prevent other scripts from blocking a clean exit. Defaults to True.

• logger (logging.Logger) – Logger to log with.

Deprecated since version 3.0.0: The GrpcServiceRunner class helper has moved to server_util.py. Please use bosdyn.client.server_util.GrpcServiceRunner.

stop()

run_until_interrupt()

Spin the thread until a SIGINT is received and then shut down cleanly.