grepros library interface. More...

Functions
	grep (args=None, **kwargs)
	Yields matching messages from specified source.

	init (args=None, **kwargs)
	Initializes ROS version bindings, loads all built-in plugins if dependencies available.

	sink (args=None, **kwargs)
	Convenience for creating a `Sink` instance from arguments, `MultiSink` if several outputs.

	source (args=None, **kwargs)
	Convenience for creating a `Source` instance from arguments.

Detailed Description

grepros library interface.

Source classes:

AppSource: produces messages from iterable or pushed data
BagSource: produces messages from ROS bagfiles
LiveSource: produces messages from live ROS topics

Sink classes:

AppSink: provides messages to callback function
BagSink: writes messages to bagfile
ConsoleSink: prints messages to console
CsvSink: writes messages to CSV files, each topic to a separate file
HtmlSink: writes messages to an HTML file
LiveSink: publishes messages to ROS topics
McapSink: writes messages to MCAP file
MultiSink: combines any number of sinks
ParquetSink: writes messages to Apache Parquet files
PostgresSink: writes messages to a Postgres database
SqliteSink: writes messages to an SQLite database
SqlSink: writes SQL schema file for message type tables and topic views

Bag: generic bag interface. Scanner: ROS message grepper.

Format-specific bag classes:

ROS1Bag: ROS1 bag reader and writer in .bag format
ROS2Bag: ROS2 bag reader and writer in .db3 SQLite format
EmbagReader: ROS1 bag reader using the embag library
McapBag: ROS1/ROS2 bag reader and writer in MCAP format

Output sink write_options arguments can be given with underscores instead of dashes, e.g. "rollover_size" instead of "rollover-size".

Function Documentation

◆ grep()

grep	(		args = `None`,
		**	kwargs
	)

Yields matching messages from specified source.

Initializes grepros if not already initialized.

Read from bagfiles: grep(file="2022-10-*.bag", pattern="cpu").

Read from live topics: grep(live=True, pattern="cpu").

Parameters

args	arguments as namespace or dictionary, case-insensitive; or a single path as the ROS bagfile to read, or one or more `Bag` instances, or a `Source` instance
kwargs	any and all arguments as keyword overrides, case-insensitive

Bag source:

Parameters

args.file	names of ROS bagfiles to read if not all in directory
args.path	paths to scan if not current directory
args.recurse	recurse into subdirectories when looking for bagfiles
args.decompress	decompress archived bags to file directory
args.reindex	make a copy of unindexed bags and reindex them (ROS1 only)
args.orderby	"topic" or "type" if any to group results by
args.timescale	emit messages on original timeline from first message at given rate, 0 disables
args.timescale_emission	start timeline from first matched message not first in bag
args.bag	one or more `Bag` instances

Live source:

Parameters

args.live	whether reading messages from live ROS topics
args.queue_size_in	subscriber queue size (default 10)
args.ros_time_in	stamp messages with ROS time instead of wall time

App source:

Parameters

args.app	whether reading messages from iterable or pushed data; may contain the iterable itself
args.iterable	iterable yielding (topic, msg, stamp) or (topic, msg); yielding `None` signals end of content Any source:
args.topic	ROS topics to read if not all
args.type	ROS message types to read if not all
args.skip_topic	ROS topics to skip
args.skip_type	ROS message types to skip
args.start_time	earliest timestamp of messages to read
args.end_time	latest timestamp of messages to read
args.start_index	message index within topic to start from
args.end_index	message index within topic to stop at
args.nth_message	read every Nth message in topic, starting from first
args.nth_interval	minimum time interval between messages in topic, as seconds or ROS duration
args.select_field	message fields to use in matching if not all
args.noselect_field	message fields to skip in matching
args.unique	emit messages that are unique in topic (select_field and noselect_field apply if specified)
args.condition	Python expressions that must evaluate as true for message to be processable, see ConditionMixin

Search‍:

Parameters

args.pattern	pattern(s) to find in message field values
args.fixed_string	pattern contains ordinary strings, not regular expressions
args.case	use case-sensitive matching in pattern
args.invert	select messages not matching pattern
args.expression	pattern(s) are a logical expression like 'this AND (this2 OR NOT "skip this")', with elements as patterns to find in message fields
args.nth_match	emit every Nth match in topic, starting from first
args.max_count	number of matched messages to emit (per file if bag input)
args.max_per_topic	number of matched messages to emit from each topic
args.max_topics	number of topics to print matches from
args.before	number of messages of leading context to emit before match
args.after	number of messages of trailing context to emit after match
args.context	number of messages of leading and trailing context to emit around match
args.highlight	highlight matched values
args.match_wrapper	string to wrap around matched values, both sides if one value, start and end if more than one, or no wrapping if zero values

Returns: GrepMessage namedtuples
of (topic, message, timestamp, match, index)

Definition at line 159 of file library.py.

◆ init()

init	(		args = `None`,
		**	kwargs
	)

