grepros.plugins Namespace Reference

Plugins interface. More...

Namespaces
namespace	auto
	Auto-loaded plugins.
namespace	embag
	ROS1 bag reader plugin using the embag library.
namespace	mcap
	MCAP input and output.
namespace	parquet
	Parquet output plugin.
namespace	sql
	SQL schema output plugin.

Functions
	add_output_label (label, flags)
	Adds plugin label to outputs enumerated in given argument help texts.
	add_write_format (name, cls, label=None, options=())
	Adds plugin to –write in main.ARGUMENTS and MultiSink formats.
	configure (args=None, **kwargs)
	Imports plugin Python packages, invokes init(args) if any, raises on error.
	get_argument (name, group=None)
	Returns a command-line argument dictionary, or None if not found.
	init (args=None, **kwargs)
	Imports and initializes all plugins from auto and from given arguments.
	load (category, args, collect=False)
	Returns a plugin category instance loaded from any configured plugin, or None.
	populate_known_plugins ()
	Adds known non-auto plugins to –plugin argument help.
	populate_output_arguments ()
	Populates argument texts with added output labels.
	populate_write_formats ()
	Populates main.ARGUMENTS with added write formats and options.

Variables
	DEFAULT_ARGS = dict(PLUGIN=[], STOP_ON_ERROR=False)
	Function argument defaults.
dict	OUTPUT_LABELS = {}
	Added output labels to insert into argument texts, as {label: [argument flag, ]}.
dict	PLUGINS = {}
	{"some.module" or "some.module.Cls": <module 'some.module' from ..> or <class 'some.module.Cls'>}
dict	WRITE_OPTIONS = {}
	Added write options, as {plugin label: [(name, help), ]}.

Detailed Description

Plugins interface.

Allows specifying custom plugins for "source", "scan" or "sink". Auto-inits any plugins in grepros.plugins.auto.

Supported (but not required) plugin interface methods:

• init(args): invoked at startup with command-line arguments
• load(category, args): invoked with category "scan" or "source" or "sink", using returned value if not None

Plugins are free to modify package internals, like adding command-line arguments to main.ARGUMENTS or sink types to outputs.MultiSink.

Convenience methods:

• plugins.add_write_format(name, cls, label=None, options=((name, help), )): adds an output plugin to defaults
• plugins.add_output_label(label, flags): adds plugin label to outputs enumerated in given argument help texts
• plugins.get_argument(name, group=None): returns a command-line argument configuration dictionary, or None

Function Documentation

add_output_label()

add_output_label	(		label,
			flags
	)

Adds plugin label to outputs enumerated in given argument help texts.

Parameters

label	output label to add, like "Parquet"
flags	list of argument flags like "--emit-field" to add the output label to

Definition at line 146 of file __init__.py.

add_write_format()

add_write_format	(		name,
			cls,
			label = None,
			options = ()
	)

Adds plugin to –write in main.ARGUMENTS and MultiSink formats.

Parameters

name	format name like "csv", added to –write .. format=FORMAT
cls	class providing Sink interface
label	plugin label; if multiple plugins add the same option, "label output" in help text is replaced with "label1/label2/.. output"
options	a sequence of (name, help) to add to –write help, like [("template=/my/path.tpl", "custom template to use for HTML output")]

Definition at line 161 of file __init__.py.

configure()

configure	(		args = None,
		**	kwargs
	)

Imports plugin Python packages, invokes init(args) if any, raises on error.

Parameters

args	arguments as namespace or dictionary, case-insensitive
args.plugin	list of Python modules or classes to import, as ["my.module", "other.module.SomeClass", ], or module or class instances
kwargs	any and all arguments as keyword overrides, case-insensitive

Definition at line 100 of file __init__.py.

get_argument()

get_argument	(		name,
			group = None
	)

Returns a command-line argument dictionary, or None if not found.

Parameters

name	argument name like "--write"
group	argument group like "Output control", if any

Definition at line 172 of file __init__.py.

init()

init	(		args = None,
		**	kwargs
	)

Imports and initializes all plugins from auto and from given arguments.

Parameters

args	arguments as namespace or dictionary, case-insensitive
args.plugin	list of Python modules or classes to import, as ["my.module", "other.module.SomeClass", ], or module or class instances
args.stop_on_error	stop execution on any error like failing to load plugin
kwargs	any and all arguments as keyword overrides, case-insensitive

Definition at line 70 of file __init__.py.

load()

load	(		category,
			args,
			collect = False
	)

Returns a plugin category instance loaded from any configured plugin, or None.

Parameters

category	item category like "source", "sink", or "scan"
args	arguments as namespace or dictionary, case-insensitive
collect	if true, returns a list of instances, using all plugins that return something

Definition at line 123 of file __init__.py.

populate_known_plugins()

populate_known_plugins

(

)

Adds known non-auto plugins to –plugin argument help.

Definition at line 209 of file __init__.py.

populate_output_arguments()

populate_output_arguments

(

)

Populates argument texts with added output labels.

Definition at line 181 of file __init__.py.

populate_write_formats()

populate_write_formats

(

)

Populates main.ARGUMENTS with added write formats and options.

Definition at line 233 of file __init__.py.

Variable Documentation

DEFAULT_ARGS

DEFAULT_ARGS = dict(PLUGIN=[], STOP_ON_ERROR=False)

Function argument defaults.

Definition at line 57 of file __init__.py.

OUTPUT_LABELS

dict OUTPUT_LABELS = {}

Added output labels to insert into argument texts, as {label: [argument flag, ]}.

Definition at line 51 of file __init__.py.

PLUGINS

dict PLUGINS = {}

{"some.module" or "some.module.Cls": <module 'some.module' from ..> or <class 'some.module.Cls'>}

Definition at line 48 of file __init__.py.

WRITE_OPTIONS

dict WRITE_OPTIONS = {}

Added write options, as {plugin label: [(name, help), ]}.

Definition at line 54 of file __init__.py.