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

fameio/input/metadata.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+from abc import ABC, abstractmethod
+from typing import Any, Optional, final, Union, Final
+
+from fameio.input import InputError
+
+
+class Metadata(ABC):
+    """Hosts metadata of any kind - extend this class to optionally add metadata capability to the extending class"""
+
+    KEY_METADATA: Final[str] = "Metadata".lower()
+
+    def __init__(self, definitions: Optional[Union[Any, dict[str, Any]]] = None):
+        """
+        Initialises the metadata by searching the given definitions' top level for metadata.
+        Alternatively, call `_extract_metadata()` to add metadata later on.
+        If metadata are found on the definitions, they get removed.
+        """
+        self._metadata = self.__extract_metadata(definitions)
+
+    @staticmethod
+    def __extract_metadata(definitions: Optional[dict[str, Any]]) -> dict:
+        """
+        If keyword `metadata` is found on the highest level of given `definitions`, metadata are extracted (removed) and
+        returned, otherwise, an empty dict is returned and definitions are not changed
+        """
+        if definitions and isinstance(definitions, dict):
+            matching_key = [key for key in definitions.keys() if key.lower() == Metadata.KEY_METADATA]
+            return definitions.pop(matching_key[0], {}) if matching_key else {}
+        return {}
+
+    @property
+    def metadata(self) -> dict:
+        """Returns metadata dictionary or an empty dict if no metadata are defined"""
+        return self._metadata
+
+    @final
+    def _extract_metadata(self, definitions: Optional[dict[str, Any]]) -> None:
+        """If keyword `metadata` is found on the highest level of given `definitions`, metadata are removed and set"""
+        self._metadata = self.__extract_metadata(definitions)
+
+    @final
+    def get_metadata_string(self) -> str:
+        """Returns string representation of metadata dictionary or empty string if no metadata are present"""
+        return str(self._metadata) if self.has_metadata() else ""
+
+    @final
+    def has_metadata(self) -> bool:
+        """Returns True if metadata are available"""
+        return bool(self._metadata)
+
+    @final
+    def to_dict(self) -> dict:
+        """Returns a dictionary representation of this item (using its _to_dict method) and adding its metadata"""
+        child_data = self._to_dict()
+        self.__enrich_with_metadata(child_data)
+        return child_data
+
+    @abstractmethod
+    def _to_dict(self) -> dict:
+        """Returns a dictionary representation of this item excluding its metadata"""
+
+    @final
+    def __enrich_with_metadata(self, data: dict) -> dict:
+        """Returns data enriched with metadata field - if any metadata is available"""
+        if self.has_metadata():
+            data[self.KEY_METADATA] = self._metadata
+        return data
+
+
+class MetadataComponent(Metadata):
+    """
+    A component that can contain metadata and may be associated with Objects that have metadata but do not extend
+    Metadata itself, like, e.g., Strings in a list.
+    """
+
+    def __init__(self, additional_definition: Optional[dict] = None) -> None:
+        super().__init__(additional_definition)
+
+    def _to_dict(self) -> dict[str, dict]:
+        return {}
+
+
+class ValueContainer:
+    """A container for values of any type with optional associated metadata"""
+
+    class ParseError(InputError):
+        """An error that occurred while parsing content for metadata-annotated simple values"""
+
+        pass
+
+    _ERR_VALUES_ILL_FORMATTED = "Only Lists and Dictionaries are supported here, but was: {}"
+
+    def __init__(self, definition: Union[dict[str, Any], list[Any]] = None) -> None:
+        """Sets data (and metadata - if any) from given `definition`"""
+        self._values = self._extract_values(definition)
+
+    @staticmethod
+    def _extract_values(definition: Union[dict[str, Any], list[Any]]) -> dict[Any, MetadataComponent]:
+        """Returns value data (and optional metadata) extracted from given `definition`"""
+        if definition is None:
+            return {}
+        elif isinstance(definition, dict):
+            return {key: MetadataComponent(key_definition) for key, key_definition in definition.items()}
+        elif isinstance(definition, list):
+            return {key: MetadataComponent() for key in definition}
+        else:
+            raise ValueContainer.ParseError(ValueContainer._ERR_VALUES_ILL_FORMATTED.format(repr(definition)))
+
+    @property
+    def values(self) -> dict[str, MetadataComponent]:
+        """Returns stored values and each associated MetadataComponent"""
+        return self._values
+
+    def as_list(self) -> list[Any]:
+        """Returns all values as list - excluding any metadata"""
+        return list(self._values.keys())
+
+    def to_dict(self) -> dict[Any, dict[str, dict]]:
+        """
+        Gives all values in dictionary representation
+
+        Returns:
+            If metadata are present they are mapped to each value; values without metadata associate with an empty dict
+        """
+        return {value: component_metadata.to_dict() for value, component_metadata in self._values.items()}
+
+    def has_value(self, to_search) -> bool:
+        """
+        Returns True if given value `to_search` is a key in this ValueContainer
+
+        Args:
+            to_search: value that is searched for in the keys of this ValueContainer
+
+        Returns:
+            True if value is found, False otherwise
+        """
+        return to_search in self._values.keys()
+
+    def is_empty(self) -> bool:
+        """
+        Returns True if no values are stored herein
+
+        Returns:
+            True if no values are stored in this container, False otherwise
+        """
+        return len(self._values) == 0

