fameio 2.3.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

fameio/input/schema/agenttype.py

@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from typing import Any, Final
+
+from fameio.input import InputError, SchemaError
+from fameio.input.metadata import Metadata, MetadataComponent, ValueContainer
+from fameio.logs import log_error_and_raise, log
+from fameio.tools import keys_to_lower
+from .attribute import AttributeSpecs
+
+
+class AgentType(Metadata):
+    """Schema definitions for an Agent type"""
+
+    KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
+    KEY_PRODUCTS: Final[str] = "Products".lower()
+    KEY_OUTPUTS: Final[str] = "Outputs".lower()
+
+    _ERR_NAME_INVALID = "'{}' is not a valid name for AgentTypes"
+    _ERR_NO_STRING = "{} definition of AgentType '{}' contains keys other than string: '{}'"
+    _ERR_UNKNOWN_STRUCTURE = "{} definition of AgentType '{}' is neither list nor dictionary: '{}'"
+
+    _NO_ATTRIBUTES = "Agent '{}' has no specified 'Attributes'."
+    _NO_PRODUCTS = "Agent '{}' has no specified 'Products'."
+    _NO_OUTPUTS = "Agent '{}' has no specified 'Outputs'."
+
+    def __init__(self, name: str):
+        """
+        Initialise a new AgentType
+
+        Args:
+            name: name of the AgenType - must not be None, empty or only whitespaces
+        """
+        super().__init__()
+        if not name or name.isspace():
+            log_error_and_raise(SchemaError(AgentType._ERR_NAME_INVALID.format(name)))
+        self._name = name
+        self._attributes: dict[str, AttributeSpecs] = {}
+        self._products: ValueContainer = ValueContainer()
+        self._outputs: ValueContainer = ValueContainer()
+
+    @classmethod
+    def from_dict(cls, name: str, definitions: dict) -> AgentType:
+        """
+        Creates AgentType with given `name` from specified dictionary
+
+        Args:
+            name: of the agent type
+            definitions: of the agent type specifying, e.g., its attributes and products
+
+        Returns:
+            a new instance of AgentType
+        """
+        agent_type = cls(name)
+        agent_type._extract_metadata(definitions)
+
+        definition = keys_to_lower(definitions)
+        if AgentType.KEY_ATTRIBUTES in definition:
+            for attribute_name, attribute_details in definition[AgentType.KEY_ATTRIBUTES].items():
+                full_name = name + "." + attribute_name
+                agent_type._attributes[attribute_name] = AttributeSpecs(full_name, attribute_details)
+        else:
+            log().info(AgentType._NO_ATTRIBUTES.format(name))
+
+        if AgentType.KEY_PRODUCTS in definition and definition[AgentType.KEY_PRODUCTS]:
+            agent_type._products = AgentType._read_values(
+                section="Products", agent_type=name, values=definition[AgentType.KEY_PRODUCTS]
+            )
+        else:
+            log().info(AgentType._NO_PRODUCTS.format(name))
+
+        if AgentType.KEY_OUTPUTS in definition and definition[AgentType.KEY_OUTPUTS]:
+            agent_type._outputs = AgentType._read_values(
+                section="Outputs", agent_type=name, values=definition[AgentType.KEY_OUTPUTS]
+            )
+        else:
+            log().debug(AgentType._NO_OUTPUTS.format(name))
+
+        return agent_type
+
+    @staticmethod
+    def _read_values(section: str, agent_type: str, values: Any) -> ValueContainer:
+        """Returns ValueContainer for `section` of in specifications of `agent_type` extracted from given `values`"""
+        try:
+            data = ValueContainer(values)
+        except InputError:
+            log_error_and_raise(SchemaError(AgentType._ERR_UNKNOWN_STRUCTURE.format(section, agent_type, values)))
+        else:
+            if not all([isinstance(item, str) for item in data.as_list()]):
+                log_error_and_raise(SchemaError(AgentType._ERR_NO_STRING.format(section, agent_type, data.as_list())))
+            return data
+
+    @property
+    def name(self) -> str:
+        """Returns the agent type name"""
+        return self._name
+
+    @property
+    def products(self) -> dict[str, MetadataComponent]:
+        """Returns dict of products or an empty dict if no products are defined"""
+        return self._products.values
+
+    def get_product_names(self) -> list[str]:
+        """Returns list of product names or an empty list if no products are defined"""
+        return self._products.as_list()
+
+    @property
+    def attributes(self) -> dict[str, AttributeSpecs]:
+        """Returns list of Attributes of this agent or an empty list if no attributes are defined"""
+        return self._attributes
+
+    @property
+    def outputs(self) -> dict[str, MetadataComponent]:
+        """Returns list of outputs or an empty list if no outputs are defined"""
+        return self._outputs.values
+
+    def _to_dict(self) -> dict:
+        return {
+            self.KEY_ATTRIBUTES: {name: attribute.to_dict() for name, attribute in self._attributes.items()},
+            self.KEY_PRODUCTS: self._products.to_dict(),
+            self.KEY_OUTPUTS: self._outputs.to_dict(),
+        }

fameio/input/schema/attribute.py

@@ -0,0 +1,268 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from enum import Enum, auto
+from typing import Any, Optional, Final, Union
+
+from fameio.input import SchemaError
+from fameio.input.metadata import Metadata, ValueContainer
+from fameio.logs import log
+from fameio.time import FameTime
+from fameio.tools import keys_to_lower
+
+
+class AttributeType(Enum):
+    """Data types that Attributes can take"""
+
+    INTEGER = auto()
+    DOUBLE = auto()
+    LONG = auto()
+    TIME_STAMP = auto()
+    STRING = auto()
+    STRING_SET = auto()
+    ENUM = auto()
+    TIME_SERIES = auto()
+    BLOCK = auto()
+
+    def convert_string_to_type(self, value: str) -> Union[int, float, str]:
+        """
+        Converts a given string to this AttributeType's data format
+
+        Args:
+            value: string to be converted
+
+        Returns:
+            value converted to data format associated with AttributeType
+
+        Raises:
+            ValueError: if data conversion failed, e.g. due to improper string content
+        """
+        if self is AttributeType.INTEGER or self is AttributeType.LONG:
+            return int(value)
+        elif self is AttributeType.DOUBLE:
+            return float(value)
+        elif self is AttributeType.TIME_STAMP:
+            return FameTime.convert_string_if_is_datetime(value)
+        elif self is AttributeType.ENUM or self is AttributeType.STRING or self is AttributeType.STRING_SET:
+            return str(value)
+        elif self is AttributeType.TIME_SERIES:
+            return float(value)
+        else:
+            raise ValueError("String conversion not supported for '{}'.".format(self))
+
+
+class AttributeSpecs(Metadata):
+    """Schema Definition of a single Attribute (with possible inner Attributes) of an agent"""
+
+    _DISALLOWED_NAMES = ["value", "values", "metadata"]
+    _SEPARATOR = "."
+
+    KEY_MANDATORY: Final[str] = "Mandatory".lower()
+    KEY_LIST: Final[str] = "List".lower()
+    KEY_TYPE: Final[str] = "AttributeType".lower()
+    KEY_NESTED: Final[str] = "NestedAttributes".lower()
+    KEY_VALUES: Final[str] = "Values".lower()
+    KEY_DEFAULT: Final[str] = "Default".lower()
+    KEY_HELP: Final[str] = "Help".lower()
+
+    _EMPTY_DEFINITION = "Definitions missing for Attribute '{}'."
+    _MISSING_SPEC_DEFAULT = "Missing '{}' specification for Attribute '{}' - assuming {}."
+    _MISSING_TYPE = "'AttributeType' not declare for Attribute '{}'."
+    _INVALID_TYPE = "'{}' is not a valid type for an Attribute."
+    _DEFAULT_NOT_LIST = "Attribute is list, but provided Default '{}' is not a list."
+    _INCOMPATIBLE = "Value '{}' in section '{}' can not be converted to AttributeType '{}'."
+    _DEFAULT_DISALLOWED = "Default '{}' is not an allowed value."
+    _LIST_DISALLOWED = "Attribute '{}' of type TIME_SERIES cannot be a list."
+    _VALUES_ILL_FORMAT = "Only List and Dictionary is supported for 'Values' but was: {}"
+    _NAME_DISALLOWED = f"Attribute name must not be empty and none of: {_DISALLOWED_NAMES}"
+
+    def __init__(self, name: str, definition: dict):
+        """Loads Attribute from given `definition`"""
+        super().__init__(definition)
+        if self._name_is_disallowed(name):
+            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+
+        self._full_name = name
+        if not definition:
+            raise SchemaError(AttributeSpecs._EMPTY_DEFINITION.format(name))
+        definition = keys_to_lower(definition)
+
+        if AttributeSpecs.KEY_MANDATORY in definition:
+            self._is_mandatory = definition[AttributeSpecs.KEY_MANDATORY]
+        else:
+            self._is_mandatory = True
+            log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_MANDATORY, name, True))
+
+        if AttributeSpecs.KEY_LIST in definition:
+            self._is_list = definition[AttributeSpecs.KEY_LIST]
+        else:
+            self._is_list = False
+            log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_LIST, name, False))
+
+        if AttributeSpecs.KEY_TYPE in definition:
+            self._attr_type = AttributeSpecs._get_type_for_name(definition[AttributeSpecs.KEY_TYPE])
+        else:
+            log().error(AttributeSpecs._MISSING_TYPE.format(name))
+            raise SchemaError(AttributeSpecs._MISSING_TYPE.format(name))
+
+        if self._attr_type == AttributeType.TIME_SERIES and self._is_list:
+            raise SchemaError(AttributeSpecs._LIST_DISALLOWED.format(name))
+
+        self._allowed_values: ValueContainer = ValueContainer()
+        if AttributeSpecs.KEY_VALUES in definition:
+            value_definition = definition[AttributeSpecs.KEY_VALUES]
+            if value_definition:
+                self._allowed_values = self._read_values(value_definition)
+
+        self._default_value = None
+        if AttributeSpecs.KEY_DEFAULT in definition:
+            provided_value = definition[AttributeSpecs.KEY_DEFAULT]
+            if self._is_list:
+                self._default_value = self._convert_list(provided_value)
+            else:
+                self._default_value = self._convert_and_test(provided_value)
+
+        self._nested_attributes = {}
+        if AttributeSpecs.KEY_NESTED in definition:
+            for nested_name, nested_details in definition[AttributeSpecs.KEY_NESTED].items():
+                full_name = name + self._SEPARATOR + nested_name
+                self._nested_attributes[nested_name] = AttributeSpecs(full_name, nested_details)
+
+        self._help = None
+        if AttributeSpecs.KEY_HELP in definition:
+            self._help = definition[AttributeSpecs.KEY_HELP].strip()
+
+    @staticmethod
+    def _name_is_disallowed(full_name: str) -> bool:
+        """Returns True if name is not allowed"""
+        if full_name is None:
+            return True
+        short_name = full_name.split(AttributeSpecs._SEPARATOR)[-1]
+        if len(short_name) == 0 or short_name.isspace():
+            return True
+        return short_name.lower() in AttributeSpecs._DISALLOWED_NAMES
+
+    def _read_values(self, definition: [dict, list]) -> ValueContainer:
+        """
+        Returns accepted values mapped to their additional metadata specifications extracted from given `definition`
+        Accepts lists of accepted values or dictionaries with (optional) metadata assigned to each value
+
+        Args:
+            definition: list of acceptable values or dict with acceptable values as keys and (optional) metadata content
+
+        Returns:
+            Mapping of acceptable values to their associated Metadata
+        """
+        try:
+            value_container = ValueContainer(definition)
+            for value in value_container.as_list():
+                self._convert_to_data_type(value, self.KEY_VALUES)
+            return value_container
+        except ValueContainer.ParseError:
+            raise SchemaError(AttributeSpecs._VALUES_ILL_FORMAT.format(definition))
+
+    def _convert_to_data_type(self, value: str, section: str) -> Union[int, float, str]:
+        """Returns a given single `value` in `section` converted to this Attribute's data type"""
+        try:
+            return self._attr_type.convert_string_to_type(value)
+        except ValueError:
+            raise SchemaError(AttributeSpecs._INCOMPATIBLE.format(value, section, self._attr_type))
+
+    def _convert_list(self, values) -> list:
+        """Converts all entries in given `values` list to this attribute data type and returns this new list"""
+        if isinstance(values, list):
+            return [self._convert_and_test(item) for item in values]
+        else:
+            raise SchemaError(AttributeSpecs._DEFAULT_NOT_LIST.format(values))
+
+    def _convert_and_test(self, value: str):
+        """Converts a given single `value` to this Attribute's data type and tests if the value is allowed"""
+        if self.has_value_restrictions and (not self._allowed_values.has_value(value)):
+            raise SchemaError(AttributeSpecs._DEFAULT_DISALLOWED.format(value))
+        return self._convert_to_data_type(value, self.KEY_DEFAULT)
+
+    @property
+    def attr_type(self) -> AttributeType:
+        """Returns AttributeType of this attribute"""
+        return self._attr_type
+
+    @property
+    def values(self) -> list:
+        """Returns the list of allowed values for this attribute"""
+        return self._allowed_values.as_list()
+
+    @property
+    def has_value_restrictions(self) -> bool:
+        """Returns True if the attribute can only take a set of certain values"""
+        return not self._allowed_values.is_empty()
+
+    @property
+    def is_list(self) -> bool:
+        """Return True if this attribute type is a list"""
+        return self._is_list
+
+    @property
+    def has_nested_attributes(self) -> bool:
+        """Returns True if nested attributes are defined"""
+        return bool(self._nested_attributes)
+
+    @property
+    def nested_attributes(self) -> dict[str, AttributeSpecs]:
+        """Returns list of nested Attributes of this Attribute or an empty dict if no nested attributes are defined"""
+        return self._nested_attributes
+
+    @property
+    def has_default_value(self) -> bool:
+        """Return True if a default value is available"""
+        return self._default_value is not None
+
+    @property
+    def default_value(self) -> Optional[Any]:
+        """Return the default value of this attribute, or None if no default is specified"""
+        return self._default_value
+
+    @property
+    def is_mandatory(self) -> bool:
+        """Return True if this attribute is mandatory"""
+        return self._is_mandatory
+
+    @property
+    def full_name(self) -> str:
+        """Returns name including name of enclosing parent attributes"""
+        return self._full_name
+
+    @staticmethod
+    def _get_type_for_name(name: str) -> AttributeType:
+        """Returns the AttributeType matching the given `name` converted to upper case"""
+        try:
+            return AttributeType[name.upper()]
+        except KeyError:
+            raise SchemaError(AttributeSpecs._INVALID_TYPE.format(name))
+
+    @property
+    def has_help_text(self) -> bool:
+        """Return True if a help_text is available"""
+        return bool(self._help)
+
+    @property
+    def help_text(self) -> str:
+        """Return the help_text of this attribute, if any, otherwise an empty string"""
+        return self._help if self.has_help_text else ""
+
+    def _to_dict(self) -> dict[str, Any]:
+        definition = {
+            self.KEY_TYPE: self._attr_type.name,
+            self.KEY_MANDATORY: self._is_mandatory,
+            self.KEY_LIST: self._is_list,
+        }
+        if self.has_help_text:
+            definition[self.KEY_HELP] = self._help
+        if self.has_default_value:
+            definition[self.KEY_DEFAULT] = self._default_value
+        if self.has_value_restrictions:
+            definition[self.KEY_VALUES] = self._allowed_values.to_dict()
+        if self.has_nested_attributes:
+            definition[self.KEY_NESTED] = {name: inner.to_dict() for name, inner in self.nested_attributes.items()}
+        return definition

fameio/{source → input}/schema/java_packages.py

@@ -3,31 +3,31 @@
 # SPDX-License-Identifier: Apache-2.0
 from __future__ import annotations
 
-from typing import List, Dict
+from typing import Final
 
-from fameio.source.logs import log_error_and_raise
-from fameio.source.schema import SchemaException
-from fameio.source.tools import keys_to_lower
+from fameio.input import SchemaError
+from fameio.logs import log_error_and_raise, log
+from fameio.tools import keys_to_lower
 
 
 class JavaPackages:
     """Schema definitions for Java package names in which model classes reside"""
 
+    KEY_AGENT: Final[str] = "Agents".lower()
+    KEY_DATA_ITEM: Final[str] = "DataItems".lower()
+    KEY_PORTABLE: Final[str] = "Portables".lower()
+
     _ERR_MISSING_AGENTS = "JavaPackages requires non-empty list for `Agents`. Key was missing or list was empty."
-    _ERR_MISSING_DATA_ITEMS = "JavaPackages requires non-empty list for `DataItems`. Key was missing or list was empty."
+    _INFO_MISSING_DATA_ITEMS = "`DataItems` not specified: Key was missing or list was empty."
     _ERR_MISSING_PORTABLES = "JavaPackages require non-empty list for `Portables`. Key was missing or list was empty."
 
-    _KEY_AGENT = "Agents".lower()
-    _KEY_DATA_ITEM = "DataItems".lower()
-    _KEY_PORTABLE = "Portables".lower()
-
     def __init__(self):
-        self._agents: List[str] = []
-        self._data_items: List[str] = []
-        self._portables: List[str] = []
+        self._agents: list[str] = []
+        self._data_items: list[str] = []
+        self._portables: list[str] = []
 
     @classmethod
-    def from_dict(cls, definitions: Dict[str, List[str]]) -> JavaPackages:
+    def from_dict(cls, definitions: dict[str, list[str]]) -> JavaPackages:
         """
         Creates JavaPackages from a dictionary representation
 
@@ -40,30 +40,34 @@ class JavaPackages:
         java_packages = cls()
         definitions = keys_to_lower(definitions)
 
-        java_packages._agents = definitions.get(JavaPackages._KEY_AGENT, [])
-        java_packages._data_items = definitions.get(JavaPackages._KEY_DATA_ITEM, [])
-        java_packages._portables = definitions.get(JavaPackages._KEY_PORTABLE, [])
+        java_packages._agents = definitions.get(JavaPackages.KEY_AGENT, [])
+        java_packages._data_items = definitions.get(JavaPackages.KEY_DATA_ITEM, [])
+        java_packages._portables = definitions.get(JavaPackages.KEY_PORTABLE, [])
 
         if not java_packages._agents:
-            log_error_and_raise(SchemaException(JavaPackages._ERR_MISSING_AGENTS))
+            log_error_and_raise(SchemaError(JavaPackages._ERR_MISSING_AGENTS))
         if not java_packages._data_items:
-            log_error_and_raise(SchemaException(JavaPackages._ERR_MISSING_DATA_ITEMS))
+            log().info(JavaPackages._INFO_MISSING_DATA_ITEMS)
         if not java_packages._portables:
-            log_error_and_raise(SchemaException(JavaPackages._ERR_MISSING_PORTABLES))
+            log_error_and_raise(SchemaError(JavaPackages._ERR_MISSING_PORTABLES))
 
         return java_packages
 
     @property
-    def agents(self) -> List[str]:
+    def agents(self) -> list[str]:
         """Return list of java package names that contain the model's Agents"""
         return self._agents
 
     @property
-    def data_items(self) -> List[str]:
+    def data_items(self) -> list[str]:
         """Return list of java package names that contain the model's DataItems"""
         return self._data_items
 
     @property
-    def portables(self) -> List[str]:
+    def portables(self) -> list[str]:
         """Return list of java package names that contain the model's Portables"""
         return self._portables
+
+    def to_dict(self) -> dict[str, list[str]]:
+        """Return dictionary representation of this JavaPackages object"""
+        return {self.KEY_AGENT: self.agents, self.KEY_DATA_ITEM: self.data_items, self.KEY_PORTABLE: self.portables}

fameio/{source → input}/schema/schema.py

@@ -4,52 +4,55 @@
 from __future__ import annotations
 
 import ast
-from typing import Dict, Optional
+from typing import Any, Final
 
-from fameio.source.logs import log_error_and_raise, log
-from fameio.source.schema.agenttype import AgentType
-from fameio.source.schema.exception import SchemaException
-from fameio.source.schema.java_packages import JavaPackages
-from fameio.source.tools import keys_to_lower
+from fameio.input import SchemaError
+from fameio.logs import log_error_and_raise
+from fameio.tools import keys_to_lower
+from .agenttype import AgentType
+from .java_packages import JavaPackages
 
 
 class Schema:
     """Definition of a schema"""
 
+    KEY_AGENT_TYPE: Final[str] = "AgentTypes".lower()
+    KEY_PACKAGES: Final[str] = "JavaPackages".lower()
+
     _ERR_AGENT_TYPES_MISSING = "Required keyword `AgentTypes` missing in Schema."
     _ERR_AGENT_TYPES_EMPTY = "`AgentTypes` must not be empty - at least one type of agent is required."
-    _WARN_MISSING_PACKAGES = "No `JavaPackages` defined Schema. Future versions of fameio will require it."
-
-    _KEY_AGENT_TYPE = "AgentTypes".lower()
-    _KEY_PACKAGES = "JavaPackages".lower()
+    _ERR_MISSING_PACKAGES = "Missing required section `JavaPackages` in Schema."
 
     def __init__(self, definitions: dict):
         self._original_input_dict = definitions
         self._agent_types = {}
-        self._packages: Optional[JavaPackages] = None
+        self._packages = None
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Schema:
         """Load given dictionary `definitions` into a new Schema"""
         definitions = keys_to_lower(definitions)
-        if Schema._KEY_AGENT_TYPE not in definitions:
-            log_error_and_raise(SchemaException(Schema._ERR_AGENT_TYPES_MISSING))
         schema = cls(definitions)
-        agent_types = definitions[Schema._KEY_AGENT_TYPE]
-        if len(agent_types) == 0:
-            log_error_and_raise(SchemaException(Schema._ERR_AGENT_TYPES_EMPTY))
 
+        agent_types = cls._get_or_raise(definitions, Schema.KEY_AGENT_TYPE, Schema._ERR_AGENT_TYPES_MISSING)
+        if len(agent_types) == 0:
+            log_error_and_raise(SchemaError(Schema._ERR_AGENT_TYPES_EMPTY))
         for agent_type_name, agent_definition in agent_types.items():
             agent_type = AgentType.from_dict(agent_type_name, agent_definition)
             schema._agent_types[agent_type_name] = agent_type
 
-        if Schema._KEY_PACKAGES in definitions:
-            schema._packages = JavaPackages.from_dict(definitions[Schema._KEY_PACKAGES])
-        else:
-            log().warning(Schema._WARN_MISSING_PACKAGES)
-            schema._packages = JavaPackages()
+        java_packages = cls._get_or_raise(definitions, Schema.KEY_PACKAGES, Schema._ERR_MISSING_PACKAGES)
+        schema._packages = JavaPackages.from_dict(java_packages)
+
         return schema
 
+    @staticmethod
+    def _get_or_raise(definitions: dict[str, Any], key: str, error_message: str) -> Any:
+        """Get given `key` from given `definitions` - raise error with given `error_message` if not present"""
+        if key not in definitions:
+            log_error_and_raise(SchemaError(error_message))
+        return definitions[key]
+
     @classmethod
     def from_string(cls, definitions: str) -> Schema:
         """Load given string `definitions` into a new Schema"""
@@ -64,7 +67,7 @@ class Schema:
         return repr(self.to_dict())
 
     @property
-    def agent_types(self) -> Dict[str, AgentType]:
+    def agent_types(self) -> dict[str, AgentType]:
         """Returns all the agent types by their name"""
         return self._agent_types