grepros 1.3.0
grep for ROS bag files and live topics
Loading...
Searching...
No Matches
grepros.api Namespace Reference

Classes

class  Bag
 
class  BaseBag
 
class  TypeMeta
 

Functions

 calculate_definition_hash (typename, msgdef, extradefs=())
 
 canonical (typename, unbounded=False)
 
 create_publisher (topic, cls_or_typename, queue_size)
 
 create_subscriber (topic, cls_or_typename, handler, queue_size)
 
 deserialize_message (msg, cls_or_typename)
 
 dict_to_message (dct, msg)
 
 filter_fields (fieldmap, top=(), include=(), exclude=())
 
 format_message_value (msg, name, value)
 
 get_alias_type (typename)
 
 get_message_class (typename)
 
 get_message_definition (msg_or_type)
 
 get_message_fields (val)
 
 get_message_type (msg_or_cls)
 
 get_message_type_hash (msg_or_type)
 
 get_message_value (msg, name, typename=None, default=Ellipsis)
 
 get_ros_time_category (msg_or_type)
 
 get_rostime (fallback=False)
 
 get_topic_types ()
 
 get_type_alias (typename)
 
 init_node (name=None)
 
 is_ros_message (val, ignore_time=False)
 
 is_ros_time (val)
 
 iter_message_fields (msg, messages_only=False, flat=False, scalars=(), include=(), exclude=(), top=())
 
 make_bag_time (stamp, bag)
 
 make_duration (secs=0, nsecs=0)
 
 make_full_typename (typename, category="msg")
 
 make_live_time (stamp)
 
 make_message_hash (msg, include=(), exclude=())
 
 make_time (secs=0, nsecs=0)
 
 message_to_dict (msg, replace=None)
 
 parse_definition_fields (typename, typedef)
 
 parse_definition_subtypes (typedef, nesting=False)
 
 scalar (typename)
 
 serialize_message (msg)
 
 set_message_value (obj, name, value)
 
 shutdown_node ()
 
 time_message (val, to_message=True, clock_type=None)
 
 to_datetime (val)
 
 to_decimal (val)
 
 to_duration (val)
 
 to_nsec (val)
 
 to_sec (val)
 
 to_sec_nsec (val)
 
 to_time (val)
 
 validate (live=False)
 

Variables

tuple BAG_EXTENSIONS = ()
 Bagfile extensions to seek, including leading dot, populated after init.
 
str NODE_NAME = "grepros"
 Node base name for connecting to ROS (will be anonymized).
 
 realapi = None
 Module grepros.ros1 or grepros.ros2.
 
 ROS1 = None
 Flag denoting ROS1 environment, populated on validate()
 
 ROS2 = None
 Flag denoting ROS2 environment, populated on validate()
 
dict ROS_ALIAS_TYPES = {}
 Mapping between type aliases and real types, like {"byte": "int8"} in ROS1.
 
dict ROS_BUILTIN_CTORS
 Python constructors for ROS built-in types, as {ROS name: type class}.
 
list ROS_BUILTIN_TYPES = ROS_NUMERIC_TYPES + ROS_STRING_TYPES
 All built-in basic types in ROS.
 
list ROS_COMMON_TYPES = []
 All built-in basic types plus time types in ROS, populated after init.
 
 ROS_FAMILY = None
 ROS Python module family, "rospy" or "rclpy", populated on validate()
 
list ROS_NUMERIC_TYPES
 All built-in numeric types in ROS.
 
list ROS_STRING_TYPES = ["string", "wstring"]
 All built-in string types in ROS.
 
dict ROS_TIME_CLASSES = {}
 ROS1 time/duration types mapped to type names, populated after init.
 
list ROS_TIME_TYPES = []
 ROS time/duration types, populated after init.
 
 ROS_VERSION = None
 ROS version from environment, populated on validate() as integer.
 
tuple SKIP_EXTENSIONS = ()
 Bagfile extensions to skip, including leading dot, populated after init.
 

Detailed Description

ROS interface, shared facade for ROS1 and ROS2.

------------------------------------------------------------------------------
This file is part of grepros - grep for ROS1 bag files and live topics.
Released under the BSD License.

@author      Erki Suurjaak
@created     01.11.2021
@modified    13.02.2026
------------------------------------------------------------------------------

Function Documentation

◆ calculate_definition_hash()

calculate_definition_hash (   typename,
  msgdef,
  extradefs = () 
)
Returns MD5 hash for message type definition.

@param   extradefs  additional subtype definitions as ((typename, msgdef), )

Definition at line 623 of file api.py.

◆ canonical()

canonical (   typename,
  unbounded = False 
)
Returns "pkg/Type" for "pkg/subdir/Type", standardizes various ROS2 formats.

