Namespaces
namespace	auto

namespace	embag

namespace	mcap

namespace	parquet

namespace	sql

Functions
	add_output_label (label, flags)

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

	configure (args=None, **kwargs)

	get_argument (name, group=None)

	init (args=None, **kwargs)

	load (category, args, collect=False)

	populate_known_plugins ()

	populate_output_arguments ()

	populate_write_formats ()

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

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

@author      Erki Suurjaak
@created     18.12.2021
@modified    14.07.2023
------------------------------------------------------------------------------

Function Documentation

◆ add_output_label()

add_output_label	(	label,
		flags
	)

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

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

Definition at line 141 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.

@param   name     format name like "csv", added to `--write .. format=FORMAT`
@param   cls      class providing Sink interface
@param   label    plugin label; if multiple plugins add the same option,
                  "label output" in help text is replaced with "label1/label2/.. output"
@param   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 151 of file __init__.py.

◆ configure()

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

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

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

Definition at line 91 of file __init__.py.

◆ get_argument()

get_argument	(	name,
		group = `None`
	)

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

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

Definition at line 166 of file __init__.py.

◆ init()

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

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

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

Definition at line 60 of file __init__.py.

◆ load()

load	(	category,
		args,
		collect = `False`
	)

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

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

Definition at line 116 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.

Namespaces

Functions

Variables