Registry Management

Omniduct provides some simple tooling to help manage ensembles of Duct configurations. The primary tool is the DuctRegistry, which manages Duct instances and allows them to communicate with each other.

For some simple examples on its use, please refer to the Quickstart.

class omniduct.registry.DuctRegistry(config=None)

Bases: object

A convenient registry for Duct instances.

This class provides a simple interface to a pool of configured services, allowing convenient lookups of available services and the creation of new ones. It also allows for the batch creation of services from a shared configuration, which is especially useful in a company deployment.

__init__(config=None)

Parameters:config (iterable, dict, str, None) – Refer to .import_from_config for more details (default: None).

register(duct, name=None, override=False, register_magics=True)

Register an existing Duct instance into the registry.

Names of ducts can consist of any valid Python identifier, and multiple names can be provided as a comma separated list in which case the names will be aliases referring to the same Duct instance. Keep in mind that any name must uniquely identify one Duct instance.

Parameters:

• duct (Duct) – The Duct instance to be registered.
• name (str) – An optional name to use when registering. If not provided this will fall back to duct.name. If neither is configured, an error will be thrown. Name can be a comma-separated list of names, in which case the names are aliases and will point to the same Duct instance.
• override (bool) – Whether to override any existing Duct instance of the same name. If False, any overrides will result in an exception.

Returns:

The Duct instance being registered.

Return type:

Duct

new(name, protocol, override=False, register_magics=True, **kwargs)

Create a new service and register it into the registry.

Parameters:

• name (str) – The name (or names) of the target service. If multiple aliases are to be used, names should be a comma separated list. See .register for more details.
• protocol (str) – The protocol of the new service.
• override (bool) – Whether to override any existing Duct instance of the same name. If False, any overrides will result in an exception.
• register_magics (bool) – Whether to register the magics if running in and IPython session (default: True).
• **kwargs (dict) – Additional arguments to pass to the constructor of the class associated with the nominated protocol.

Returns:

The Duct instance registered into the registry.

Return type:

Duct

names

The names of all ducts in the registry.

Type:list

lookup(name, kind=None)

Look up an existing registered Duct by name and (optionally) kind.

Parameters:

• name (str) – The name of the Duct instance.
• kind (str, Duct.Type) – The kind of Duct to which the lookup should be restricted.

Returns:

The looked up Duct instance.

Return type:

Duct

Raises:

DuctNotFound – If no Duct can be found for requested name and/or type.

populate_namespace(namespace=None, names=None, kinds=None)

Populate a nominated namespace with references to a subset of ducts.

While a registry object is a great way to store and configure Duct instances, it is sometimes desirable to surface frequently used instances in other more convenient namespaces (such as the globals of your module).

Parameters:

• namespace (dict, None) – The namespace to populate. If using from a module you can pass globals(). If None, a new dictionary is created, populated and then returned.
• names (list<str>, None) – The names to include in the population. If not specified then all names will be exported.
• kinds (list<str>, None) – The kinds of ducts to include in the population. If not specified, all kinds will be exported.

Returns:

The populated namespace.

Return type:

dict

get_proxy(by_kind=True)

Return a structured proxy object for easy exploration of services.

This method returns a proxy object to the registry upon which the Duct instances are available as attributes. This object is also by default structured such that one first accesses an attribute associated with a kind, which makes larger collections of services more easily navigatable.

For example, if you have DatabaseClient subclass registered as ‘my_service’, you could access it on the proxy using: >>> proxy = registry.get_proxy(by_kind=True) >>> proxy.databases.my_service

Parameters:by_kind (bool) – Whether to nest proxy of Duct instances by kind. Returns:The proxy object. Return type:ServicesProxy

register_from_config(config, override=False)

Register a collection of Duct service configurations.

The configuration format must be one of the following: - An iterable sequence of dictionaries containing a mapping between the

keyword arguments required to instantiate the Duct subclass.

• A dictionary mapping names of Duct instances to dictionaries of keyword arguments.
• A dictionary mapping Duct types (‘databases’, ‘filesystems’, etc) to mappings like those immediately above.
• A string YAML representation of one of the above (with at least one newline character).
• A string filename containing such a YAML representation.

There are three special keyword arguments that are required by the DuctRegistry instance: - name: Should be present only in the configuration dictionary when

config is provided as an iterable sequence of dictionaries.

• protocol: Which specifies which Duct subclass to fetch. Failure to correctly set this will result in a warning and an ignoring of this configuration.
• register_magics (optional): A boolean flag indicating whether to register any magics defined by this Duct class (default: True).

Parameters:

• config (iterable, dict, str, None) – A configuration specified in one of the above described formats.
• override (bool) – Whether to override any existing Duct instance of the same name(s). If False, any overrides will result in an exception.