Converts ROS2 DDS types like "octet" to "byte", and "sequence<uint8, 100>" to "uint8[100]".

@param   unbounded  drop constraints like array bounds, and string bounds in ROS2,
                    e.g. returning "uint8[]" for "uint8[10]"

Definition at line 664 of file api.py.

◆ create_publisher()

create_publisher (   topic,
  cls_or_typename,
  queue_size 
)
Returns a ROS publisher instance, with .get_num_connections() and .unregister().

Definition at line 676 of file api.py.

◆ create_subscriber()

create_subscriber (   topic,
  cls_or_typename,
  handler,
  queue_size 
)
Returns a ROS subscriber instance.

Supplemented with .unregister(), .get_message_class(), .get_message_definition(),
.get_message_type_hash(), and .get_qoses().

Definition at line 681 of file api.py.

◆ deserialize_message()

deserialize_message (   msg,
  cls_or_typename 
)
Returns ROS message or service request/response instantiated from serialized binary.

Definition at line 1115 of file api.py.

◆ dict_to_message()

dict_to_message (   dct,
  msg 
)
Returns given ROS message populated from Python dictionary.

Raises TypeError on attribute value type mismatch.

Definition at line 999 of file api.py.

◆ filter_fields()

filter_fields (   fieldmap,
  top = (),
  include = (),
  exclude = () 
)
Returns fieldmap filtered by include and exclude patterns.

@param   fieldmap   {field name: field type name}
@param   top        parent path as (rootattr, ..)
@param   include    [((nested, path), re.Pattern())] to require in parent path
@param   exclude    [((nested, path), re.Pattern())] to reject in parent path

Definition at line 691 of file api.py.

◆ format_message_value()

format_message_value (   msg,
  name,
  value 
)
Returns a message attribute value as string.

Result is at least 10 chars wide if message is a ROS time/duration
(aligning seconds and nanoseconds).

Definition at line 717 of file api.py.

◆ get_alias_type()

get_alias_type (   typename)
Returns ROS built-in type for alias like "char", if any; reverse of get_alias_type().

In ROS1, byte and char are aliases for int8 and uint8; in ROS2 the reverse.

Definition at line 809 of file api.py.

◆ get_message_class()

get_message_class (   typename)
Returns ROS message class, or None if unavailable.

Definition at line 727 of file api.py.

◆ get_message_definition()

get_message_definition (   msg_or_type)
Returns ROS message type definition full text, including subtype definitions.

Returns None if unknown type.

Definition at line 732 of file api.py.

◆ get_message_fields()

get_message_fields (   val)
Returns OrderedDict({field name: field type name}) if ROS message, else {}.

@param   val  ROS message class or instance

Definition at line 746 of file api.py.

◆ get_message_type()

get_message_type (   msg_or_cls)
Returns ROS message type name, like "std_msgs/Header".

Definition at line 755 of file api.py.

◆ get_message_type_hash()

get_message_type_hash (   msg_or_type)
Returns ROS message type MD5 hash, or "" if unknown type.

Definition at line 741 of file api.py.

◆ get_message_value()

get_message_value (   msg,
  name,
  typename = None,
  default = Ellipsis 
)
Returns object attribute value, with numeric arrays converted to lists.

@param   name      message attribute name
@param   typename  value ROS type name, for identifying byte arrays
@param   default   value to return if attribute does not exist; raises exception otherwise

Definition at line 760 of file api.py.

◆ get_ros_time_category()

get_ros_time_category (   msg_or_type)
Returns "time" or "duration" for time/duration type or instance, else original argument.

Definition at line 780 of file api.py.

◆ get_rostime()

get_rostime (   fallback = False)
Returns current ROS time, as rospy.Time or rclpy.time.Time.

@param   fallback  use wall time if node not initialized

Definition at line 771 of file api.py.

◆ get_topic_types()

get_topic_types ( )
Returns currently available ROS topics, as [(topicname, typename)].

Omits topics that the current ROS node itself has published.

Definition at line 791 of file api.py.

◆ get_type_alias()

get_type_alias (   typename)
Returns alias like "char" for ROS built-in type, if any; reverse of get_type_alias().

In ROS1, byte and char are aliases for int8 and uint8; in ROS2 the reverse.

Definition at line 800 of file api.py.

◆ init_node()

init_node (   name = None)
Initializes a ROS1 or ROS2 node if not already initialized.

In ROS1, blocks until ROS master available.

Definition at line 571 of file api.py.

◆ is_ros_message()

is_ros_message (   val,
  ignore_time = False 
)
Returns whether value is a ROS message or special like ROS time/duration class or instance.

@param   ignore_time  whether to ignore ROS time/duration types

Definition at line 818 of file api.py.

◆ is_ros_time()

is_ros_time (   val)
Returns whether value is a ROS time/duration class or instance.

