==============
KSS Registries
==============

KSS can be extendend in a few different ways. To make these things
work we have a few different registries. 

The registries are all instances of a simple base class. Using these
is pretty simple.

  >>> from kss.base.registry import Registry

We will now demonstrate the working of this registry with an sample
command set.

  >>> command_set_registry = Registry()

First we will create a simple factory function for our command
set. Note that any callable object will do. For more information on
command sets look at the documentation in kss.commands.

  >>> def test_command_set_factory(commands):
  ...     pass

We can register a command set by passing in the factory and a name.

  >>> command_set_registry.register('test', test_command_set_factory)

The name is used as a unique identifier to lookup the command set factory.
When you try to register a factory under the same name you will get an error.

  >>> command_set_registry.register('test', test_command_set_factory)
  Traceback (most recent call last):
  ...
  KeyError: ...

This avoids any accidental overrides. If you want to override a command you
can unregister it first.

  >>> command_set_registry.unregister('test')

Unregistering the same thing twice will throw a KeyError.

  >>> command_set_registry.unregister('test')
  Traceback (most recent call last):
  ...
  KeyError: ...

This is because we cannot unregister what is not there.

Now that the registry is clean we can safely register our command set again.

  >>> command_set_registry.register('test', test_command_set_factory)

To use a command set we will need to get it from the registry. Let us load the
previously defined `test` set.

  >>> command_set_registry.get('test') is test_command_set_factory
  True

Trying to load a command set which is not defined will result in a key error.

  >>> command_set_registry.get('does-not-exist')
  Traceback (most recent call last):
  ...
  KeyError: ...

Registries can list theirs registered items.

  >>> list(command_set_registry.items())
  [('test', <function test_command_set_factory at ...>)]