fameio/input/resolver.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+import glob
+from os import path
+from typing import Optional
+
+
+class PathResolver:
+    """
+    Class responsible for locating files referenced in a scenario.
+
+    Such files can be the ones referenced via the YAML `!include` extension, or simply the data files (time_series)
+    referenced in attributes.
+
+    This class provides a default behaviour that can easily be customized by the caller.
+    """
+
+    # noinspection PyMethodMayBeStatic
+    def resolve_file_pattern(self, root_path: str, file_pattern: str) -> list[str]:
+        """Returns a list of file paths matching the given `file_pattern` in the specified `root_path`"""
+        absolute_path = path.abspath(path.join(root_path, file_pattern))
+        return glob.glob(absolute_path)
+
+    # noinspection PyMethodMayBeStatic
+    def resolve_series_file_path(self, file_name: str) -> Optional[str]:
+        """
+        Searches for the file in the current working directory and returns its absolute file path
+
+        Args:
+            file_name: name of the file that is to be searched
+
+        Returns:
+            absolute path to given file_name if file_name is an absolute path on its own;
+            or relative path to given file_name if the file was found on the current directory;
+            or None if file could not be found
+        """
+        return file_name if path.isabs(file_name) else PathResolver._search_file_in_directory(file_name, path.curdir)
+
+    @staticmethod
+    def _search_file_in_directory(file_name: str, directory: str) -> Optional[str]:
+        """Returns path to said `file_name` relative to specified `directory` if file was found there, None otherwise"""
+        file_path = path.join(directory, file_name)
+        return file_path if path.exists(file_path) else None

fameio/{source → input}/scenario/__init__.py

@@ -5,7 +5,6 @@
 from .agent import Agent
 from .attribute import Attribute
 from .contract import Contract
-from .exception import ScenarioException
-from .fameiofactory import FameIOFactory
 from .generalproperties import GeneralProperties
 from .scenario import Scenario
+from .stringset import StringSet

fameio/{source → input}/scenario/agent.py

@@ -4,24 +4,20 @@
 from __future__ import annotations
 
 import ast
-from typing import Any, Dict, Optional
+from typing import Any, Final
 
-from fameio.source.scenario.attribute import Attribute
-from fameio.source.scenario.exception import (
-    assert_or_raise,
-    get_or_default,
-    get_or_raise,
-)
-from fameio.source.tools import keys_to_lower
+from fameio.input.metadata import Metadata
+from fameio.tools import keys_to_lower
+from .attribute import Attribute
+from .exception import assert_or_raise, get_or_default, get_or_raise
 
 
-class Agent:
+class Agent(Metadata):
     """Contains specifications for an agent in a scenario"""
 
-    _KEY_TYPE = "Type".lower()
-    _KEY_ID = "Id".lower()
-    _KEY_ATTRIBUTES = "Attributes".lower()
-    _KEY_METADATA = "MetaData".lower()
+    KEY_TYPE: Final[str] = "Type".lower()
+    KEY_ID: Final[str] = "Id".lower()
+    KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
 
     _ERR_MISSING_KEY = "Agent requires `key` '{}' but is missing it."
     _ERR_MISSING_TYPE = "Agent requires `type` but is missing it."
@@ -29,28 +25,29 @@ class Agent:
     _ERR_DOUBLE_ATTRIBUTE = "Cannot add attribute '{}' to agent {} because it already exists."
     _ERR_ATTRIBUTE_OVERWRITE = "Agent's attributes are already set and would be overwritten."
 
