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

fameio/input/scenario/contract.py

@@ -10,20 +10,21 @@ from fameio.input.metadata import Metadata
 from fameio.input.scenario.attribute import Attribute
 from fameio.logs import log, log_error
 from fameio.time import FameTime, ConversionError
-from fameio.tools import ensure_is_list, keys_to_lower
+from fameio.tools import keys_to_lower
 
 
 class Contract(Metadata):
-    """Contract between two Agents of a scenario"""
+    """Contract between two Agents of a scenario."""
 
     class ContractError(InputError):
-        """An error that occurred while parsing Contract definitions"""
+        """An error that occurred while parsing Contract definitions."""
 
     KEY_SENDER: Final[str] = "SenderId".lower()
     KEY_RECEIVER: Final[str] = "ReceiverId".lower()
     KEY_PRODUCT: Final[str] = "ProductName".lower()
     KEY_FIRST_DELIVERY: Final[str] = "FirstDeliveryTime".lower()
     KEY_INTERVAL: Final[str] = "DeliveryIntervalInSteps".lower()
+    KEY_EVERY: Final[str] = "Every".lower()
     KEY_EXPIRE: Final[str] = "ExpirationTime".lower()
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
 
@@ -33,7 +34,8 @@ class Contract(Metadata):
         "or N-to-N sender-to-receiver numbers. Found M-to-N pairing in Contract with "
         "Senders: {} and Receivers: {}."
     )
-    _ERR_INTERVAL_NOT_POSITIVE = "Contract delivery interval must be a positive integer but was: {}"
+    _ERR_XOR_KEYS = "Contract expects exactly one of the keys '{}' or '{}'. Found either both or none."
+    _ERR_INTERVAL_INVALID = "Contract delivery interval must be a positive integer but was: {}"
     _ERR_SENDER_IS_RECEIVER = "Contract sender and receiver have the same id: {}"
     _ERR_DOUBLE_ATTRIBUTE = "Cannot add attribute '{}' to contract because it already exists."
     _ERR_TIME_CONVERSION = "Contract item '{}' is an ill-formatted time: '{}'"
@@ -50,8 +52,7 @@ class Contract(Metadata):
         expiration_time: int | None = None,
         metadata: dict | None = None,
     ) -> None:
-        """
-        Constructs a new Contract
+        """Constructs a new Contract.
 
         Args:
             sender_id: unique id of sender
@@ -74,7 +75,7 @@ class Contract(Metadata):
         if sender_id == receiver_id:
             log().warning(self._ERR_SENDER_IS_RECEIVER.format(sender_id))
         if delivery_interval <= 0:
-            raise log_error(self.ContractError(self._ERR_INTERVAL_NOT_POSITIVE.format(delivery_interval)))
+            raise log_error(self.ContractError(self._ERR_INTERVAL_INVALID.format(delivery_interval)))
         self._sender_id = sender_id
         self._receiver_id = receiver_id
         self._product_name = product_name
@@ -84,56 +85,55 @@ class Contract(Metadata):
         self._attributes: dict = {}
 
     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 product_name(self) -> str:
-        """Returns the product name of the contract"""
+        """Returns the product name of the contract."""
         return self._product_name
 
     @property
     def sender_id(self) -> int:
-        """Returns the sender ID of the contract"""
+        """Returns the sender ID of the contract."""
         return self._sender_id
 
     @property
     def display_sender_id(self) -> str:
-        """Returns the sender ID of the contract as a string for display purposes"""
+        """Returns the sender ID of the contract as a string for display purposes."""
         return f"#{self._sender_id}"
 
     @property
     def receiver_id(self) -> int:
-        """Returns the receiver ID of the contract"""
+        """Returns the receiver ID of the contract."""
         return self._receiver_id
 
     @property
     def display_receiver_id(self) -> str:
-        """Returns the receiver ID of the contract as a string for display purposes"""
+        """Returns the receiver ID of the contract as a string for display purposes."""
         return f"#{self._receiver_id}"
 
     @property
     def delivery_interval(self) -> int:
-        """Returns the delivery interval of the contract (in steps)"""
+        """Returns the delivery interval of the contract (in steps)."""
         return self._delivery_interval
 
     @property
     def first_delivery_time(self) -> int:
-        """Returns the first delivery time of the contract"""
+        """Returns the first delivery time of the contract."""
         return self._first_delivery_time
 
     @property
     def expiration_time(self) -> int | None:
-        """Returns the expiration time of the contract if available, None otherwise"""
+        """Returns the expiration time of the contract if available, None otherwise."""
         return self._expiration_time
 
     @property
     def attributes(self) -> dict[str, Attribute]:
-        """Returns dictionary of all Attributes of the contract"""
+        """Returns dictionary of all Attributes of the contract."""
         return self._attributes
 
     def add_attribute(self, name: str, value: Attribute) -> None:
-        """
-        Adds a new attribute to the Contract
+        """Adds a new attribute to the Contract.
 
         Args:
             name: of the attribute
@@ -149,8 +149,7 @@ class Contract(Metadata):
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Contract:
-        """
-        Parses contract from given `definitions`
+        """Parses contract from given `definitions`.
 
         Args:
             definitions: dictionary representation of a contract
@@ -167,7 +166,7 @@ class Contract(Metadata):
         product_name = Contract._get_or_raise(definitions, Contract.KEY_PRODUCT, Contract._ERR_MISSING_KEY)
 
         first_delivery_time = Contract._get_time(definitions, Contract.KEY_FIRST_DELIVERY)
-        delivery_interval = Contract._get_or_raise(definitions, Contract.KEY_INTERVAL, Contract._ERR_MISSING_KEY)
+        delivery_interval = Contract._get_interval(definitions)
         expiration_time = Contract._get_time(definitions, Contract.KEY_EXPIRE, mandatory=False)
 
         contract = cls(sender_id, receiver_id, product_name, delivery_interval, first_delivery_time, expiration_time)
@@ -177,8 +176,7 @@ class Contract(Metadata):
 
     @staticmethod
     def _get_or_raise(dictionary: dict, key: str, error_message: str) -> Any:
-        """
-        Returns value associated with `key` in given `dictionary`, or raises exception if key or value is missing
+        """Returns value associated with `key` in given `dictionary`, or raises exception if key or value is missing.
 
         Args:
             dictionary: to search the key in
@@ -205,8 +203,7 @@ class Contract(Metadata):
 
     @staticmethod
     def _get_time(definitions: dict, key: str, mandatory: bool = True) -> int | None:
-        """
-        Extract time representation value at given key, and, if present, convert to integer, else return None
+        """Extract time representation value at given key, and, if present, convert to integer, else return None.
 
         Args:
             definitions: to search given key in
@@ -229,9 +226,45 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MISSING_KEY.format(key)))
         return None
 
-    def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
+    @staticmethod
+    def _get_interval(definitions: dict) -> int:
+        """Extract delivery interval from Contract definition, or raise an error if not present or ill formatted.
+
+        Args:
+            definitions: to extract the delivery interval from
+
+        Returns:
+            the delivery interval in fame time steps
+
+        Raises:
+            ContractError: if delivery interval is not defined or invalid, logged with level "ERROR"
         """
