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 = bar

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, *args, **kwargs):
    super().__init__(*args, **kwargs)
    if self.bar < 0:
        raise ValueError("...")

class stonesoup.base.Property(cls, default=inspect.Parameter.empty)

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)

Alternatively a default_factory can be specified. This must be a callable, that will be called when a value isn’t provided or is None. For example, this is useful where a default that is mutable is wanted like a list or a set. This will set default to None when provided.

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)

• default_factory (callable, optional) – A default callable, which should return same type as class. Will be called as the returned value used when value isn’t provided or is 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.

• allow_none_with_factory (bool, optional) – If True, then default_factory will be called only if value isn’t specified, else will also be called when value is None.

cls

default

default_factory

doc

readonly

allow_none_with_factory

empty

Alias to inspect.Parameter.empty

Type:

inspect.Parameter.empty

class stonesoup.base.BaseMeta(name, bases, namespace)

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)

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

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.

class stonesoup.base.ImmutableMeta(name, bases, namespace)

Metaclass for immutable Stone Soup objects. New classes using this metaclass have all the same Properties as any parent class, but all these properties are set to read-only.

class stonesoup.base.ImmutableMixIn

This MixIn class, when included in a class’s bases, forces all the Stone Soup Properties of the class to be read only. It also provides an equality check by value, provided all the values of all the properties of the class are hashable. If any of the value are not hashable, then the equality check falls back to the default equality algorithm (by identity, rather than value). If the equality check is by value, then this class also defines an appropriate hash algorithm.

Immutability is inherited: that is, all subclasses of a class which inherits from this class will have all their properties readonly, even ones defined by the subclass.

copy_with_updates(**kwargs)

Returns a shallow copy of the (immutable) object with any properties specified by keyword arguments overwritten with the specified value. The returned object is of the same type as the original object, and any unspecified properties retain their values from the original object.

Example

>>> class Demo(ImmutableMixIn)
>>>     a: int = Property()
>>>     b: float = Property()
>>>
>>> obj1 = Demo(a=1, b=1.2)
>>> obj2 = obj1.copy_with_updates(b=2.1)

After the above code obj2 would be an object of type Demo, with obj2.a == 1 and obj2.b == 2.1

Parameters:

**kwargs – Property names and values to overwrite in the copied object.

Returns:

obj – Copy of the object, with any specified properties changed.

Return type:

The same type as copied object

property property_dict: dict

Returns a dict of the names and and values of all the Property attributes of the class.

stonesoup.base.Freezable(cls: type)

This function is designed a decorator to a class. If a class (MyClass(Base)) is decorated Freezable() two things happen to the class:

First, a new class is created called FrozenMyClass which has all the same Property fields as MyClass but also inherits from ImmutableMixIn such that all properties are read only.

Second, the freeze() method is injected into MyClass so that my_obj.freeze() returns a new FrozenMyClass object with all the same values as my_obj, the only difference being that it is immutable.