-    def __init__(self, agent_id: int, type_name: str, meta_data: Optional[Dict] = None) -> None:
+    def __init__(self, agent_id: int, type_name: str, metadata: dict = None) -> None:
         """Constructs a new Agent"""
+        super().__init__({Agent.KEY_METADATA: metadata} if metadata else None)
         assert_or_raise(type(agent_id) is int and agent_id >= 0, self._ERR_MISSING_ID.format(agent_id))
         assert_or_raise(bool(type_name and type_name.strip()), self._ERR_MISSING_TYPE)
         self._id: int = agent_id
         self._type_name: str = type_name.strip()
-        self._attributes: Dict = {}
-        self._meta_data: Optional[Dict] = meta_data if meta_data else {}
+        self._attributes: dict[str, Attribute] = {}
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Agent:
         """Parses an agent from provided `definitions`"""
         definitions = keys_to_lower(definitions)
-        agent_type = get_or_raise(definitions, Agent._KEY_TYPE, Agent._ERR_MISSING_TYPE)
-        agent_id = get_or_raise(definitions, Agent._KEY_ID, Agent._ERR_MISSING_ID)
+        agent_type = get_or_raise(definitions, Agent.KEY_TYPE, Agent._ERR_MISSING_TYPE)
+        agent_id = get_or_raise(definitions, Agent.KEY_ID, Agent._ERR_MISSING_ID)
         agent = cls(agent_id, agent_type)
-        attribute_definitions = get_or_default(definitions, Agent._KEY_ATTRIBUTES, {})
+        agent._extract_metadata(definitions)
+        attribute_definitions = get_or_default(definitions, Agent.KEY_ATTRIBUTES, {})
         agent.init_attributes_from_dict(attribute_definitions)
-        agent._meta_data = get_or_default(definitions, Agent._KEY_METADATA, {})
+        agent._meta_data = get_or_default(definitions, Agent.KEY_METADATA, {})
         return agent
 
-    def init_attributes_from_dict(self, attributes: Dict[str, Any]) -> None:
+    def init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
         """Initialize Agent `attributes` from dict; Must only be called when creating a new Agent"""
         assert_or_raise(not self._attributes, self._ERR_ATTRIBUTE_OVERWRITE)
         self._attributes = {}
@@ -65,17 +62,11 @@ class Agent:
         self._attributes[name] = value
         self._notify_data_changed()
 
-    def to_dict(self) -> dict:
-        """Serializes the Agent content to a dict"""
-        result = {Agent._KEY_TYPE: self.type_name, Agent._KEY_ID: self.id}
-
-        if self.attributes:
-            attributes_dict = {}
-            for attr_name, attr_value in self.attributes.items():
-                attributes_dict[attr_name] = attr_value.generic_content
-            result[self._KEY_ATTRIBUTES] = attributes_dict
-        if self.meta_data:
-            result[self._KEY_METADATA] = self.meta_data
+    def _to_dict(self) -> dict:
+        """Serializes the Agent's content to a dict"""
+        result = {Agent.KEY_TYPE: self.type_name, Agent.KEY_ID: self.id}
+        if self._attributes:
+            result[self.KEY_ATTRIBUTES] = {name: value.to_dict() for name, value in self._attributes.items()}
         return result
 
     def to_string(self) -> str:
@@ -106,11 +97,6 @@ class Agent:
         return self._type_name
 
     @property
-    def attributes(self) -> Dict[str, Attribute]:
+    def attributes(self) -> dict[str, Attribute]:
         """Returns dictionary of all Attributes of this agent"""
         return self._attributes
-
-    @property
-    def meta_data(self) -> dict:
-        """Returns dictionary of all MetaData of this agent"""
-        return self._meta_data

fameio/input/scenario/attribute.py