-        Resets Contract `attributes` from dict
+        has_interval = Contract.KEY_INTERVAL in definitions
+        has_every = Contract.KEY_EVERY in definitions
+
+        if has_interval and not has_every:
+            value = definitions[Contract.KEY_INTERVAL]
+            if isinstance(value, int):
+                return value
+            raise log_error(Contract.ContractError(Contract._ERR_INTERVAL_INVALID.format(value)))
+        if has_every and not has_interval:
+            value = definitions[Contract.KEY_EVERY]
+            if isinstance(value, int):
+                return value
+            if isinstance(value, str):
+                try:
+                    return FameTime.convert_text_to_time_span(value)
+                except ConversionError as e:
+                    raise log_error(
+                        Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value))
+                    ) from e
+            raise log_error(Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value)))
+        raise log_error(
+            Contract.ContractError(Contract._ERR_XOR_KEYS.format(Contract.KEY_INTERVAL, Contract.KEY_EVERY))
+        )
+
+    def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
+        """Resets Contract `attributes` from dict.
 
         Args:
             attributes: key-value pairs of attributes to be set
@@ -244,7 +277,7 @@ class Contract(Metadata):
             self.add_attribute(name, Attribute(full_name, value))
 
     def _to_dict(self) -> dict:
-        """Serializes the Contract content to a dict"""
+        """Serializes the Contract content to a dict."""
         result = {
             self.KEY_SENDER: self.sender_id,
             self.KEY_RECEIVER: self.receiver_id,
@@ -262,9 +295,10 @@ class Contract(Metadata):
 
     @staticmethod
     def split_contract_definitions(multi_definition: dict) -> list[dict]:
-        """
+        """Split given M:N `multi_definition` of contracts to multiple 1:1 contracts.
+
         Splits given dictionary of contracts with potentially more than ore sender and/or receiver into a list
-        of individual contract definitions with one sender and one receiver
+        of individual contract definitions with one sender and one receiver.
 
         Args:
             multi_definition: contract definitions with potentially more than ore sender and/or receiver
@@ -285,15 +319,14 @@ class Contract(Metadata):
             Contract.KEY_EXPIRE,
             Contract.KEY_METADATA,
             Contract.KEY_ATTRIBUTES,
+            Contract.KEY_EVERY,
         ]:
             if key in multi_definition:
                 base_data[key] = multi_definition[key]
-        senders = ensure_is_list(
-            Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
-        )
-        receivers = ensure_is_list(
-            Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
-        )
+        sender_value = Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
+        senders = Contract._unpack_list(sender_value)
+        receiver_value = Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
+        receivers = Contract._unpack_list(receiver_value)
         if len(senders) > 1 and len(receivers) == 1:
             for index, sender in enumerate(senders):
                 contracts.append(Contract._copy_contract(sender, receivers[0], base_data))
@@ -307,9 +340,16 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MULTI_CONTRACT_CORRUPT.format(senders, receivers)))
         return contracts
 
+    @staticmethod
+    def _unpack_list(obj: Any | list) -> list[Any]:
+        """Returns the given value as a flat list - unpacks potential nested list(s)"""
+        if isinstance(obj, list):
+            return [item for element in obj for item in Contract._unpack_list(element)]
+        return [obj]
+
     @staticmethod
     def _copy_contract(sender: int, receiver: int, base_data: dict) -> dict:
-        """Returns a new contract definition dictionary, with given `sender` and `receiver` and copied `base_data`"""
+        """Returns a new contract definition dictionary, with given `sender` and `receiver` and copied `base_data`."""
         contract = {
             Contract.KEY_SENDER: sender,
             Contract.KEY_RECEIVER: receiver,

fameio/input/scenario/exception.py

@@ -12,8 +12,7 @@ _DEFAULT_USED = "Using default value '{}' for missing key '{}'"
 
 
 def log_scenario_error(message: str) -> ScenarioError:
-    """
-    Creates exception with given `message`, logs it on level "Error" and returns it
+    """Creates exception with given `message`, logs it on level "Error" and returns it.
 
     Args:
         message: to be logged and included in the exception if key is missing
@@ -27,8 +26,7 @@ def log_scenario_error(message: str) -> ScenarioError:
 
 
 def get_or_raise(dictionary: dict, key: str, error_message: str) -> Any:
-    """
-    Returns value associated with `key` in given `dictionary`, or raises exception if key or value is missing
+    """Returns value associated with `key` in given `dictionary`, or raises exception if key or value is missing.
 
     Args:
         dictionary: to search the key in
@@ -47,8 +45,7 @@ def get_or_raise(dictionary: dict, key: str, error_message: str) -> Any:
 
 
 def assert_or_raise(assertion: bool, error_message: str) -> None:
-    """
-    Raises exception with given `msg` if `assertion` is False
+    """Raises exception with given `error_message` if `assertion` is False.
 
     Args:
         assertion: expression that must be True, else an exception is raised

fameio/input/scenario/fameiofactory.py

@@ -9,15 +9,14 @@ from .stringset import StringSet
 
 
 class FameIOFactory:
-    """
-    Factory used to instantiate the types defined in a scenario file.
+    """Factory used to instantiate the types defined in a scenario file.
+
     This allows a client to subclass some types in order to extend what a scenario can contain.
     """
 
     @staticmethod
     def new_schema_from_dict(definitions: dict) -> Schema:
-        """
-        Load given dictionary `definitions` into a new schema
+        """Loads given dictionary `definitions` into a new schema.
 
         Args:
             definitions: dictionary representation of schema
@@ -32,8 +31,7 @@ class FameIOFactory:
 
     @staticmethod
     def new_general_properties_from_dict(definitions: dict) -> GeneralProperties:
-        """
-        Parse general properties from provided `definitions`
+        """Parses general properties from provided `definitions`.
 
         Args:
             definitions: dictionary representation of general properties
@@ -48,8 +46,7 @@ class FameIOFactory:
 
     @staticmethod
     def new_agent_from_dict(definitions: dict) -> Agent:
