ros_sugar.robot.command#

Robot command descriptor.

A RobotCommand declares one command surface a plugin exposes: which standard message type it stands in for, which transport carries it, and how to encode a component’s output into a wire payload.

Module Contents#

Classes#

RobotCommand

A robot command surface.

CommandSpec

Introspection record for a RobotCommand (see plugin.list_commands).

API#

class ros_sugar.robot.command.RobotCommand#

Bases: ros_sugar.config.BaseAttrs

A robot command surface.

Parameters:

  • key – Registry key on plugin.commands. A recipe routes an output topic through this command with Topic(..., use_plugin=True); resolution matches the topic’s name against this key first, then falls back to a unique message-type match. For plugins that expose exactly one command per message type, conventionally the message-type name ("Twist"). For plugins with multiple commands of the same type (e.g. a humanoid’s "left_arm" / "right_arm" JointStates), choose a descriptive role name and name the recipe’s topic to match it.

  • transport – Transport the command is sent on.

  • encoder – encoder(output) -> payload — turns a component’s output (the value it would have published) into the transport’s wire payload (bytes for UDP/HTTP, an SDK object for SDK, a request for RosServiceTransport).

  • msg_type – Optional SupportedType subclass — set only when the transport is ROS-typed (RosTopicTransport).

  • description – Human-readable description.

property channel: str#

Command bus channel, used when transport.route_via_host is set.

spec() → ros_sugar.robot.command.CommandSpec#

Return the introspection spec for this command.

asdict(filter: Optional[Callable] = None) → Dict#

Convert class to dict.

Return type:

dict

to_dict() → Dict#

Convert class to dict.

Return type:

dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:

Fields that differ from the defaults

Return type:

dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

  • ValueError – If attribute_name in dictionary does not exists in class attributes

  • TypeError – If attribute_value type in dictionary does not correspond to class attribute type

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

Update class attributes from yaml, json, or toml

Parameters:

  • file_path – Path to config file (.yaml, .json, .toml)

  • nested_root_name – Nested root name for the config, defaults to None

  • get_common – Whether to get extra config root (for merging), defaults to False

to_json() → Union[str, bytes, bytearray]#

Dump to json

Returns:

description

Return type:

str | bytes | bytearray

from_json(json_obj: Union[str, bytes, bytearray]) → None#

Gets attributes values from given json

Parameters:

json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:

attr_name (str) – description

Returns:

If object has attribute with given name

Return type:

bool

get_attribute_type(attr_name: str) → Optional[type]#

Gets type of given attribute name

Parameters:

attr_name (str) – description

Raises:

AttributeError – If class does not have attribute with given name

Returns:

Attribute type

Return type:

type

update_value(attr_name: str, attr_value: Any) → bool#

Updates the value of an attribute in the class

Parameters:

  • attr_name (str) – Attribute name - can be nested name

  • attr_value (Any) – Attribute value

Raises:

  • AttributeError – If class does not contain attribute with given name

  • TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:

A dictionary where keys are field names and values are dicts of metadata.

class ros_sugar.robot.command.CommandSpec#

Bases: ros_sugar.config.BaseAttrs

Introspection record for a RobotCommand (see plugin.list_commands).

key is the registry key on plugin.commands. To route an output through this command, set Topic(use_plugin=True) and name the topic after this key (needed only to disambiguate multiple commands of the same message type).

asdict(filter: Optional[Callable] = None) → Dict#

Convert class to dict.

Return type:

dict

to_dict() → Dict#

Convert class to dict.

Return type:

dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:

Fields that differ from the defaults

Return type:

dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

  • ValueError – If attribute_name in dictionary does not exists in class attributes

  • TypeError – If attribute_value type in dictionary does not correspond to class attribute type

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

Update class attributes from yaml, json, or toml

Parameters:

  • file_path – Path to config file (.yaml, .json, .toml)

  • nested_root_name – Nested root name for the config, defaults to None

  • get_common – Whether to get extra config root (for merging), defaults to False

to_json() → Union[str, bytes, bytearray]#

Dump to json

Returns:

description

Return type:

str | bytes | bytearray

from_json(json_obj: Union[str, bytes, bytearray]) → None#

Gets attributes values from given json

Parameters:

json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:

attr_name (str) – description

Returns:

If object has attribute with given name

Return type:

bool

get_attribute_type(attr_name: str) → Optional[type]#

Gets type of given attribute name

Parameters:

attr_name (str) – description

Raises:

AttributeError – If class does not have attribute with given name

Returns:

Attribute type

Return type:

type

update_value(attr_name: str, attr_value: Any) → bool#

Updates the value of an attribute in the class

Parameters:

  • attr_name (str) – Attribute name - can be nested name

  • attr_value (Any) – Attribute value

Raises:

  • AttributeError – If class does not contain attribute with given name

  • TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:

A dictionary where keys are field names and values are dicts of metadata.