Registry (registry)

Registry

The registry module implements discovery and description of the widgets that are available/installed. The WidgetRegistry is a repository of WidgetDescription and CategoryDescription instances forming a two level widget hierarchy ([category]/[widget]).

The WidgetDiscovery can be used to populate the registry.

WidgetRegistry

class orangecanvas.registry.WidgetRegistry(other: WidgetRegistry | None = None)

A container for widget and category descriptions.

Parameters:

other (WidgetRegistry, optional) – If supplied the registry is initialized with the contents of other.

See also

WidgetDiscovery

categories() → List[CategoryDescription]

Return a list all top level CategoryDescription instances ordered by priority.

category(name: str) → CategoryDescription

Find and return a CategoryDescription by its name.

Note

Categories are identified by name attribute in contrast with widgets which are identified by qualified_name.

Parameters:

name (str) – Category name

has_category(name: str) → bool

Return True if a category with name exist in this registry.

Parameters:

name (str) – Category name

widgets(category: CategoryDescription | str | None = None) → List[WidgetDescription]

Return a list of all widgets in the registry. If category is specified return only widgets which belong to the category.

Parameters:

category (CategoryDescription or str, optional) – Return only descriptions of widgets belonging to the category.

widget(qualified_name: str) → WidgetDescription

Return a WidgetDescription identified by qualified_name.

Raise KeyError if the description does not exist.

Parameters:

qualified_name (str) – Widget description qualified name

has_widget(qualified_name: str) → bool

Return True if the widget with qualified_name exists in this registry.

register_widget(desc: WidgetDescription) → None

Register a WidgetDescription instance.

register_category(desc: CategoryDescription) → None

Register a CategoryDescription instance.

Note

It is always best to register the category before the widgets belonging to it.

WidgetDescription

class orangecanvas.registry.WidgetDescription(name, id, category=None, version=None, description=None, long_description=None, qualified_name=None, package=None, project_name=None, inputs=None, outputs=None, author=None, author_email=None, maintainer=None, maintainer_email=None, help=None, help_ref=None, url=None, keywords=None, priority=9223372036854775807, icon=None, background=None, replaces=None, short_name=None)

Description of a widget.

Parameters:

• name (str) – A human readable name of the widget.

• id (str) – A unique identifier of the widget (in most situations this should be the full module name).

• category (str, optional) – A name of the category in which this widget belongs.

• version (str, optional) – Version of the widget. By default the widget inherits the project version.

• description (str, optional) – A short description of the widget, suitable for a tool tip.

• long_description (str, optional) – A longer description of the widget, suitable for a ‘what’s this?’ role.

• qualified_name (str) – A qualified name (import name) of the class implementing the widget.

• package (str, optional) – A package name where the widget is implemented.

• project_name (str, optional) – The distribution name that provides the widget.

• inputs (Sequence[InputSignal]) – A list of input channels provided by the widget.

• outputs (Sequence[OutputSignal]) – A list of output channels provided by the widget.

• help (str, optional) – URL or an Resource template of a detailed widget help page.

• help_ref (str, optional) – A text reference id that can be used to identify the help page, for instance an intersphinx reference.

• author (str, optional) – Author name.

• author_email (str, optional) – Author email address.

• maintainer (str, optional) – Maintainer name

• maintainer_email (str, optional) – Maintainer email address.

• keywords (list-of-str, optional) – A list of keyword phrases.

• priority (int, optional) – Widget priority (the order of the widgets in a GUI presentation).

• icon (str, optional) – A filename of the widget icon (in relation to the package).

• background (str, optional) – Widget’s background color (in the canvas GUI).

• replaces (list of str, optional) – A list of ids this widget replaces (optional).

• short_name (str, optional) – Short name for display where text would otherwise elide.

CategoryDescription

class orangecanvas.registry.CategoryDescription(name=None, version=None, description=None, long_description=None, qualified_name=None, package=None, project_name=None, author=None, author_email=None, maintainer=None, maintainer_email=None, url=None, help=None, keywords=None, widgets=None, priority=9223372036854775807, icon=None, background=None, hidden=False)

