fameio 3.3.0__tar.gz → 3.4.0__tar.gz

{fameio-3.3.0 → fameio-3.4.0}/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 SPDX-License-Identifier: CC0-1.0 -->
 
-## [3.3.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.3.0) - 2025-5-09
+##  [3.4.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.4.0) - 2025-05-27
+### Changed
+- Allow nesting of sender or receiver lists in contracts !228 (@dlr-cjs)
+
+### Added
+- Add new keyword "Every" to Contracts that allow text qualification of Contract duration #249 (@dlr-cjs)
+- Add helper method to return first time stamp of a given year #247 (@dlr-cjs)
+- Add checks for Python 3.13 to CI #250 (@dlr-cjs)
+
+### Fixed
+- Avoid causing a traceback by nested contract sender or receiver lists #228 (@dlr-cjs)
+
+## [3.3.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.3.0) - 2025-05-09
 ### Changed
 - Expose static methods to read, convert, and write time series #245 (@dlr-cjs)
 - Improve docstrings of SchemaValidator !219 (@dlr-cjs)

{fameio-3.3.0 → fameio-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fameio
-Version: 3.3.0
+Version: 3.4.0
 Summary: Tools for input preparation and output digestion of FAME models
 License: Apache-2.0
 Keywords: FAME,fameio,agent-based modelling,energy systems
@@ -507,7 +507,7 @@ Contracts:
     ReceiverId: 2
     ProductName: ProductOfAgent_1
     FirstDeliveryTime: -25
-    DeliveryIntervalInSteps: 3600
+    Every: 3600
     Metadata:
       Some: "additional information can go here"
 
@@ -515,7 +515,7 @@ Contracts:
     ReceiverId: 1
     ProductName: ProductOfAgent_2
     FirstDeliveryTime: -22
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
     Attributes:
       ProductAppendix: value
       TimeOffset: 42
@@ -527,7 +527,8 @@ Contract Parameters:
 * `ReceiverId` unique ID of agent receiving the product
 * `ProductName` name of the product to be sent
 * `FirstDeliveryTime` first time of delivery in the format "seconds after the January 1st 2000, 00:00:00"
-* `DeliveryIntervalInSteps` delay time in between deliveries in seconds
+* `Every` delay time in between deliveries; either an integer value in seconds, or a qualified time span in the format "<integer> <TimeUnit>(s)", where TimeUnit is one of "second", "minute", "hour", "day", "week", "month", "year" - with an options "s" at the end; mind that week, month, and year refer to fixed-length intervals of 168, 730, and 8760 hours.
+* `DeliveryIntervalInSteps` deprecated; delay time in between deliveries in seconds (use instead of `Every`)
 * `Metadata` can be assigned to add further helpful information about a Contract
 * `Attributes` can be set to include additional information as `int`, `float`, `enum`, or `dict` data types
 
@@ -541,59 +542,72 @@ example:
 ```yaml
 Contracts:
   # effectively 3 similar contracts (0 -> 11), (0 -> 12), (0 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: 0
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 10), (2 -> 10), (3 -> 10)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 11), (2 -> 12), (3 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
-Combined with YAML anchors complex contract chains can be easily reduced to a minimum of required configuration.
-The following example is equivalent to the previous one and allows a quick extension of contracts to a new couple of
-agents e.g. (4;14):
+When combined with YAML anchors, the complexity of extensive contract chains can be reduced.
+The following example is equivalent to the previous one, enabling contracts to be quickly extended to a new group of agents:
 
 ```yaml
 Groups:
-  - &agentList1: [ 1,2,3 ]
-  - &agentList2: [ 11,12,13 ]
+  - &agentList1: [ 1, 2, 3 ]
+  - &agentList2: [ 11, 12, 13 ]
 
 Contracts:
   - SenderId: 0
     ReceiverId: *agentList2
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: *agentList2
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
+Lists can be nested in senders and receivers as follows:
+
+```
+Groups:
+  - SenderId: 42
+    ReceiverId: [1, [2, 3], [4, [5]]]
+    ProductName: AnImportantProduct
+    FirstDeliveryTime: 101
+    Every: 30 minutes
+```
+
+This feature should not be overused, as nested lists can become messy and difficult to read.
+Special care should be taken when using it with an N-to-N mapping, as it will be difficult to check whether senders and receivers are matched correctly.
+
 #### StringSets
 
 This optional section defines values of type `string_set`.

{fameio-3.3.0 → fameio-3.4.0}/README.md

@@ -475,7 +475,7 @@ Contracts:
     ReceiverId: 2
     ProductName: ProductOfAgent_1
     FirstDeliveryTime: -25
-    DeliveryIntervalInSteps: 3600
+    Every: 3600
     Metadata:
       Some: "additional information can go here"
 
@@ -483,7 +483,7 @@ Contracts:
     ReceiverId: 1
     ProductName: ProductOfAgent_2
     FirstDeliveryTime: -22
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
     Attributes:
       ProductAppendix: value
       TimeOffset: 42
@@ -495,7 +495,8 @@ Contract Parameters:
 * `ReceiverId` unique ID of agent receiving the product
 * `ProductName` name of the product to be sent
 * `FirstDeliveryTime` first time of delivery in the format "seconds after the January 1st 2000, 00:00:00"
-* `DeliveryIntervalInSteps` delay time in between deliveries in seconds
+* `Every` delay time in between deliveries; either an integer value in seconds, or a qualified time span in the format "<integer> <TimeUnit>(s)", where TimeUnit is one of "second", "minute", "hour", "day", "week", "month", "year" - with an options "s" at the end; mind that week, month, and year refer to fixed-length intervals of 168, 730, and 8760 hours.
+* `DeliveryIntervalInSteps` deprecated; delay time in between deliveries in seconds (use instead of `Every`)
 * `Metadata` can be assigned to add further helpful information about a Contract
 * `Attributes` can be set to include additional information as `int`, `float`, `enum`, or `dict` data types
 
@@ -509,59 +510,72 @@ example:
 ```yaml
 Contracts:
   # effectively 3 similar contracts (0 -> 11), (0 -> 12), (0 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: 0
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 10), (2 -> 10), (3 -> 10)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   # effectively 3 similar contracts (1 -> 11), (2 -> 12), (3 -> 13)
-  # with otherwise identical ProductName, FirstDeliveryTime & DeliveryIntervalInSteps
+  # with otherwise identical ProductName, FirstDeliveryTime, and Every
   - SenderId: [ 1, 2, 3 ]
     ReceiverId: [ 11, 12, 13 ]
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
-Combined with YAML anchors complex contract chains can be easily reduced to a minimum of required configuration.
-The following example is equivalent to the previous one and allows a quick extension of contracts to a new couple of
-agents e.g. (4;14):
+When combined with YAML anchors, the complexity of extensive contract chains can be reduced.
+The following example is equivalent to the previous one, enabling contracts to be quickly extended to a new group of agents:
 
 ```yaml
 Groups:
-  - &agentList1: [ 1,2,3 ]
-  - &agentList2: [ 11,12,13 ]
+  - &agentList1: [ 1, 2, 3 ]
+  - &agentList2: [ 11, 12, 13 ]
 
 Contracts:
   - SenderId: 0
     ReceiverId: *agentList2
     ProductName: MyOtherProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: 10
     ProductName: MyProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 
   - SenderId: *agentList1
     ReceiverId: *agentList2
     ProductName: MyThirdProduct
     FirstDeliveryTime: 100
-    DeliveryIntervalInSteps: 3600
+    Every: 1 hour
 ```
 
+Lists can be nested in senders and receivers as follows:
+
+```
+Groups:
+  - SenderId: 42
+    ReceiverId: [1, [2, 3], [4, [5]]]
+    ProductName: AnImportantProduct
+    FirstDeliveryTime: 101
+    Every: 30 minutes
+```
+
+This feature should not be overused, as nested lists can become messy and difficult to read.
+Special care should be taken when using it with an N-to-N mapping, as it will be difficult to check whether senders and receivers are matched correctly.
+
 #### StringSets
 
 This optional section defines values of type `string_set`.

{fameio-3.3.0 → fameio-3.4.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "fameio"
-version = "3.3.0"
+version = "3.4.0"
 description = "Tools for input preparation and output digestion of FAME models"
 license = "Apache-2.0"
 readme = "README.md"

{fameio-3.3.0 → fameio-3.4.0}/src/fameio/input/scenario/contract.py

@@ -10,7 +10,7 @@ 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):
@@ -24,6 +24,7 @@ class Contract(Metadata):
     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: '{}'"
@@ -73,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
@@ -164,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)
@@ -224,6 +226,43 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MISSING_KEY.format(key)))
         return 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"
+        """
+        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.
 
@@ -280,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))
@@ -302,6 +340,13 @@ 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`."""

{fameio-3.3.0 → fameio-3.4.0}/src/fameio/time.py

@@ -17,6 +17,7 @@ START_IN_REAL_TIME = "2000-01-01_00:00:00"
 DATE_FORMAT = "%Y-%m-%d_%H:%M:%S"
 DATE_REGEX = re.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{2}:[0-9]{2}:[0-9]{2}")
 FAME_FIRST_DATETIME = dt.datetime.strptime(START_IN_REAL_TIME, DATE_FORMAT)
+TIME_SPAN_REGEX = re.compile(r"^[0-9]+\s*[A-z]+$")
 
 
 class ConversionError(InputError, OutputError):
@@ -71,6 +72,8 @@ class FameTime:
     _INVALID_TOO_LARGE = "Cannot convert time stamp string '{}' - last day of leap year is Dec 30th!"
     _NO_TIMESTAMP = "Time value expected, but '{}' is neither a time stamp string nor an integer."
     _INVALID_DATE_FORMAT = "Received invalid date format '{}'."
+    _INVALID_SPAN_FORMAT = "Time span must be provided in the format '<positive integer> <TimeUnit>' but was: '{}'"
+    _INVALID_TIME_UNIT = f"Time span unit '{{}}' unknown, must be one of: {[u.name for u in TimeUnit]}"
 
     @staticmethod
     def convert_datetime_to_fame_time_step(datetime_string: str) -> int:
@@ -160,6 +163,32 @@ class FameTime:
             return steps * value
         raise log_error(ConversionError(FameTime._TIME_UNIT_UNKNOWN.format(unit)))
 
+    @staticmethod
+    def convert_text_to_time_span(string: str) -> int:
+        """Converts given string in form of "<positive integer> <TimeUnit>" to a time span in FAME time steps.
+
+        Args:
+            string: to convert to a time span from
+
+        Returns:
+            FAME time steps equivalent of `value x unit`
+
+        Raises:
+            ConversionError: if an unknown time unit or an unsupported format is used, logged with level "ERROR"
+        """
+        string = string.strip()
+        if TIME_SPAN_REGEX.fullmatch(string) is None:
+            raise log_error(ConversionError(FameTime._INVALID_SPAN_FORMAT.format(string)))
+        multiple, unit_name = string.split()
+        unit_name = unit_name.upper()
+        if not unit_name.endswith("S"):
+            unit_name += "S"
+        try:
+            unit = TimeUnit[unit_name]
+        except KeyError as e:
+            raise log_error(ConversionError(FameTime._INVALID_TIME_UNIT.format(unit_name))) from e
+        return FameTime.convert_time_span_to_fame_time_steps(int(multiple), unit)
+
     @staticmethod
     def is_datetime(string: Any) -> bool:
         """Returns `True` if given `string` matches Datetime string format and can be converted to FAME time step."""
@@ -208,3 +237,15 @@ class FameTime:
             return int(value)
         except ValueError as e:
             raise log_error(ConversionError(FameTime._NO_TIMESTAMP.format(value))) from e
+
+    @staticmethod
+    def get_first_fame_time_step_of_year(year: int) -> int:
+        """Returns FAME time in integer format of first time step of given year.
+
+        Args:
+            year: to get the first time step for
+
+        Returns:
+            first time step in the requested year in integer format
+        """
+        return (year - FAME_FIRST_DATETIME.year) * Constants.STEPS_PER_YEAR