Declarative Base

Provides base for Stone Soup components.

To aid creation of components in Stone Soup, a declarative approach is used to declare properties of components. These declared properties are then used to generate the signature for the class, populate documentation, and generate forms for the user interface.

An example would be:

class Foo(Base):
    '''Example Foo class'''
    foo: str = Property(doc="foo string parameter")
    bar: int = Property(default=10, doc="bar int parameter, default is 10")

This is equivalent to the following:

class Foo:
    '''Example Foo class

    Parameters
    ----------
    foo : str
        foo string parameter
    bar : int, optional
        bar int parameter, default is 10
    '''

    def __init__(self, foo, bar=10):
        self.foo = foo
        self.bar = 10

Note

The init method is actually part of Base class so in the case of having to customise initialisation, super() should be used e.g.:

class Foo(Base):
'''Example Foo class'''
foo: str = Property(doc="foo string parameter")
bar: int = Property(default=10, doc="bar int parameter, default is 10")

def __init__(self, foo, bar=bar.default, *args, **kwargs):
    if bar < 0:
        raise ValueError("...")
    super().__init__(foo, bar, *args, **kwargs)
class stonesoup.base.Property(cls, default=inspect.Parameter.empty)[source]

Property class for definition of attributes on component classes.

A class must be provided such that the framework is aware of how components are put together to create a valid run within the framework. Additionally, the class is used by the user interface to generate configuration options to the users. The class is not used for any type checking, in the spirit of Python’s duck typing.

A default value can be specified to signify the property on the class is optional. As None and False are reasonable default values, inspect.Parameter.empty is used to signify the argument is mandatory. (Also aliased to Property.empty for ease)

A description string can also be provided which will be rendered in the documentation.

A property can be specified as read only using the (optional) readonly flag. Such properties can be written only once (when the parent object is instantiated). Any subsequent write raises an AttributeError

Property also can be used in similar way to Python standard property using getter, setter and deleter decorators.

Parameters
  • cls (class, optional) – A Python class. Where not specified, a type annotation is required, and providing both will raise an error.

  • default (any, optional) – A default value, which should be same type as class or None. Defaults to inspect.Parameter.empty (alias Property.empty)

  • doc (str, optional) – Doc string for property

  • readonly (bool, optional) – If True, then property can only be set during initialisation.

cls
default
doc
readonly
empty

Alias to inspect.Parameter.empty

Type

inspect.Parameter.empty

class stonesoup.base.BaseMeta(name, bases, namespace)[source]

Base metaclass for Stone Soup components.

This metaclass enables the use of the Property class to define attributes of a class. This includes generation of the init method signature.

The init method signature if defined on a class, the arguments must match as declared. However, keyword only arguments can be added to the init method if required, as these won’t effect the use of the class in the framework.

register(subclass)[source]

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

property subclasses

Set of subclasses for the class

property properties

Set of properties required to initialise the class

class stonesoup.base.Base[source]

Base class for framework components.

This is the base class which should be used for any Stone Soup components. Building on the BaseMeta this provides a init method which populates the declared properties with their values.

Subclasses can override this method, but they should either call this via super() or ensure they manually populated the properties as declared.