API documentation for the constants_class module

The constants_class module provides the abstract base class ConstantsDataclass and the from_config method to generate instances using a dictionary to override default constant values.

The main use of the base class is to unambiguously identify dataclasses within the core and models as providing constants for use within models. To create a constants class for use in a model:

  1. Create a constants.py submodule within the model.

  2. Import the ConstantsDataclass base class.

  3. Define a new frozen dataclass as a subclass of the base class and populate the dataclass with the required constant values. See ConstantsDataclass for syntax details.

Classes:

ConstantsDataclass()

The constants dataclass abstract base class.
class virtual_ecosystem.core.constants_class.ConstantsDataclass

The constants dataclass abstract base class.

This abstract base class provides a template for all constants dataclasses in models. This allows constants classes to be identified from a common class. Within the definition of subclasses, variables can either be defined as instance variables, which can be configured by the user, or class variables, which cannot. This is useful to prevent accidental modification of truly universal constants.

@dataclass(frozen=True)
class ExampleConsts(ConstantsDataclass):

    cannot_be_changed: ClassVar[float] = 1.0
    can_be_configured: float = 2.0

Methods:

from_config(config)

Create a constants dataclass instance from a configuration dictionary.
classmethod from_config(config: dict[str, Any]) → ConstantsDataclass

Create a constants dataclass instance from a configuration dictionary.

This method accepts a configuration dictionary and validates the provided keys against the dataclass fields of the subclass. If all the keys are valid, it returns a new constants instance, overriding default values with any provided values in the dictionary.

Raises:

ConfigurationError – where the keys in the configuration dictionary do not match the subclass fields or the configuration attempts to set non-configurable universal constants.