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

fameio/input/scenario/contract.py

@@ -14,10 +14,10 @@ from fameio.tools import ensure_is_list, 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()
@@ -50,8 +50,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
@@ -84,56 +83,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 +147,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
@@ -177,8 +174,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 +201,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
@@ -230,8 +225,7 @@ class Contract(Metadata):
         return None
 
     def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
-        """
-        Resets Contract `attributes` from dict
+        """Resets Contract `attributes` from dict.
 
         Args:
             attributes: key-value pairs of attributes to be set
@@ -244,7 +238,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 +256,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
@@ -309,7 +304,7 @@ class Contract(Metadata):
 
     @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: