Registry (registry)

# Orange Canvas Core 0.0.8 documentation

## Registry (registry)

# 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)

  A container for widget and category descriptions.

      >>> reg = WidgetRegistry()
      >>> file_desc = WidgetDescription.from_module(
      ...     "Orange.OrangeWidgets.Data.OWFile"
      ... )
      ...
      >>> reg.register_widget(file_desc)  # register the description
      >>> print reg.widgets()
      [...

  Parameters: | other (`WidgetRegistry`, optional) If supplied the registry is initialized with the contents of other.

  See also

  `WidgetDiscovery`

  `categories`()

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

  `category`(name)

    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)

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

    Parameters: | name (str) Category name

  `widgets`(category=None)

    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)

    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)

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

  `register_widget`(desc)

    Register a `WidgetDescription` instance.

  `register_category`(desc)

    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=[], outputs=[], 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)

  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 whats 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 (list of `InputSignal`, optional) A list of input channels provided by the widget. outputs (list of `OutputSignal`, optional) 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) Widgets background color (in the canvas GUI). replaces (list-of-str, optional) A list of ids this widget replaces (optional).

  classmethod `from_module`(module)

    Get the widget description from a module.

    The module is inspected for global variables (upper case versions of WidgetDescription.__init__ parameters).

    Parameters: | module (module or str) A module to inspect for widget description. Can be passed as a string (qualified import name).

## 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 pkg_resources 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.

  classmethod `from_package`(package)

    Get the CategoryDescription from a package.

    Parameters: | package (module or str) A package containing the category.

## InputSignal

class `orangecanvas.registry.` `InputSignal`(name, type, handler, flags=18, id=None, doc=None, replaces=[])

  Description of an input channel.

  Parameters: | name (str) Name of the channel. type (str or type) Type of the accepted signals. handler (str) Name of the handler method for the signal. flags (int, optional) Channel flags. id (str) A unique id of the input signal. doc (str, optional) A docstring documenting the channel. replaces (List[str]) A list of names this input replaces.

## OutputSignal

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

  Description of an output channel.

  Parameters: | name (str) Name of the channel. type (str or type) Type of the output signals. 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.

## WidgetDiscovery

class `orangecanvas.registry.` `WidgetDiscovery`(registry=None, cached_descriptions=None)

  Base widget discovery runner.

  `run`(entry_points_iter)

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

    As a convenience, if entry_points_iter is a string it will be used to retrieve the iterator using pkg_resources.iter_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.