Registry (registry) — Orange Canvas Core 0.0.9 documentation

# Orange Canvas Core 0.0.9 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 ‘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 (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) – Widget’s 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.