Definition at line 827 of file api.py.

◆ iter_message_fields()

iter_message_fields (   msg,
  messages_only = False,
  flat = False,
  scalars = (),
  include = (),
  exclude = (),
  top = () 
)
Yields ((nested, path), value, typename) from ROS message.

@param   messages_only  whether to yield only values that are ROS messages themselves
                        or lists of ROS messages, else will yield scalar and scalar list values
@param   flat           recurse into lists of nested messages, ignored if `messages_only`
@param   scalars        sequence of ROS types to consider as scalars, like ("time", duration")
@param   include        [((nested, path), re.Pattern())] to require in field path, if any
@param   exclude        [((nested, path), re.Pattern())] to reject in field path, if any
@param   top            internal recursion helper

Definition at line 832 of file api.py.

◆ make_bag_time()

make_bag_time (   stamp,
  bag 
)
Returns value as ROS timestamp, conditionally as relative to bag start/end time.

Stamp is interpreted as relative offset from bag start/end time
if numeric string with sign prefix, or timedelta, or ROS duration.

@param   stamp   converted to ROS timestamp if int/float/str/duration/datetime/timedelta/decimal
@param   bag     an open bag to use for relative start/end time

Definition at line 885 of file api.py.

◆ make_duration()

make_duration (   secs = 0,
  nsecs = 0 
)
Returns a ROS duration.

Definition at line 935 of file api.py.

◆ make_full_typename()

make_full_typename (   typename,
  category = "msg" 
)
Returns "pkg/msg/Type" for "pkg/Type".

@param   category  type category like "msg" or "srv"

Definition at line 873 of file api.py.

◆ make_live_time()

make_live_time (   stamp)
Returns value as ROS timestamp, conditionally as relative to system time.

Stamp is interpreted as relative offset from system time
if numeric string with sign prefix, or timedelta, or ROS duration.

@param   stamp   converted to ROS timestamp if int/float/str/duration/datetime/timedelta/decimal

Definition at line 912 of file api.py.

◆ make_message_hash()

make_message_hash (   msg,
  include = (),
  exclude = () 
)
Returns hashcode for ROS message, as a hex digest.

@param   include   message fields to include if not all, as [((nested, path), re.Pattern())]
@param   exclude   message fields to exclude, as [((nested, path), re.Pattern())]

Definition at line 945 of file api.py.

◆ make_time()

make_time (   secs = 0,
  nsecs = 0 
)
Returns a ROS time.

Definition at line 940 of file api.py.

◆ message_to_dict()

message_to_dict (   msg,
  replace = None 
)
Returns ROS message as nested Python dictionary.

@param   replace  mapping of {value: replaced value},
                  e.g. {math.nan: None, math.inf: None}

Definition at line 974 of file api.py.

◆ parse_definition_fields()

parse_definition_fields (   typename,
  typedef 
)
Returns field names and type names from a message definition text.

Does not recurse into subtypes.

@param   typename  ROS message type name, like "my_pkg/MyCls"
@param   typedef   ROS message definition, like "Header header\nbool a\nMyCls2 b"
@return            ordered {field name: type name},
                   like {"header": "std_msgs/Header", "a": "bool", "b": "my_pkg/MyCls2"}

Definition at line 1028 of file api.py.

◆ parse_definition_subtypes()

parse_definition_subtypes (   typedef,
  nesting = False 
)
Returns subtype names and type definitions from a full message definition.

@param   typedef    message type definition including all subtype definitions
@param   nesting    whether to additionally return type nesting information as
                    {typename: [typename contained in parent]}
@return             {"pkg/MsgType": "full definition for MsgType including subtypes"}
                    or ({typedefs}, {nesting}) if nesting

Definition at line 1061 of file api.py.

◆ scalar()

scalar (   typename)
Returns scalar type from ROS message data type, like "uint8" from uint8-array.

Returns type unchanged if an ordinary type. In ROS2, returns unbounded type,
e.g. "string" from "string<=10[<=5]".

Definition at line 1120 of file api.py.

◆ serialize_message()

serialize_message (   msg)
Returns ROS message as a serialized binary.

Definition at line 1110 of file api.py.

◆ set_message_value()

set_message_value (   obj,
  name,
  value 
)
Sets message or object attribute value.

Definition at line 1130 of file api.py.

◆ shutdown_node()

shutdown_node ( )
Shuts down live ROS node.

Definition at line 580 of file api.py.

◆ time_message()

time_message (   val,
  to_message = True,
  clock_type = None 
)
Converts ROS2 time/duration between `rclpy` and `builtin_interfaces` objects.

Returns input value as-is in ROS1.

@param   val         ROS2 time/duration object from `rclpy` or `builtin_interfaces`
@param   to_message  whether to convert from `rclpy` to `builtin_interfaces` or vice versa
@param   clock_type  ClockType for converting to `rclpy.Time`, defaults to `ROS_TIME`
@return              value converted to appropriate type, or original value if not convertible

Definition at line 1135 of file api.py.

◆ to_datetime()

to_datetime (   val)
Returns value as datetime.datetime if value is ROS time/duration, else value.

Definition at line 1150 of file api.py.

◆ to_decimal()

to_decimal (   val)
Returns value as decimal.Decimal if value is ROS time/duration, else value.

Definition at line 1156 of file api.py.

◆ to_duration()

to_duration (   val)
Returns value as ROS duration if convertible (int/float/time/datetime/decimal), else value.

Definition at line 1167 of file api.py.

◆ to_nsec()

to_nsec (   val)
Returns value in nanoseconds if value is ROS time/duration, else value.

Definition at line 1172 of file api.py.

◆ to_sec()

to_sec (   val)
Returns value in seconds if value is ROS time/duration, else value.

Definition at line 1177 of file api.py.

◆ to_sec_nsec()

to_sec_nsec (   val)
Returns value as (seconds, nanoseconds) if value is ROS time/duration, else value.

Definition at line 1182 of file api.py.

◆ to_time()

to_time (   val)
Returns value as ROS time if convertible (int/float/duration/datetime/decimal), else value.

Definition at line 1187 of file api.py.

◆ validate()

validate (   live = False)
Initializes ROS bindings, returns whether ROS environment set, prints or raises error if not.

@param   live  whether environment must support launching a ROS node

Definition at line 585 of file api.py.

Variable Documentation

◆ BAG_EXTENSIONS

tuple BAG_EXTENSIONS = ()

Bagfile extensions to seek, including leading dot, populated after init.

Definition at line 36 of file api.py.

◆ NODE_NAME

str NODE_NAME = "grepros"

Node base name for connecting to ROS (will be anonymized).

Definition at line 33 of file api.py.

◆ realapi

realapi = None

Module grepros.ros1 or grepros.ros2.

Definition at line 82 of file api.py.

◆ ROS1

ROS1 = None

Flag denoting ROS1 environment, populated on validate()

Definition at line 42 of file api.py.

◆ ROS2

ROS2 = None

Flag denoting ROS2 environment, populated on validate()

Definition at line 45 of file api.py.

◆ ROS_ALIAS_TYPES

dict ROS_ALIAS_TYPES = {}

Mapping between type aliases and real types, like {"byte": "int8"} in ROS1.

Definition at line 79 of file api.py.

◆ ROS_BUILTIN_CTORS

dict ROS_BUILTIN_CTORS
Initial value:
1= {"byte": int, "char": int, "int8": int, "int16": int,
2 "int32": int, "int64": int, "uint8": int, "uint16": int,
3 "uint32": int, "uint64": int, "float32": float, "float64": float,
4 "bool": bool, "string": str, "wstring": str}

Python constructors for ROS built-in types, as {ROS name: type class}.

Definition at line 64 of file api.py.

◆ ROS_BUILTIN_TYPES

list ROS_BUILTIN_TYPES = ROS_NUMERIC_TYPES + ROS_STRING_TYPES

All built-in basic types in ROS.

Definition at line 61 of file api.py.

◆ ROS_COMMON_TYPES

list ROS_COMMON_TYPES = []

All built-in basic types plus time types in ROS, populated after init.

Definition at line 76 of file api.py.

◆ ROS_FAMILY

ROS_FAMILY = None

ROS Python module family, "rospy" or "rclpy", populated on validate()

Definition at line 51 of file api.py.

◆ ROS_NUMERIC_TYPES

list ROS_NUMERIC_TYPES
Initial value:
1= ["byte", "char", "int8", "int16", "int32", "int64", "uint8",
2 "uint16", "uint32", "uint64", "float32", "float64", "bool"]

All built-in numeric types in ROS.

Definition at line 54 of file api.py.

◆ ROS_STRING_TYPES

list ROS_STRING_TYPES = ["string", "wstring"]

All built-in string types in ROS.

Definition at line 58 of file api.py.

◆ ROS_TIME_CLASSES

dict ROS_TIME_CLASSES = {}

ROS1 time/duration types mapped to type names, populated after init.

Definition at line 73 of file api.py.

◆ ROS_TIME_TYPES

list ROS_TIME_TYPES = []

ROS time/duration types, populated after init.

Definition at line 70 of file api.py.

◆ ROS_VERSION

ROS_VERSION = None

ROS version from environment, populated on validate() as integer.

Definition at line 48 of file api.py.

◆ SKIP_EXTENSIONS

tuple SKIP_EXTENSIONS = ()

Bagfile extensions to skip, including leading dot, populated after init.

Definition at line 39 of file api.py.