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

fameio/input/validator.py

@@ -17,11 +17,11 @@ from fameio.time import FameTime
 
 
 class ValidationError(InputError):
-    """Indicates an error occurred during validation of any data with a connected schema"""
+    """Indicates an error occurred during validation of any data with a connected schema."""
 
 
 class SchemaValidator:
-    """Handles validation of scenarios based on a connected `schema`"""
+    """Handles validation of scenarios based on a connected `schema`."""
 
     _AGENT_ID_NOT_UNIQUE = "Agent ID(s) not unique: '{}'."
     _AGENT_TYPE_UNKNOWN = "Agent type '{}' not declared in Schema."
@@ -45,9 +45,7 @@ class SchemaValidator:
     def validate_scenario_and_timeseries(
         scenario: Scenario, path_resolver: PathResolver = PathResolver()
     ) -> TimeSeriesManager:
-        """
-        Validates the given `scenario` and its timeseries using given `path_resolver`
-        Raises an exception if schema requirements are not met or timeseries data are erroneous.
+        """Validates the given `scenario` and its timeseries using given `path_resolver`.
 
         Args:
             scenario: to be validated against the encompassed schema
@@ -55,8 +53,9 @@ class SchemaValidator:
 
         Returns:
             a new TimeSeriesManager initialised with validated time series from scenario
+
         Raises:
-            ValidationError: if an error in the scenario or in timeseries is spotted
+            ValidationError: if schema requirements are not met or timeseries are erroneous, logged with level "ERROR"
         """
         schema = scenario.schema
         agents = scenario.agents
@@ -75,28 +74,63 @@ class SchemaValidator:
 
     @staticmethod
     def ensure_unique_agent_ids(agents: list[Agent]) -> None:
-        """Raises exception if any id for given `agents` is not unique"""
+        """Ensures that IDs of given agents are unique.
+
+        Args:
+            agents: whose IDs are to be checked to uniqueness
+
+        Raises:
+            ValidationError: if any id for given `agents` is not unique, logged with level "ERROR"
+        """
         list_of_ids = [agent.id for agent in agents]
         non_unique_ids = [agent_id for agent_id, count in Counter(list_of_ids).items() if count > 1]
         if non_unique_ids:
             raise log_error(ValidationError(SchemaValidator._AGENT_ID_NOT_UNIQUE.format(non_unique_ids)))
 
     @staticmethod
-    def ensure_agent_and_timeseries_are_valid(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager):
-        """Validates given `agent` against `schema` plus loads and validates its timeseries"""
+    def ensure_agent_and_timeseries_are_valid(
+        agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager
+    ) -> None:
+        """Validates given `agent` against `schema`, loads and validates its timeseries.
+
+        Args:
+            agent: to be checked
+            schema: to check the agent against
+            timeseries_manager: to register new timeseries at
+
+        Raises:
+            ValidationError: if agent is not in schema, has missing or invalid data; logged with level "ERROR"
+        """
         SchemaValidator.ensure_agent_type_in_schema(agent, schema)
         SchemaValidator.ensure_is_valid_agent(agent, schema, timeseries_manager)
         SchemaValidator.load_and_validate_timeseries(agent, schema, timeseries_manager)
 
     @staticmethod
     def ensure_agent_type_in_schema(agent: Agent, schema: Schema) -> None:
-        """Raises exception if type for given `agent` is not specified in given `schema`"""
+        """Makes sure that the given agent is contained in the given schema.
+
+        Args:
+            agent: to be checked
+            schema: that ought to contain the agent
+
+        Raises:
+            ValidationError: if type for given `agent` is not specified in given `schema`, logged with level "ERROR"
+        """
         if agent.type_name not in schema.agent_types:
             raise log_error(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(agent.type_name)))
 
     @staticmethod
     def ensure_is_valid_agent(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager) -> None:
-        """Raises an exception if given `agent` does not meet the specified `schema` requirements"""
+        """Ensures that given `agent` meets the specified `schema` requirements and registers new timeseries
+
+        Args:
+            agent: to be checked
+            schema: to check against
+            timeseries_manager: to register new timeseries at
+
+        Raises:
+            ValidationError: if the agent doesn't meet the schema's requirements, logged with level "ERROR"
+        """
         scenario_attributes = agent.attributes
         schema_attributes = SchemaValidator._get_agent(schema, agent.type_name).attributes
         missing_default_series = SchemaValidator._check_mandatory_or_default(scenario_attributes, schema_attributes)
@@ -107,7 +141,18 @@ class SchemaValidator:
 
     @staticmethod
     def _get_agent(schema: Schema, name: str) -> AgentType:
-        """Returns agent specified by `name` or raises Exception if this agent is not present in given `schema`"""
+        """Returns agent type as specified by `name`.
+
+        Args:
+            schema: to obtain the agent type from
+            name: of the agent type to obtain
+
+        Returns:
+            AgentType corresponding to given name
+
+        Raises:
+            ValidationError: if this agent is not present in given `schema`, logged with level "ERROR"
+        """
         if name in schema.agent_types:
             return schema.agent_types[name]
         raise log_error(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(name)))
@@ -117,12 +162,19 @@ class SchemaValidator:
         attributes: dict[str, Attribute],
         specifications: dict[str, AttributeSpecs],
     ) -> list[str | float]:
-        """
-        Raises Exception if in given list of `specifications` at least one item is mandatory,
-        provides no defaults and is not contained in given `attributes` dictionary
+        """Ensures that each attribute that is mandatory has either a value specified or a default value available.
+
+        Also gathers and returns all default values of time series attributes.
+
+        Args:
+            attributes: to check for completeness
+            specifications: to check attributes against
 
         Returns:
             list of time series defaults used in scenario
+
+        Raises:
+            ValidationError: if any mandatory attribute is missing and has no default
         """
         missing_series_defaults: list[str | float] = []
         for name, specification in specifications.items():
@@ -154,7 +206,16 @@ class SchemaValidator:
 
     @staticmethod
     def _ensure_attributes_exist(attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs]) -> None:
-        """Raises exception any entry of given `attributes` has no corresponding type `specification`"""
+        """Ensures that each attribute has a corresponding entry in given specifications.
+
+        Args:
+            attributes: to search specifications for
+            specifications: describing the attributes
+
+        Raises:
+            ValidationError: if any entry of given `attributes` has no corresponding type `specification`,
+                logged with level "ERROR"
+        """
         for name, attribute in attributes.items():
             if name not in specifications:
                 raise log_error(ValidationError(SchemaValidator._ATTRIBUTE_UNKNOWN.format(attribute)))
@@ -170,7 +231,16 @@ class SchemaValidator:
     def _ensure_value_and_type_match(
         attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs]
     ) -> None:
-        """Raises exception if in given list of `attributes` its value does not match associated type `specification`"""
+        """Ensure that the value of an attribute match the attribute's type and are allowed.
+
+        Args:
+            attributes: to check the values for
+            specifications: describing the attribute (and potential value restrictions)
+
+        Raises:
+            ValidationError: if in given list of `attributes` any value does not match associated type `specification`,
+                logged with level "ERROR"
+        """
         for name, attribute in attributes.items():
             specification = specifications[name]
             if attribute.has_value:
@@ -190,7 +260,18 @@ class SchemaValidator:
 
     @staticmethod
     def _is_compatible(specification: AttributeSpecs, value_or_values: Any) -> bool:
-        """Returns True if given `value_or_values` is compatible to specified `attribute_type` and `should_be_list`"""
+        """Checks if given `value_or_values` is compatible with the given `specification`.
+
+        Args:
+            specification: of the attribute for which to check the values
+            value_or_values: singe value or list of values that is to be checked for compatibility
+
+        Returns:
+            True if given `value_or_values` is compatible the to specified `attribute_type`, False otherwise
+
+        Raises:
+            ValidationError: if an unknown attribute type is encountered, logged with level "ERROR"
+        """
         is_list = isinstance(value_or_values, list)
         attribute_type = specification.attr_type
         if specification.is_list:
@@ -205,7 +286,19 @@ class SchemaValidator:
 
     @staticmethod
     def _is_compatible_value(attribute_type: AttributeType, value) -> bool:
-        """Returns True if given single value is compatible to specified `attribute_type` and is not a NaN float"""
+        """Checks if given value is compatible with the specifications of the `attribute_type`.
+
+        Args:
+            attribute_type: specification to test the value against
+            value: to be tested for compatibility
+
+        Returns:
+            True if given single value is compatible to specified `attribute_type` and is not a NaN float,
+                False otherwise
+
+        Raises:
+            ValidationError: if checks for the attribute type are not implemented, logged with level "ERROR"
+        """
         if attribute_type is AttributeType.INTEGER:
             if isinstance(value, int):
                 return -2147483648 < value < 2147483647
@@ -224,15 +317,20 @@ class SchemaValidator:
 
     @staticmethod
     def _is_allowed_value(attribute: AttributeSpecs, value) -> bool:
-        """Returns True if `value` matches an entry of given `Attribute`'s value list or if this list is empty"""
-        if not attribute.values:
-            return True
-        return value in attribute.values
+        """Checks if given value is on the list of allowed values for an attribute type.
+
+        Args:
+            attribute: type description of an attribute
+            value: to be checked if compatible with the attribute type's value restrictions
+
+        Returns:
+             True if `value` matches an entry of given `Attribute`'s value list or if this list is empty
+        """
+        return not attribute.values or value in attribute.values
 
     @staticmethod
     def load_and_validate_timeseries(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager) -> None:
-        """
-        Loads all timeseries specified in given `schema` of given `agent` into given `timeseries_manager`
+        """Loads all timeseries in given `schema` for given `agent`. Uses `timeseries_manager` to validates them.
 
         Args:
             agent: definition in scenario
@@ -244,13 +342,22 @@ class SchemaValidator:
         """
         scenario_attributes = agent.attributes
         schema_attributes = SchemaValidator._get_agent(schema, agent.type_name).attributes
-        SchemaValidator._ensure_valid_timeseries(scenario_attributes, schema_attributes, timeseries_manager)
+        SchemaValidator._register_timeseries(scenario_attributes, schema_attributes, timeseries_manager)
 
     @staticmethod
-    def _ensure_valid_timeseries(
+    def _register_timeseries(
         attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs], manager: TimeSeriesManager
     ) -> None:
-        """Recursively searches for time_series in agent attributes and registers them at given `manager`"""
+        """Recursively searches for timeseries in agent attributes and registers them at given `manager`.
+
+        Args:
+            attributes: to search timeseries in
+            specifications: corresponding to the attributes
+            manager: to register new timeseries at
+
+        Raises:
+            ValidationError: if a timeseries could not be registered, logged at level "ERROR"
+        """
         for name, attribute in attributes.items():
             specification = specifications[name]
             if attribute.has_value:
@@ -262,17 +369,24 @@ class SchemaValidator:
                         message = SchemaValidator._TIME_SERIES_INVALID.format(specification.full_name)
                         raise log_error(ValidationError(message)) from e
             if attribute.has_nested:
-                SchemaValidator._ensure_valid_timeseries(attribute.nested, specification.nested_attributes, manager)
+                SchemaValidator._register_timeseries(attribute.nested, specification.nested_attributes, manager)
             if attribute.has_nested_list:
                 for entry in attribute.nested_list:
-                    SchemaValidator._ensure_valid_timeseries(entry, specification.nested_attributes, manager)
+                    SchemaValidator._register_timeseries(entry, specification.nested_attributes, manager)
 
     @staticmethod
     def ensure_string_set_consistency(agent: Agent, schema: Schema, string_sets: dict[str, StringSet]) -> None:
-        """
-        Raises exception if
-            a) an agent's attribute is of type StringSet but the corresponding StringSet is not defined in the scenario
-            b) the value assigned to an attribute of type StringSet is not contained in the corresponding StringSet
+        """Checks consistency of an `agent's` StringSet attributes as mentioned in `schema` with provided `string_sets`.
+
+        Args:
+            agent: whose StringSet attributes are to be checked for consistency
+            schema: describing the agent's attributes
+            string_sets: as defined in the scenario and to test the agents attribute against
+
+        Raises:
+            ValidationError: logged with level "ERROR", occur when either
+                a) an agent's attribute is type StringSet but the corresponding StringSet is not defined in the scenario, or
+                b) the value assigned to an attribute of type StringSet is not contained in the corresponding StringSet
         """
         scenario_attributes = agent.attributes
         schema_attributes = SchemaValidator._get_agent(schema, agent.type_name).attributes