Initializes ROS version bindings, loads all built-in plugins if dependencies available.

Parameters

args
args.plugin	one or more extra plugins to load, as full names or instances of Python module/class
kwargs	any and all arguments as keyword overrides, case-insensitive

Definition at line 353 of file library.py.

◆ sink()

sink	(		args = `None`,
		**	kwargs
	)

Convenience for creating a Sink instance from arguments, MultiSink if several outputs.

Initializes grepros if not already initialized.

Parameters

args	arguments as namespace or dictionary, case-insensitive; or a single item as sink target like bag filename
kwargs	any and all arguments as keyword overrides, case-insensitive
args.app	provide messages to given callback function
args.console	print matches to console
args.publish	publish matches to live topics
args.write	file or other target like Postgres database to write, as "target", or ["target", dict(format="format", ..)] or [[..target1..], [..target2..], ..]
args.write_options	format-specific options like {"overwrite": whether to overwrite existing file (default false)}

Console sink:

Parameters

args.line_prefix	print source prefix like bag filename on each message line
args.max_field_lines	maximum number of lines to print per field
args.start_line	message line number to start output from
args.end_line	message line number to stop output at
args.max_message_lines	maximum number of lines to output per message
args.lines_around_match	number of message lines around matched fields to output
args.matched_fields_only	output only the fields where match was found
args.wrap_width	character width to wrap message YAML output at
args.match_wrapper	string to wrap around matched values, both sides if one value, start and end if more than one, or no wrapping if zero values

Console / HTML sink:

Parameters

args.color	False or "never" for not using colors in replacements
args.highlight	highlight matched values (default true)
args.emit_field	message fields to emit if not all
args.noemit_field	message fields to skip in output
args.max_field_lines	maximum number of lines to output per field
args.start_line	message line number to start output from
args.end_line	message line number to stop output at
args.max_message_lines	maximum number of lines to output per message
args.lines_around_match	number of message lines around matched fields to output
args.matched_fields_only	output only the fields where match was found
args.wrap_width	character width to wrap message YAML output at
args.match_wrapper	string to wrap around matched values, both sides if one value, start and end if more than one, or no wrapping if zero values

Topic sink:

Parameters

args.queue_size_out	publisher queue size (default 10)
args.publish_prefix	output topic prefix, prepended to input topic
args.publish_suffix	output topic suffix, appended to output topic
args.publish_fixname	single output topic name to publish to, overrides prefix and suffix if given

App sink:

Parameters

args.emit	callback(topic, msg, stamp, highlighted msg, index in topic) if any
args.metaemit	callback(metadata dict) if any, invoked before first emit from source batch

Any sink:

Parameters

args.meta	whether to print metainfo
args.verbose	whether to print debug information

Definition at line 324 of file library.py.

◆ source()

source	(		args = `None`,
		**	kwargs
	)

Convenience for creating a Source instance from arguments.

Initializes grepros if not already initialized.

Parameters

args	arguments as namespace or dictionary, case-insensitive; or a single path as the ROS bagfile to read
kwargs	any and all arguments as keyword overrides, case-insensitive
args.file	one or more names of ROS bagfiles to read from
args.live	read messages from live ROS topics instead
args.app	read messages from iterable or pushed data instead; may contain the iterable itself

Bag source:

Parameters

args.file	names of ROS bagfiles to read if not all in directory
args.path	paths to scan if not current directory
args.recurse	recurse into subdirectories when looking for bagfiles
args.orderby	"topic" or "type" if any to group results by
args.decompress	decompress archived bags to file directory
args.reindex	make a copy of unindexed bags and reindex them (ROS1 only)
args.timescale	emit messages on original timeline from first message at given rate, 0 disables
args.timescale_emission	start timeline from first matched message not first in bag
args.progress	whether to print progress bar

Live source:

Parameters

args.queue_size_in	subscriber queue size (default 10)
args.ros_time_in	stamp messages with ROS time instead of wall time
args.progress	whether to print progress bar

App source:

Parameters

args.iterable iterable yielding (topic, msg, stamp) or (topic, msg); yielding None signals end of content

Any source:

Parameters

args.topic	ROS topics to read if not all
args.type	ROS message types to read if not all
args.skip_topic	ROS topics to skip
args.skip_type	ROS message types to skip
args.start_time	earliest timestamp of messages to read
args.end_time	latest timestamp of messages to read
args.start_index	message index within topic to start from
args.end_index	message index within topic to stop at
args.unique	emit messages that are unique in topic
args.select_field	message fields to use for uniqueness if not all
args.noselect_field	message fields to skip for uniqueness
args.nth_message	read every Nth message in topic, starting from first
args.nth_interval	minimum time interval between messages in topic, as seconds or ROS duration
args.condition	Python expressions that must evaluate as true for message to be processable, see ConditionMixin

Definition at line 241 of file library.py.

Functions

Detailed Description

Function Documentation

◆ grep()

◆ init()

◆ sink()

◆ source()