fameio 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

fameio/input/metadata.py

@@ -11,13 +11,14 @@ from fameio.logs import log_error
 
 
 class Metadata(ABC):
-    """Hosts metadata of any kind - extend this class to optionally add metadata capability to the extending class"""
+    """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: Any | dict[str, Any] | None = None):
-        """
-        Initialises the metadata by searching the given definitions' top level for metadata.
+        """Initialises the metadata.
+
+        Search 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.
         """
@@ -25,9 +26,10 @@ class Metadata(ABC):
 
     @staticmethod
     def __extract_metadata(definitions: dict[str, Any] | None) -> dict:
-        """
+        """Extract metadata from `definitions` - if present.
+
         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
+        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]
@@ -36,47 +38,47 @@ class Metadata(ABC):
 
     @property
     def metadata(self) -> dict:
-        """Returns metadata dictionary or an empty dict if no metadata are defined"""
+        """Returns metadata dictionary or an empty dict if no metadata are defined."""
         return self._metadata
 
     @final
     def _extract_metadata(self, definitions: dict[str, Any] | None) -> None:
-        """If keyword `metadata` is found on the highest level of given `definitions`, metadata are removed and set"""
+        """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"""
+        """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"""
+        """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"""
+        """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"""
+        """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"""
+        """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.
+    """A component that can contain metadata and may be associated with other Objects.
+
+    This can be attached to objects that cannot be derived from the Metadata class themselves.
     """
 
     def __init__(self, additional_definition: dict | None = None) -> None:
@@ -87,16 +89,15 @@ class MetadataComponent(Metadata):
 
 
 class ValueContainer:
-    """A container for values of any type with optional associated metadata"""
+    """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"""
+        """An error that occurred while parsing content for metadata-annotated simple values."""
 
     _ERR_VALUES_ILL_FORMATTED = "Only Lists or Dictionaries are supported for value definitions, but was: {}"
 
     def __init__(self, definition: dict[str, Any] | list | None = None) -> None:
-        """
-        Sets data (and metadata - if any) from given `definition`
+        """Sets data (and metadata - if any) from given `definition`.
 
         Args:
             definition: dictionary representation of value(s) with potential associated metadata
@@ -108,8 +109,7 @@ class ValueContainer:
 
     @staticmethod
     def _extract_values(definition: dict[str, Any] | list | None) -> dict[Any, MetadataComponent]:
-        """
-        Returns value data (and optional metadata) extracted from given `definition`
+        """Returns value data (and optional metadata) extracted from given `definition`.
 
         Args:
             definition: dictionary representation of value with potential associated metadata
@@ -130,16 +130,15 @@ class ValueContainer:
 
     @property
     def values(self) -> dict[str, MetadataComponent]:
-        """Returns stored values and each associated 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"""
+        """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
+        """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
@@ -147,8 +146,7 @@ class ValueContainer:
         return {value: component_metadata.to_dict() for value, component_metadata in self._values.items()}
 
     def has_value(self, to_search: Any) -> bool:
-        """
-        Returns True if given value `to_search` is a key in this ValueContainer
+        """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
@@ -159,8 +157,7 @@ class ValueContainer:
         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 herein.
 
         Returns:
             True if no values are stored in this container, False otherwise

fameio/input/resolver.py

@@ -8,8 +8,7 @@ from os import path
 
 
 class PathResolver:
-    """
-    Class responsible for locating files referenced in a scenario.
+    """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.
@@ -19,14 +18,13 @@ class PathResolver:
 
     # 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`"""