Description of a widget category.

Parameters:

• name (str) – A human readable name.

• version (str, optional) – Version string.

• description (str, optional) – A short description of the category, suitable for a tool tip.

• long_description (str, optional) – A longer description.

• qualified_name (str,) – Qualified name

• project_name (str) – A project name providing the category.

• priority (int) – Priority (order in the GUI).

• icon (str) – An icon filename (a resource name retrievable using pkgutil.get_data relative to qualified_name).

• background (str) – An background color for widgets in this category.

• hidden (bool) – Is this category (by default) hidden in the canvas gui.

InputSignal

class orangecanvas.registry.InputSignal(name: str, type: TypeSpec, handler: str, flags: int = 18, id: str | None = None, doc: str | None = None, replaces: Iterable[str] = ())

Description of an input channel.

Parameters:

• name (str) – Name of the channel.

• type (Union[str, type] or Tuple[Union[str, type]]) –

  Specify the type of the accepted input. This can be a type instance, a fully qualified type name or a tuple of such. If a tuple then the input type is a union of the passed types.

  Changed in version 0.1.5: Added Union type support.

• handler (str) – Name of the handler method for the signal.

• flags (int) – Channel flags.

• id (str, optional) – A unique id of the input signal.

• doc (str, optional) – A docstring documenting the channel.

• replaces (Iterable[str]) – A list of names this input replaces.

property types: Tuple[str, ...]

The normalized type specification. This is a tuple of qualified type names that were passed to the constructor.

Added in version 0.1.5.

Type:

Tuple[str, …]

OutputSignal

class orangecanvas.registry.OutputSignal(name: str, type: TypeSpec, flags: int = 16, id: str | None = None, doc: str | None = None, replaces: Iterable[str] = ())

Description of an output channel.

Parameters:

• name (str) – Name of the channel.

• type (Union[str, type] or Tuple[Union[str, type]]) –

  Specify the type of the output. This can be a type instance, a fully qualified type name or a tuple of such. If a tuple then the output type is a union of the passed types.

  Changed in version 0.1.5: Added Union type support.

• flags (int, optional) – Channel flags.

• id (str) – A unique id of the output signal.

• doc (str, optional) – A docstring documenting the channel.

• replaces (List[str]) – A list of names this output replaces.

property types: Tuple[str, ...]

The normalized type specification. This is a tuple of qualified type names that were passed to the constructor.

Added in version 0.1.5.

Type:

Tuple[str, …]

WidgetDiscovery

class orangecanvas.registry.WidgetDiscovery(registry: WidgetRegistry | Handler | None = None, cached_descriptions=None)

Base widget discovery runner.

run(entry_points_iter)

Run the widget discovery process from an entry point iterator (yielding importlib.metadata.EntryPoint instances).

As a convenience, if entry_points_iter is a string it will be used to retrieve the iterator using importlib.metadata.entry_points.

process_widget_module(module, name=None, category_name=None, distribution=None)

Process a widget module.

process_category_package(category, name=None, distribution=None)

Process a category package.

process_loader(callable)

Process a callable loader function.

process_iter(iter)

handle_widget(desc)

Handle a found widget description.

Base implementation adds it to the registry supplied in the constructor.

handle_category(desc)

Handle a found category description.

Base implementation adds it to the registry supplied in the constructor.

iter_widget_descriptions(package, category_name=None, distribution=None)

Return an iterator over widget descriptions accessible from package.

widget_description(module, widget_name=None, category_name=None, distribution=None)

Return a widget description from a module.

cache_insert(module, mtime, description, distribution=None, error=None)

Insert the description into the cache.

cache_get(mod_path, distribution=None)

Get the cache entry for mod_path.

cache_has_valid_entry(mod_path, distribution=None)

Does the cache have a valid entry for mod_path.

cache_can_ignore(mod_path, distribution=None)

Can the mod_path be ignored (i.e. it was determined that it could not contain a valid widget description, for instance the module does not have a valid description and was not changed from the last discovery run).

cache_log_error(mod_path, error, distribution=None)

Cache that the error occurred while processing mod_path.