@@ -282,12 +396,19 @@ class SchemaValidator:
     def _ensure_string_set_consistency(
         attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs], string_sets: dict[str, StringSet]
     ) -> None:
-        """
-        Recursively iterates through all attributes of an agent, applying tests if attribute type is `StringSet`
+        """Recursively iterates through all attributes of an agent checking consistency of `StringSet` type attributes.
+
+        Checks consistency of agent `StringSet` attributes with provided `string_sets` in the scenario and schema.
+
+        Args:
+            attributes: attributes of an agent
+            specifications: corresponding to the provided attributes
+            string_sets: to check attributes of type string_set against
+
         Raises:
-            ValidationError: if
-                a) StringSet mentioned in schema is not defined in the scenario
-                b) the value assigned to an attribute of type StringSet is not contained in the corresponding StringSet
+            ValidationError: logged with level "ERROR", occur when
+                a) StringSet declared in schema is not defined in the section "StringSet" in the scenario, or
+                b) value assigned to an attribute of type StringSet is not contained in the corresponding StringSet
         """
         for name, attribute in attributes.items():
             specification = specifications[name]
@@ -313,7 +434,19 @@ class SchemaValidator:
 
     @staticmethod
     def ensure_is_valid_contract(contract: Contract, schema: Schema, agent_types_by_id: dict[int, str]) -> None:
-        """Raises exception if given `contract` does not meet the `schema`'s requirements, using `agent_types_by_id`"""
+        """Checks validity of a contract's IDs and product.
+
+        Ensures that for a given `contract` sender and receiver IDs are valid, and that the sender offers the
+        contracted product.
+
+        Args:
+            contract: to be checked
+            schema: to extract the sender's available products from
+            agent_types_by_id: to test if sender and receiver IDs are contained
+
+        Raises:
+            ValidationError: if given `contract` uses unknown agent IDs or an unknown product, logged with level "ERROR"
+        """
         sender_id = contract.sender_id
         if sender_id not in agent_types_by_id:
             raise log_error(ValidationError(SchemaValidator._AGENT_MISSING.format(sender_id, contract.to_dict())))
@@ -333,7 +466,11 @@ class SchemaValidator:
 
     @staticmethod
     def check_agents_have_contracts(scenario: Scenario) -> None:
-        """Raises warning for each agent without any assigned contract"""
+        """Loads a warning for each agent without any assigned contract.
+
+        Args:
+            scenario: to search for agents without any contract
+        """
         senders = [contract.sender_id for contract in scenario.contracts]
         receivers = [contract.receiver_id for contract in scenario.contracts]
         active_agents = set(senders + receivers)

fameio/input/writer.py

@@ -28,11 +28,11 @@ from fameio.tools import ensure_is_list
 
 
 class ProtoWriterError(InputError):
-    """Indicates an error during writing of a protobuf file"""
+    """Indicates an error during writing of a protobuf file."""
 
 
 class ProtoWriter:
-    """Writes a given scenario to protobuf file"""
+    """Writes a given scenario to protobuf file."""
 
     _FAME_PROTOBUF_STREAM_HEADER = fameio.FILE_HEADER_V2
 
@@ -54,8 +54,7 @@ class ProtoWriter:
         self._time_series_manager: TimeSeriesManager = time_series_manager
 
     def write_validated_scenario(self, scenario: Scenario) -> None:
-        """
-        Writes given validated Scenario to file
+        """Writes given validated Scenario to file.
 
         Args:
             scenario: to be written to file
@@ -68,8 +67,7 @@ class ProtoWriter:
         self._write_data_to_disk(serialised)
 
     def _create_protobuf_from_scenario(self, scenario: Scenario) -> DataStorage:
-        """
-        Returns given `scenario` written to new DataStorage protobuf
+        """Returns given `scenario` written to new DataStorage protobuf.
 
         Args:
             scenario: to be converted to protobuf
@@ -97,7 +95,7 @@ class ProtoWriter:
 
     @staticmethod
     def _set_general_properties(pb_input: InputData, general_properties: GeneralProperties) -> None:
-        """Saves a scenario's general properties to specified protobuf `pb_input` container"""
+        """Saves a scenario's general properties to specified protobuf `pb_input` container."""
         log().info("Adding General Properties")
         pb_input.run_id = general_properties.run_id
         pb_input.simulation.start_time = general_properties.simulation_start_time
@@ -105,8 +103,7 @@ class ProtoWriter:
         pb_input.simulation.random_seed = general_properties.simulation_random_seed
 
     def _add_agents(self, pb_input: InputData, agents: list[Agent], schema: Schema) -> None:
-        """
-        Triggers setting of `agents` to `pb_input`
+        """Triggers setting of `agents` to `pb_input`.
 
         Args:
             pb_input: parent element to add the agents to
@@ -125,7 +122,7 @@ class ProtoWriter:
 
     @staticmethod
     def _set_agent(pb_agent: InputData.AgentDao, agent: Agent) -> InputData.AgentDao:
-        """Saves type and id of given `agent` to protobuf `pb_agent` container. Returns given `pb_agent`"""
+        """Saves type and id of given `agent` to protobuf `pb_agent` container. Returns given `pb_agent`."""
         pb_agent.class_name = agent.type_name
         pb_agent.id = agent.id
         return pb_agent
@@ -136,8 +133,7 @@ class ProtoWriter:
         attributes: dict[str, Attribute],
         specs: dict[str, AttributeSpecs],
     ) -> None:
-        """
-        Assigns `attributes` to protobuf fields of given `pb_parent` - cascades for nested Attributes
+        """Assigns `attributes` to protobuf fields of given `pb_parent` - cascades for nested Attributes.
 
         Args:
             pb_parent: to store the attributes in
@@ -171,14 +167,13 @@ class ProtoWriter:
 
     @staticmethod
     def _add_field(pb_parent: InputData.AgentDao | NestedField, name: str) -> NestedField:
-        """Returns new field with given `name` that is added to given `pb_parent`"""
+        """Returns new field with given `name` that is added to given `pb_parent`."""
         pb_field = pb_parent.fields.add()
         pb_field.field_name = name
         return pb_field
 
     def _set_attribute(self, pb_field: NestedField, value: Any, attribute_type: AttributeType) -> None:
-        """
-        Sets given `value` to given protobuf `pb_field` depending on specified `attribute_type`
+        """Sets given `value` to given protobuf `pb_field` depending on specified `attribute_type`.
 
         Args:
             pb_field: parent element to contain the attribute value therein
@@ -205,8 +200,7 @@ class ProtoWriter:
 
     @staticmethod
     def _add_contracts(pb_input: InputData, contracts: list[Contract]) -> None:
-        """
-        Adds given contracts to input data
+        """Adds given contracts to input data.
 
         Args:
             pb_input: parent element to have the contracts added to
@@ -223,7 +217,7 @@ class ProtoWriter:
 
     @staticmethod
     def _set_contract(pb_contract: ProtoContract, contract: Contract) -> ProtoContract:
-        """Saves given `contract` details to protobuf container `pb_contract`. Returns given `pb_contract`"""
+        """Saves given `contract` details to protobuf container `pb_contract`. Returns given `pb_contract`."""
         pb_contract.sender_id = contract.sender_id
         pb_contract.receiver_id = contract.receiver_id
         pb_contract.product_name = contract.product_name
@@ -235,8 +229,7 @@ class ProtoWriter:
 
     @staticmethod
     def _set_contract_attributes(pb_parent: ProtoContract | NestedField, attributes: dict[str, Attribute]) -> None:
-        """
-        Assign (nested) Attributes to given protobuf container `pb_parent`
+        """Assign (nested) Attributes to given protobuf container `pb_parent`.
 
         Args:
             pb_parent: parent element, either a contract or an attribute
@@ -263,7 +256,7 @@ class ProtoWriter:
                 ProtoWriter._set_contract_attributes(pb_field, attribute.nested)
 
     def _set_time_series(self, pb_input: InputData) -> None:
-        """Adds all time series from TimeSeriesManager to given `pb_input`"""
+        """Adds all time series from TimeSeriesManager to given `pb_input`."""
         log().info("Adding TimeSeries")
         for unique_id, identifier, data in self._time_series_manager.get_all_series():
             pb_series = pb_input.time_series.add()
@@ -274,13 +267,13 @@ class ProtoWriter:
 
     @staticmethod
     def _set_schema(pb_input: InputData, schema: Schema) -> None:
-        """Sets the given `schema` `pb_input`"""
+        """Sets the given `schema` `pb_input`."""
         log().info("Adding Schema")
         pb_input.schema = schema.to_string()
 
     @staticmethod
     def _set_string_sets(pb_input: InputData, string_sets: dict[str, StringSet]) -> None:
-        """Adds the given StringSets to given `pb_input`"""
+        """Adds the given StringSets to given `pb_input`."""
         for name, string_set in string_sets.items():
             pb_set = pb_input.string_sets.add()
             pb_set.name = name
@@ -294,7 +287,7 @@ class ProtoWriter:
 
     @staticmethod
     def _set_java_package_names(pb_model: ModelData, java_packages: JavaPackages) -> None:
-        """Adds given JavaPackages names to given ModelData section"""
+        """Adds given JavaPackages names to given ModelData section."""
         pb_packages = pb_model.package_definition
         pb_packages.agents.extend(java_packages.agents)
         pb_packages.data_items.extend(java_packages.data_items)
@@ -302,14 +295,13 @@ class ProtoWriter:
 
     @staticmethod
     def _set_execution_versions(pb_version_data: ExecutionData.VersionData) -> None:
-        """Adds version strings for fameio, fameprotobuf, and python to the given Versions message"""
+        """Adds version strings for fameio, fameprotobuf, and python to the given Versions message."""
         pb_version_data.fame_protobuf = metadata.version("fameprotobuf")
         pb_version_data.fame_io = metadata.version("fameio")
         pb_version_data.python = sys.version
 
     def _serialise(self, data_storage: DataStorage) -> bytes:
-        """
-        Serialise given data storage to bytes
+        """Serialise given data storage to bytes.
 
         Args:
             data_storage: to be serialised
@@ -326,8 +318,7 @@ class ProtoWriter:
             raise log_error(ProtoWriterError(self._ERR_PROTOBUF_ENCODING)) from e
 
     def _write_data_to_disk(self, serialised_data: bytes) -> None:
-        """
-        Writes given serialised data to file
+        """Writes given serialised data to file.
 
         Args:
             serialised_data: to be written to file

fameio/logs.py

@@ -6,10 +6,11 @@ from __future__ import annotations
 import logging as pylog
 from enum import Enum
 from pathlib import Path
+from typing import TypeVar
 
 
 class LogLevel(Enum):
-    """Levels for Logging"""
+    """Levels for Logging."""
 
     PRINT = 100
     CRITICAL = pylog.CRITICAL
@@ -33,37 +34,37 @@ _WARN_NOT_INITIALIZED = "Logger for fameio not initialised: using default log le
 LOGGER_NAME = "fameio"
 DEFAULT_LOG_LEVEL = LogLevel.WARNING
 
+T = TypeVar("T", bound=Exception)
+
 
 def log() -> pylog.Logger:
-    """Returns already set up FAME-Io's logger or - if not set up - a new logger with `WARNING`"""
+    """Returns already set up FAME-Io's logger or - if not set up - a new logger with `WARNING`."""
     if not _loggers:
         fameio_logger(DEFAULT_LOG_LEVEL.name)
         pylog.warning(_WARN_NOT_INITIALIZED)
     return _loggers[0]
 
 
-def log_critical(exception: Exception) -> Exception:
-    """
-    Logs a critical error with the exception's message and returns the exception for raising it.
-    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
+def log_critical(exception: T) -> T:
+    """Logs a critical error with the exception's message and returns the exception for raising it.
 
-    Example: `raise log_critical(MyException("My error message"))`
+    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
+    Example: `raise log_critical(MyException("My error message"))
 
     Args:
         exception: to extract the error message from
 
     Returns:
-      the given exception
+        the given exception
     """
     log().critical(str(exception))
     return exception
 
 
-def log_error(exception: Exception) -> Exception:
-    """
-    Logs an error with the exception's message and returns the exception for raising.
-    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
+def log_error(exception: T) -> T:
+    """Logs an error with the exception's message and returns the exception for raising.
 
+    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
     Example: `raise log_error(MyException("My error message"))`
 
     Args:
@@ -76,9 +77,17 @@ def log_error(exception: Exception) -> Exception:
     return exception
 
 
-def fameio_logger(log_level_name: str, file_name: Path | None = None) -> None:
+def log_and_print(message: str) -> None:
+    """Logs a message with priority "PRINT"., ensuring it is printed to console.
+
+    Args:
+        message: to be logged with the highest priority
     """
-    Ensures a logger for fameio is present and uses the specified options
+    log().log(LogLevel.PRINT.value, message)
+
+
+def fameio_logger(log_level_name: str, file_name: Path | None = None) -> None:
+    """Ensures a logger for fameio is present and uses the specified options.
 
     Args:
         log_level_name: one of Python's official logging level names, e.g. "INFO"
@@ -100,8 +109,7 @@ def fameio_logger(log_level_name: str, file_name: Path | None = None) -> None:
 
 
 def _get_logger(level: LogLevel) -> pylog.Logger:
-    """
-    Returns fameio logger with given log level without any handler and, not propagating to parent
+    """Returns fameio logger with given log level without any handler and, not propagating to parent.
 
     Args:
         level: integer representing the log level
@@ -119,10 +127,11 @@ def _get_logger(level: LogLevel) -> pylog.Logger:
 
 
 def _get_formatter(level: LogLevel) -> pylog.Formatter:
-    """
-    Returns a log formatter depending on the given log `level`
+    """Returns a log formatter depending on the given log `level`.
+
     Args:
         level: this log level determines how detailed the logger's output is
+
     Returns:
         new log formatter
     """
@@ -130,7 +139,7 @@ def _get_formatter(level: LogLevel) -> pylog.Formatter:
 
 
 def _add_handler(logger: pylog.Logger, handler: pylog.Handler, formatter: pylog.Formatter) -> None:
-    """Adds given `handler` using the specified `formatter` to given `logger` and `_handlers` list"""
+    """Adds given `handler` using the specified `formatter` to given `logger` and `_handlers` list."""
     handler.setFormatter(formatter)
     _handlers.append(handler)
     logger.addHandler(handler)