+        """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) -> str | None:
-        """
-        Searches for the file in the current working directory and returns its absolute file path
+        """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
@@ -40,6 +38,6 @@ class PathResolver:
 
     @staticmethod
     def _search_file_in_directory(file_name: str, directory: str) -> str | None:
-        """Returns path to said `file_name` relative to specified `directory` if file was found there, None otherwise"""
+        """Returns path to `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/input/scenario/agent.py

@@ -14,7 +14,7 @@ from .exception import assert_or_raise, get_or_raise
 
 
 class Agent(Metadata):
-    """Contains specifications for an agent in a scenario"""
+    """Contains specifications for an agent in a scenario."""
 
     KEY_TYPE: Final[str] = "Type".lower()
     KEY_ID: Final[str] = "Id".lower()
@@ -30,7 +30,7 @@ class Agent(Metadata):
     _WARN_UNEXPECTED_KEY = "Ignoring unexpected key(s) {} in top level of agent with id: {}"
 
     def __init__(self, agent_id: int, type_name: str, metadata: dict | None = None) -> None:
-        """Constructs a new Agent"""
+        """Constructs a new Agent."""
         super().__init__({Agent.KEY_METADATA: metadata} if metadata else None)
         assert_or_raise(isinstance(agent_id, int) and agent_id >= 0, self._ERR_ILLEGAL_ID.format(agent_id))
         assert_or_raise(bool(type_name and type_name.strip()), self._ERR_TYPE_EMPTY)
@@ -40,12 +40,13 @@ class Agent(Metadata):
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Agent:
-        """
+        """Create new Agent from given `definitions`
+
         Args:
             definitions: dictionary representation of an agent
 
         Returns:
-            new agent
+            new agent created from `definitions`
 
         Raises:
             ScenarioError: if definitions are incomplete or erroneous, logged on level "ERROR"
@@ -61,8 +62,8 @@ class Agent(Metadata):
 
     @staticmethod
     def validate_keys(data: dict, agent_id: int) -> None:
-        """
-        Logs a warning if any unexpected keys are presented at top level of `data`
+        """Logs a warning if any unexpected keys are presented at top level of `data`.
+
         Expected keys are defined in `Agent.RESERVED_KEYS`
 
         Args:
@@ -74,8 +75,9 @@ class Agent(Metadata):
             log().warning(Agent._WARN_UNEXPECTED_KEY.format(unexpected_keys, agent_id))
 
     def init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
-        """
-        Initialise agent `attributes` from dict; Must only be called when creating a new Agent
+        """Initialise agent `attributes` from dict.
+
+        Must only be called when creating a new Agent.
 
         Args:
             attributes: to be set
@@ -90,21 +92,21 @@ class Agent(Metadata):
             self.add_attribute(name, Attribute(full_name, value))
 
     def add_attribute(self, name: str, value: Attribute) -> None:
-        """Adds a new attribute to the Agent (raise an error if it already exists)"""
+        """Adds a new attribute to the Agent (raise an error if it already exists)."""
         if name in self._attributes:
             raise ValueError(self._ERR_DOUBLE_ATTRIBUTE.format(name, self.display_id))
         self._attributes[name] = value
         self._notify_data_changed()
 
     def _to_dict(self) -> dict:
-        """Serializes the Agent's content to a 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:
-        """Serializes this agent to a string"""
+        """Serializes this agent to a string."""
         return repr(self.to_dict())
 
     @classmethod
@@ -112,24 +114,24 @@ class Agent(Metadata):
         return cls.from_dict(ast.literal_eval(definitions))
 
     def _notify_data_changed(self):
-        """Placeholder method used to signal data changes to derived types"""
+        """Placeholder method used to signal data changes to derived types."""
 
     @property
     def id(self) -> int:
-        """Returns the ID of the Agent"""
+        """Returns the ID of the Agent."""
         return self._id
 
     @property
     def display_id(self) -> str:
-        """Returns the ID of the Agent as a string for display purposes"""
+        """Returns the ID of the Agent as a string for display purposes."""
         return f"#{self._id}"
 
     @property
     def type_name(self) -> str:
-        """Returns the name of the Agent type"""
+        """Returns the name of the Agent type."""
         return self._type_name
 
     @property
     def attributes(self) -> dict[str, Attribute]:
-        """Returns dictionary of all Attributes of this agent"""
+        """Returns dictionary of all Attributes of this agent."""
         return self._attributes

fameio/input/scenario/attribute.py

@@ -10,10 +10,11 @@ from typing import Any, NamedTuple, Final
 from fameio.input.metadata import Metadata, MetadataComponent
 from fameio.tools import keys_to_lower
 from .exception import log_scenario_error
+from ...logs import log_error
 
 
 class Attribute(Metadata):
-    """An Attribute of an agent in a scenario"""
+    """An Attribute of an agent in a scenario."""
 
     KEY_VALUE: Final[str] = "Value".lower()
     KEY_VALUES: Final[str] = "Values".lower()
@@ -21,37 +22,49 @@ class Attribute(Metadata):
     NAME_STRING_SEPARATOR: Final[str] = "."
 
     class __ValueMeta(NamedTuple):
-        """NamedTuple for a primitive value associated with Metadata"""
+        """NamedTuple for a primitive value associated with Metadata."""
 
         value: str | Number
         meta: MetadataComponent
 
     class __NestedMeta(NamedTuple):
-        """NamedTuple for a nested value associated with Metadata"""
+        """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"""
+        """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."
+    _ERR_CREATION = "Found error in specification of Attribute '{}'."
+    _ERR_VALUE_MISSING = "Value not specified for Attribute '{}' - leave this Attribute out or specify a value."
+    _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"""
+        """Creates a new Attribute.
+
+        Args:
+            name: full name of the Attribute including the parent Attribute(s) names
+            definitions: of this Attribute including its inner elements, if any
+
+        Raises:
+            ScenarioError: if this Attribute or its inner elements could not be created, logged with level "ERROR"
+        """
         self._full_name = name
         if definitions is None:
             raise log_scenario_error(Attribute._ERR_VALUE_MISSING.format(name))
         super().__init__(definitions)
-        data_type = Attribute._get_data_type(name, definitions)
+        try:
+            data_type = Attribute._get_data_type(definitions)
+        except ValueError as e:
+            raise log_scenario_error(Attribute._ERR_CREATION.format(name)) from e
 
         self._value: str | Number | None = None
         self._value_list: list[Attribute.__ValueMeta] | None = None
@@ -74,35 +87,65 @@ class Attribute(Metadata):
                 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`"""
+    def _get_data_type(definitions: Any) -> Attribute.__DefinitionType:
+        """Returns type of data derived from given `definitions`.
+
+        Args:
+            definitions: to deduct the data type from
+
+        Returns:
+            data type derived from given definitions
+
+        Raises:
+            ValueError: if definitions are empty or could not be derived, logged with level "ERROR"
+        """
         if isinstance(definitions, list):
             if len(definitions) == 0:
-                raise log_scenario_error(Attribute._ERR_LIST_EMPTY.format(name))
+                raise log_error(ValueError(Attribute._ERR_LIST_EMPTY))
             return Attribute._get_data_type_list(definitions)
         if isinstance(definitions, dict):
             if len(definitions) == 0:
-                raise log_scenario_error(Attribute._ERR_DICT_EMPTY.format(name))
+                raise log_error(ValueError(Attribute._ERR_DICT_EMPTY))
             return Attribute._get_data_type_dict(definitions)
         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`"""
+        """Returns type of data from a given non-empty list `definitions`.
+
+        Args:
+            definitions: list of data to derive data type from
+
+        Returns:
+            data type of data list
+
+        Raises:
+            ValueError: if definitions represent a mix of simple and complex entries, logged with level "ERROR"
+        """
         if all(Attribute._is_value_definition(entry) for entry in definitions):
             return Attribute.__DefinitionType.VALUE_LIST
         if Attribute._is_list_of_dict(definitions):
             return Attribute.__DefinitionType.NESTED_LIST
-        raise log_scenario_error(Attribute._ERR_MIXED_DATA.format(repr(definitions)))
+        raise log_error(ValueError(Attribute._ERR_MIXED_DATA))
 
     @staticmethod
     def _is_list_of_dict(definitions: list) -> bool:
-        """Returns True if given `definitions` is a list of (only) dict"""
+        """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`"""
+        """Returns type of data from a given non-empty dict `definitions`.
+
+        Args:
+            definitions: to derive the data type from
+
+        Returns:
+            data type derived from given `definitions`
+
+        Raises:
+            ValueError: if definitions represent a mix of simple and complex entries, logged with level "ERROR"
+        """
         low_keys = keys_to_lower(definitions)
         if Attribute.KEY_VALUE in low_keys.keys():
             return Attribute.__DefinitionType.VALUE
@@ -112,19 +155,19 @@ class Attribute(Metadata):
                 return Attribute.__DefinitionType.VALUE_LIST
             if Attribute._is_list_of_dict(values):
                 return Attribute.__DefinitionType.NESTED_LIST
-            raise log_scenario_error(Attribute._ERR_MIXED_DATA.format(repr(values)))
+            raise log_error(ValueError(Attribute._ERR_MIXED_DATA))
         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"""
+        """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"""
+        """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)
@@ -133,27 +176,38 @@ class Attribute(Metadata):
 
     @staticmethod
     def _extract_values(definition: list | dict) -> list[Attribute.__ValueMeta]:
-        """Creates a list of ValueMeta Tuples, each associating a value with optional metadata"""
+        """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`"""
+    def _build_attribute_dict(parent_name: str, definitions: dict[str, Any]) -> dict[str, Attribute]:
+        """Returns a new dictionary containing Attributes generated from given `definitions`.
+
+        Args:
+            parent_name: name of parent element
+            definitions: of the Attributes
+
+        Returns:
+            dictionary of Attributes created from given definitions
+
+        Raises:
+            ScenarioError: if any of the Attributes could not be created, logged with level "ERROR"
+        """
         inner_elements = {}
         for nested_name, value in definitions.items():
-            full_name = name + Attribute.NAME_STRING_SEPARATOR + nested_name
+            full_name = parent_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"""
+        """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"""
+        """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
         if self._value_list is not None:
@@ -162,22 +216,22 @@ class Attribute(Metadata):
 
     @property
     def has_nested(self) -> bool:
-        """Returns True if nested Attributes are present, False otherwise; also returns False for nested lists"""
+        """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 empty dict"""
+        """Returns dictionary of all nested Attributes if nested Attributes are present, else empty dict."""
         return self._nested if self._nested is not None else {}
 
     @property
     def has_nested_list(self) -> bool:
-        """Returns True if list of nested items is present"""
+        """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 an empty list"""
+        """Return list of all nested Attribute dictionaries if such are present, else an empty list."""
         return [entry.value for entry in self._nested_list] if self._nested_list is not None else []
 
     def __repr__(self) -> str: