iotile.core.dev.registry

Module Contents

MISSING
class ComponentRegistry

ComponentRegistry

A mapping of all of the installed components on this system that can be used as build dependencies and where they are located. Also used to manage iotile plugins.

BackingType
BackingFileName = component_registry.db
_registered_extensions
_component_overlays
_frozen_extensions
frozen

Return whether we have a cached list of all installed entry_points.

kvstore

Lazily load the underlying key-value store backing this registry.

plugins

Lazily load iotile plugins only on demand.

This is a slow operation on computers with a slow FS and is rarely accessed information, so only compute it when it is actually asked for.

load_extensions(self, group, name_filter=None, comp_filter=None, class_filter=None, product_name=None, unique=False)

Dynamically load and return extension objects of a given type.

This is the centralized way for all parts of CoreTools to allow plugin behavior. Whenever a plugin is needed, this method should be called to load it. Examples of plugins are proxy modules, emulated tiles, iotile-build autobuilders, etc.

Each kind of plugin will typically be a subclass of a certain base class and can be provided one of three ways:

  1. It can be registered as an entry point in a pip installed package. The entry point group must map the group passed to load_extensions.
  2. It can be listed as a product of an IOTile component that is stored in this ComponentRegistry. The relevant python file inside the component will be imported dynamically as needed.
  3. It can be programmatically registered by calling register_extension() on this class with a string name and an object. This is equivalent to exposing that same object as an entry point with the given name.

There is special behavior of this function if class_filter is passed and the object returned by one of the above three methods is a python module. The module will be search for object definitions that match the defined class.

The order of the returned objects list is only partially defined. Locally installed components are searched before pip installed packages with entry points. The order of results within each group is not specified.

Args:
group (str): The extension type that you wish to enumerate. This
will be used as the entry_point group for searching pip installed packages.

name_filter (str): Only return objects with the given name comp_filter (str): When searching through installed components

(not entry_points), only search through components with the given name.
class_filter (type or tuple of types): An object that will be passed to
instanceof() to verify that all extension objects have the correct types. If not passed, no checking will be done.
product_name (str): If this extension can be provided by a registered
local component, the name of the product that should be loaded.
unique (bool): If True (default is False), there must be exactly one object
found inside this extension that matches all of the other criteria.
Returns:

list of (str, object): A list of the found and loaded extension objects.

The string returned with each extension is the name of the entry_point or the base name of the file in the component or the value provided by the call to register_extension depending on how the extension was found.

If unique is True, then the list only contains a single entry and that entry will be directly returned.

register_extension(self, group, name, extension)

Register an extension.

Args:

group (str): The type of the extension name (str): A name for the extension extension (str or class): If this is a string, then it will be

interpreted as a path to import and load. Otherwise it will be treated as the extension object itself.
clear_extensions(self, group=None)

Clear all previously registered extensions.

freeze_extensions(self)

Freeze the set of extensions into a single file.

Freezing extensions can speed up the extension loading process on machines with slow file systems since it requires only a single file to store all of the extensions.

Calling this method will save a file into the current virtual environment that stores a list of all currently found extensions that have been installed as entry_points. Future calls to load_extensions will only search the one single file containing frozen extensions rather than enumerating all installed distributions.

unfreeze_extensions(self)

Remove a previously frozen list of extensions.

load_extension(self, path, name_filter=None, class_filter=None, unique=False, component=None)

Load a single python module extension.

This function is similar to using the imp module directly to load a module and potentially inspecting the objects it declares to filter them by class.

Args:

path (str): The path to the python file to load name_filter (str): If passed, the basename of the module must match

name or nothing is returned.

class_filter (type): If passed, only instance of this class are returned. unique (bool): If True (default is False), there must be exactly one object

found inside this extension that matches all of the other criteria.
component (IOTile): The component that this extension comes from if it is
loaded from an installed component. This is used to properly import the extension as a submodule of the component’s support package.
Returns:

list of (name, type): A list of the objects found at the extension path.

If unique is True, then the list only contains a single entry and that entry will be directly returned.

_load_frozen_extensions(self)
_iter_entrypoint_group(self, group)
classmethod _filter_nonextensions(cls, obj)

Remove all classes marked as not extensions.

This allows us to have a deeper hierarchy of classes than just one base class that is filtered by _filter_subclasses. Any class can define a class propery named:

__NO_EXTENSION__ = True

That class will never be returned as an extension. This is useful for masking out base classes for extensions that are declared in CoreTools and would be present in module imports but should not create a second entry point.

classmethod _dump_extensions(cls, prefix='iotile.')
_filter_subclasses(self, obj, class_filter)
classmethod SetBackingStore(cls, backing)

Set the global backing type used by the ComponentRegistry from this point forward

This function must be called before any operations that use the registry are initiated otherwise they will work from different registries that will likely contain different data

add_component(self, component, temporary=False)

Register a component with ComponentRegistry.

Component must be a buildable object with a module_settings.json file that describes its name and the domain that it is part of. By default, this component is saved in the permanent registry associated with this environment and will remain registered for future CoreTools invocations.

If you only want this component to be temporarily registered during this program’s session, you can pass temporary=True and the component will be stored in RAM only, not persisted to the underlying key-value store.

Args:

component (str): The path to a component that should be registered. temporary (bool): Optional flag to only temporarily register the

component for the duration of this program invocation.
get_component(self, component)
list_plugins(self)

List all of the plugins that have been registerd for the iotile program on this computer

find_component(self, key, domain='')
remove_component(self, key)

Remove component from registry

clear_components(self)

Clear all of the registered components

clear(self)

Clear all data from the registry

list_components(self)

List all of the registered component names.

This list will include all of the permanently stored components as well as any temporary components that were added with a temporary=True flag in this session.

Returns:

list of str: The list of component names.

Any of these names can be passed to get_component as is to get the corresponding IOTile object.

iter_components(self)

Iterate over all defined components yielding IOTile objects.

list_config(self)

List all of the configuration variables

set_config(self, key, value)

Set a persistent config key to a value, stored in the registry

Args:
key (string): The key name value (string): The key value
get_config(self, key, default=MISSING)

Get the value of a persistent config key from the registry

If no default is specified and the key is not found ArgumentError is raised.

Args:
key (string): The key name to fetch default (string): an optional value to be returned if key cannot be found
Returns:
string: the key’s value
clear_config(self, key)

Remove a persistent config key from the registry

Args:
key (string): The key name
_registry_folder(folder=None)
_check_registry_type(folder=None)

Check if the user has placed a registry_type.txt file to choose the registry type

If a default registry type file is found, the DefaultBackingType and DefaultBackingFile class parameters in ComponentRegistry are updated accordingly.

Args:
folder (string): The folder that we should check for a default registry type
_ensure_package_loaded(path, component)

Ensure that the given module is loaded as a submodule.

Returns:
str: The name that the module should be imported as.
_try_load_module(path, import_name=None)

Try to programmatically load a python module by path.

Path should point to a python file (optionally without the .py) at the end. If it ends in a :<name> then name must point to an object defined in the module, which is returned instead of the module itself.

Args:

path (str): The path of the module to load import_name (str): The explicity name that the module should be given.

If not specified, this defaults to being the basename() of path. However, if the module is inside of a support package, you should pass the correct name so that relative imports proceed correctly.
Returns:
str, object: The basename of the module loaded and the requested object.