-        """
-        Parses an agent from provided `definitions`
+        """Parses an agent from provided `definitions`.
 
         Args:
             definitions: dictionary representation of an agent
@@ -64,8 +61,7 @@ class FameIOFactory:
 
     @staticmethod
     def new_contract_from_dict(definitions: dict) -> Contract:
-        """
-        Parses contract from given `definitions`
+        """Parses contract from given `definitions`.
 
         Args:
             definitions: dictionary representation of a contract
@@ -80,8 +76,7 @@ class FameIOFactory:
 
     @staticmethod
     def new_string_set_from_dict(definition: StringSet.StringSetType) -> StringSet:
-        """
-        Returns string set initialised from `definition`
+        """Returns string set initialised from `definition`.
 
         Args:
             definition: dictionary representation of string set

fameio/input/scenario/generalproperties.py

@@ -12,7 +12,7 @@ from .exception import get_or_raise
 
 
 class GeneralProperties:
-    """Hosts general properties of a scenario"""
+    """Hosts general properties of a scenario."""
 
     KEY_RUN: Final[str] = "RunId".lower()
     KEY_SIMULATION = "Simulation".lower()
@@ -39,8 +39,7 @@ class GeneralProperties:
 
     @classmethod
     def from_dict(cls, definitions: dict) -> GeneralProperties:
-        """
-        Parse general properties from provided `definitions`
+        """Parses general properties from provided `definitions`.
 
         Args:
             definitions: dictionary representation of general properties
@@ -79,7 +78,7 @@ class GeneralProperties:
         return cls(run_id, start_time, stop_time, random_seed)
 
     def to_dict(self) -> dict:
