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=None)[source]

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()[source]

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

category(name)[source]

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)[source]

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

Parameters

name (str) – Category name

widgets(category=None)[source]

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)[source]

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)[source]

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

register_widget(desc)[source]

Register a WidgetDescription instance.

register_category(desc)[source]

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)[source]

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)[source]

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, type, handler, flags=18, id=None, doc=None, replaces=())[source]

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

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

New in version 0.1.5.

Type

Tuple[str, …]

OutputSignal

class orangecanvas.registry.OutputSignal(name, type, flags=16, id=None, doc=None, replaces=())[source]

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

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

New in version 0.1.5.

Type

Tuple[str, …]

WidgetDiscovery

class orangecanvas.registry.WidgetDiscovery(registry: Optional[Union[orangecanvas.registry.base.WidgetRegistry, orangecanvas.registry.discovery.WidgetDiscovery.Handler]] = None, cached_descriptions=None)[source]

Base widget discovery runner.

run(entry_points_iter)[source]

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)[source]

Process a widget module.

process_category_package(category, name=None, distribution=None)[source]

Process a category package.

process_loader(callable)[source]

Process a callable loader function.

process_iter(iter)[source]
handle_widget(desc)[source]

Handle a found widget description.

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

handle_category(desc)[source]

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)[source]

Return an iterator over widget descriptions accessible from package.

widget_description(module, widget_name=None, category_name=None, distribution=None)[source]

Return a widget description from a module.

cache_insert(module, mtime, description, distribution=None, error=None)[source]

Insert the description into the cache.

cache_get(mod_path, distribution=None)[source]

Get the cache entry for mod_path.

cache_has_valid_entry(mod_path, distribution=None)[source]

Does the cache have a valid entry for mod_path.

cache_can_ignore(mod_path, distribution=None)[source]

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)[source]

Cache that the error occurred while processing mod_path.