@@ -0,0 +1,203 @@
+# 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 numbers import Number
+from typing import Any, NamedTuple, Final
+
+from fameio.input.metadata import Metadata, MetadataComponent
+from fameio.tools import keys_to_lower
+from .exception import log_and_raise
+
+
+class Attribute(Metadata):
+    """An Attribute of an agent in a scenario"""
+
+    KEY_VALUE: Final[str] = "Value".lower()
+    KEY_VALUES: Final[str] = "Values".lower()
+
+    NAME_STRING_SEPARATOR: Final[str] = "."
+
+    class __ValueMeta(NamedTuple):
+        """NamedTuple for a primitive value associated with Metadata"""
+
+        value: str | Number
+        meta: MetadataComponent
+
+    class __NestedMeta(NamedTuple):
+        """NamedTuple for a nested value associated with Metadata"""
+
+        value: dict[str, Any]
+        meta: MetadataComponent
+
+    class __DefinitionType(Enum):
+        """Indicates the type of data definition for an Attribute"""
+
+        VALUE = auto()
+        VALUE_LIST = auto()
+        NESTED = auto()
+        NESTED_LIST = auto()
+
+    _ERR_VALUE_MISSING = "Value not specified for Attribute '{}' - leave out if default shall be used (if defined)."
+    _ERR_LIST_EMPTY = "Attribute '{}' was assigned an empty list - please remove attribute or fill empty assignments."
+    _ERR_DICT_EMPTY = "Attribute '{}' was assigned an empty dictionary - please remove or fill empty assignments."
+    _ERR_MIXED_DATA = "Attribute '{}' was assigned a list with mixed complex and simple entries - please fix."
+
+    def __init__(self, name: str, definitions: str | Number | list | dict) -> None:
+        """Parses an Attribute's definition"""
+        self._full_name = name
+        if definitions is None:
+            log_and_raise(Attribute._ERR_VALUE_MISSING.format(name))
+        super().__init__(definitions)
+        data_type = Attribute._get_data_type(name, definitions)
+
+        self._value: str | Number | None = None
+        self._value_list: list[Attribute.__ValueMeta] | None = None
+        self._nested: dict[str, Attribute] | None = None
+        self._nested_list: list[Attribute.__NestedMeta] | None = None
+
+        if data_type is Attribute.__DefinitionType.VALUE:
+            value = keys_to_lower(definitions)[Attribute.KEY_VALUE] if isinstance(definitions, dict) else definitions
+            self._value = value
+        elif data_type is Attribute.__DefinitionType.VALUE_LIST:
+            self._value_list = self._extract_values(definitions)
+        elif data_type is Attribute.__DefinitionType.NESTED:
+            self._nested = Attribute._build_attribute_dict(name, definitions)
+        elif data_type is Attribute.__DefinitionType.NESTED_LIST:
+            self._nested_list = []
+            values = keys_to_lower(definitions)[Attribute.KEY_VALUES] if isinstance(definitions, dict) else definitions
+            for list_index, definition in enumerate(values):
+                list_meta = MetadataComponent(definition)
+                list_extended_name = name + Attribute.NAME_STRING_SEPARATOR + str(list_index)
+                nested_items = Attribute._build_attribute_dict(list_extended_name, definition)
+                self._nested_list.append(Attribute.__NestedMeta(value=nested_items, meta=list_meta))
+
+    @staticmethod
+    def _get_data_type(name: str, definitions: Any) -> Attribute.__DefinitionType:
+        """Returns type of data derived from given `definitions`"""
+        if isinstance(definitions, list):
+            if len(definitions) == 0:
+                log_and_raise(Attribute._ERR_LIST_EMPTY.format(name))
+            return Attribute._get_data_type_list(definitions)
+        elif isinstance(definitions, dict):
+            if len(definitions) == 0:
+                log_and_raise(Attribute._ERR_DICT_EMPTY.format(name))
+            return Attribute._get_data_type_dict(definitions)
+        else:
+            return Attribute.__DefinitionType.VALUE
+
+    @staticmethod
+    def _get_data_type_list(definitions: list[Any]) -> Attribute.__DefinitionType:
+        """Returns type of data from a given non-empty list `definitions`"""
+        if all([Attribute._is_value_definition(entry) for entry in definitions]):
+            return Attribute.__DefinitionType.VALUE_LIST
+        elif Attribute._is_list_of_dict(definitions):
+            return Attribute.__DefinitionType.NESTED_LIST
+        log_and_raise(Attribute._ERR_MIXED_DATA.format(repr(definitions)))
+
+    @staticmethod
+    def _is_list_of_dict(definitions: list) -> bool:
+        """Returns True if given `definitions` is a list of (only) dict"""
+        return all([isinstance(entry, dict) for entry in definitions])
+
+    @staticmethod
+    def _get_data_type_dict(definitions: dict[str, Any]) -> Attribute.__DefinitionType:
+        """Returns type of data from a given non-empty dict `definitions`"""
+        low_keys = keys_to_lower(definitions)
+        if Attribute.KEY_VALUE in low_keys.keys():
+            return Attribute.__DefinitionType.VALUE
+        elif Attribute.KEY_VALUES in low_keys.keys():
+            values = low_keys[Attribute.KEY_VALUES]
+            if all([Attribute._is_value_definition(entry) for entry in values]):
+                return Attribute.__DefinitionType.VALUE_LIST
+            elif Attribute._is_list_of_dict(values):
+                return Attribute.__DefinitionType.NESTED_LIST
+            log_and_raise(Attribute._ERR_MIXED_DATA.format(repr(values)))
+        return Attribute.__DefinitionType.NESTED
+
+    @staticmethod
+    def _is_value_definition(definition: Any) -> bool:
+        """Returns True if given `definition` is either a dict with a key `Value` or a simple value"""
+        if isinstance(definition, dict):
+            return Attribute.KEY_VALUE in keys_to_lower(definition).keys()
+        return isinstance(definition, (str, Number))
+
+    @staticmethod
+    def _extract_value(definition: str | Number | dict[str, Any]) -> Attribute.__ValueMeta:
+        """Creates a ValueMeta Tuple associating a Value with its optional metadata"""
+        if isinstance(definition, dict):
+            return Attribute.__ValueMeta(
+                value=keys_to_lower(definition)[Attribute.KEY_VALUE], meta=MetadataComponent(definition)
+            )
+        return Attribute.__ValueMeta(value=definition, meta=MetadataComponent())
+
+    @staticmethod
+    def _extract_values(definition: list | dict) -> list[Attribute.__ValueMeta]:
+        """Creates a list of ValueMeta Tuples, each associating a value with optional metadata"""
+        values = keys_to_lower(definition)[Attribute.KEY_VALUES] if isinstance(definition, dict) else definition
+        return [Attribute._extract_value(entry) for entry in values]
+
+    @staticmethod
+    def _build_attribute_dict(name: str, definitions: dict[str, Any]) -> dict[str, Attribute]:
+        """Returns a new dictionary containing Attributes generated from given `definitions`"""
+        inner_elements = {}
+        for nested_name, value in definitions.items():
+            full_name = name + Attribute.NAME_STRING_SEPARATOR + nested_name
+            inner_elements[nested_name] = Attribute(full_name, value)
+        return inner_elements
+
+    @property
+    def has_value(self) -> bool:
+        """Returns True if Attribute has any value assigned"""
+        return self._value is not None or self._value_list is not None
+
+    @property
+    def value(self) -> str | Number | list[str | Number] | None:
+        """Returns value or list of values if available on this Attribute (ignoring any Metadata), else None"""
+        if self._value is not None:
+            return self._value
+        elif self._value_list is not None:
+            return [item.value for item in self._value_list]
+        return None
+
+    @property
+    def has_nested(self) -> bool:
+        """Returns True if nested Attributes are present, False otherwise; also returns False for nested lists"""
+        return self._nested is not None
+
+    @property
+    def nested(self) -> dict[str, Attribute]:
+        """Returns dictionary of all nested Attributes if nested Attributes are present, else None"""
+        return self._nested if self.has_nested else None
+
+    @property
+    def has_nested_list(self) -> bool:
+        """Returns True if list of nested items is present"""
+        return self._nested_list is not None
+
+    @property
+    def nested_list(self) -> list[dict[str, Attribute]]:
+        """Return list of all nested Attribute dictionaries if such are present, else None"""
+        return [entry.value for entry in self._nested_list] if self.has_nested_list else None
+
+    def __repr__(self) -> str:
+        return self._full_name
+
+    def _to_dict(self) -> dict[str, Any]:
+        if self._value is not None:
+            return {self.KEY_VALUE: self._value}
+        elif self._value_list is not None:
+            return {
+                self.KEY_VALUES: [{self.KEY_VALUE: entry.value, **entry.meta.to_dict()} for entry in self._value_list]
+            }
+        elif self._nested is not None:
+            return {name: attribute.to_dict() for name, attribute in self.nested.items()}
+        elif self._nested_list is not None:
+            return {
+                self.KEY_VALUES: [
+                    {**{name: attribute.to_dict() for name, attribute in entry.value.items()}, **entry.meta.to_dict()}
+                    for entry in self._nested_list
+                ]
+            }