-        """Serializes the general properties to a dict"""
+        """Serializes the general properties to a dict."""
         result: dict = {self.KEY_RUN: self._run_id}
         simulation_dict = {
             self.KEY_START: self.simulation_start_time,
@@ -91,20 +90,20 @@ class GeneralProperties:
 
     @property
     def run_id(self) -> int:
-        """Returns the run ID"""
+        """Returns the run ID."""
         return self._run_id
 
     @property
     def simulation_start_time(self) -> int:
-        """Returns the simulation start time"""
+        """Returns the simulation start time."""
         return self._simulation_start_time
 
     @property
     def simulation_stop_time(self) -> int:
-        """Returns the simulation stop time"""
+        """Returns the simulation stop time."""
         return self._simulation_stop_time
 
     @property
     def simulation_random_seed(self) -> int:
-        """Returns the simulation random seed"""
+        """Returns the simulation random seed."""
         return self._simulation_random_seed

fameio/input/scenario/scenario.py

@@ -18,7 +18,7 @@ from fameio.tools import keys_to_lower
 
 
 class Scenario(Metadata):
-    """Definition of a scenario"""
+    """Definition of a scenario."""
 
     KEY_SCHEMA: Final[str] = "Schema".lower()
     KEY_GENERAL: Final[str] = "GeneralProperties".lower()
@@ -42,8 +42,7 @@ class Scenario(Metadata):
 
     @classmethod
     def from_dict(cls, definitions: dict, factory: FameIOFactory = FameIOFactory()) -> Scenario:
-        """
-        Parse scenario from provided `definitions` using given `factory`
+        """Parses scenario from provided `definitions` using given `factory`.
 
         Args:
             definitions: dictionary representation of scenario
@@ -73,8 +72,7 @@ class Scenario(Metadata):
 
     @staticmethod
     def _extract_schema(definitions: dict, factory: FameIOFactory) -> Schema:
-        """
-        Extract schema from given definitions and create Schema from it
+        """Extracts schema from given definitions and creates Schema from it.
 
         Args:
             definitions: dictionary representation of scenario
@@ -94,8 +92,7 @@ class Scenario(Metadata):
 
     @staticmethod
     def _extract_string_sets(definitions: dict, factory: FameIOFactory) -> dict[str, StringSet]:
-        """
-        Extract string sets from given definitions and create dictionary from it
+        """Extracts string sets from given definitions and creates dictionary from it.
 
         Args:
             definitions: dictionary representation of scenario
@@ -117,8 +114,7 @@ class Scenario(Metadata):
 
     @staticmethod
     def _extract_contracts(definitions: dict, factory: FameIOFactory) -> list[Contract]:
-        """
-        Extract contracts from given definitions
+        """Extracts contracts from given definitions.
 
         Args:
             definitions: dictionary representation of scenario
@@ -143,7 +139,7 @@ class Scenario(Metadata):
         return contracts
 
     def _to_dict(self) -> dict:
-        """Serializes the scenario content to a dict"""
+        """Serializes the scenario content to a dict."""
         result: dict[str, Any] = {
             Scenario.KEY_GENERAL: self.general_properties.to_dict(),
             Scenario.KEY_SCHEMA: self.schema.to_dict(),
@@ -164,37 +160,37 @@ class Scenario(Metadata):
 
     @property
     def agents(self) -> list[Agent]:
-        """Returns all the agents of this scenario as a list"""
+        """Returns all the agents of this scenario as a list."""
         return self._agents
 
     def add_agent(self, agent: Agent) -> None:
-        """Adds a new agent to this scenario"""
+        """Adds a new agent to this scenario."""
         self._agents.append(agent)
 
     @property
     def contracts(self) -> list[Contract]:
-        """Returns all the contracts of this scenario as a list"""
+        """Returns all the contracts of this scenario as a list."""
         return self._contracts
 
     def add_contract(self, contract: Contract) -> None:
-        """Adds a new contract to this scenario"""
+        """Adds a new contract to this scenario."""
         self._contracts.append(contract)
 
     @property
     def schema(self) -> Schema:
-        """Returns Schema associated with this scenario"""
+        """Returns Schema associated with this scenario."""
         return self._schema
 
     @property
     def general_properties(self) -> GeneralProperties:
-        """Returns General properties of this scenario"""
+        """Returns General properties of this scenario."""
         return self._general_props
 
     @property
     def string_sets(self) -> dict[str, StringSet]:
-        """Returns StringSets of this scenario"""
+        """Returns StringSets of this scenario."""
         return self._string_sets
 
     def add_string_set(self, name: str, string_set: StringSet) -> None:
-        """Adds `string_set` with `name`"""
+        """Adds `string_set` with `name`."""
         self._string_sets[name] = string_set

fameio/input/scenario/stringset.py

@@ -12,10 +12,10 @@ from fameio.tools import keys_to_lower
 
 
 class StringSet(Metadata):
-    """Hosts a StringSet in the given format"""
+    """Hosts a StringSet in the given format."""
 
     class StringSetError(InputError):
-        """An error that occurred while parsing a StringSet definition"""
+        """An error that occurred while parsing a StringSet definition."""
 
     KEY_VALUES: Final[str] = "Values".lower()
 
@@ -31,8 +31,7 @@ class StringSet(Metadata):
 
     @classmethod
     def from_dict(cls, definition: StringSetType) -> StringSet:
-        """
-        Returns StringSet initialised from `definition`
+        """Returns StringSet initialised from `definition`.
 
         Args:
             definition: dictionary representation of string set
@@ -59,9 +58,9 @@ class StringSet(Metadata):
 
     @property
     def values(self) -> dict[str, MetadataComponent]:
-        """Returns values and their associated MetadataComponent"""
+        """Returns values and their associated MetadataComponent."""
         return self._value_container.values
 
     def is_in_set(self, key: Any) -> bool:
-        """Returns True if `key` is a valid name in this StringSet"""
+        """Returns True if `key` is a valid name in this StringSet."""
         return self._value_container.has_value(key)

fameio/input/schema/agenttype.py

@@ -13,7 +13,7 @@ from .attribute import AttributeSpecs
 
 
 class AgentType(Metadata):
-    """Schema definitions for an Agent type"""
+    """Schema definitions for an Agent type."""
 
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
     KEY_PRODUCTS: Final[str] = "Products".lower()
@@ -47,8 +47,7 @@ class AgentType(Metadata):
 
     @classmethod
     def from_dict(cls, name: str, definitions: dict) -> AgentType:
-        """
-        Creates AgentType with given `name` from specified dictionary
+        """Creates AgentType with given `name` from specified dictionary.
 
         Args:
             name: of the agent type
@@ -89,8 +88,7 @@ class AgentType(Metadata):
 
     @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`
+        """Returns ValueContainer for `section` in specifications of `agent_type` extracted from given `values`.
 
         Args:
             section: key of the section that contains the values
@@ -113,26 +111,26 @@ class AgentType(Metadata):
 
     @property
     def name(self) -> str:
-        """Returns the agent type name"""
+        """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"""
+        """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"""
+        """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"""
+        """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"""
+        """Returns list of outputs or an empty list if no outputs are defined."""
         return self._outputs.values
 
     def _to_dict(self) -> dict: