spinedb_api.parameter_value =========================== .. py:module:: spinedb_api.parameter_value .. autoapi-nested-parse:: Parameter values in a Spine DB can be of different types (see :ref:`parameter_value_format`). For each of these types, this module provides a Python class to represent values of that type. .. list-table:: Parameter value type and Python class :header-rows: 1 * - type - Python class * - ``date_time`` - :class:`DateTime` * - ``duration`` - :class:`Duration` * - ``array`` - :class:`Array` * - ``time_pattern`` - :class:`TimePattern` * - ``time_series`` - :class:`TimeSeriesFixedResolution` and :class:`TimeSeriesVariableResolution` * - ``map`` - :class:`Map` The module also provides the functions :func:`to_database` and :func:`from_database` to translate between instances of the above classes and their DB representation (namely, the `value` and `type` fields that would go in the ``parameter_value`` table). For example, to write a Python object into a parameter value in the DB:: # Create the Python object parsed_value = TimeSeriesFixedResolution( "2023-01-01T00:00", # start "1D", # resolution [9, 8, 7, 6, 5, 4, 3, 2, 1, 0], # values ignore_year=False, repeat=False, ) # Translate it to value and type value, type_ = to_database(parsed_value) # Add a parameter_value to the DB with that value and type with DatabaseMapping(url) as db_map: db_map.add_parameter_value_item( entity_class_name="cat", entity_byname=("Tom",), parameter_definition_name="number_of_lives", alternative_name="Base", value=value, type=type_, ) db_map.commit_session("Tom is living one day at a time") The value can be accessed as a Python object using the ``parsed_value`` field:: # Get the parameter_value from the DB with DatabaseMapping(url) as db_map: pval_item = db_map.get_parameter_value_item( entity_class_name="cat", entity_byname=("Tom",), parameter_definition_name="number_of_lives", alternative_name="Base", ) value = pval_item["parsed_value"] In the rare case where a manual conversion from a DB value to Python object is needed, use :func:`.from_database`:: # Obtain value and type value, type_ = pval_item["value"], pval_item["type"] # Translate value and type to a Python object manually parsed_value = from_database(value, type_) Classes ------- .. autoapisummary:: spinedb_api.parameter_value.ParameterValue spinedb_api.parameter_value.DateTime spinedb_api.parameter_value.Duration spinedb_api.parameter_value.IndexedValue spinedb_api.parameter_value.Array spinedb_api.parameter_value.TimePattern spinedb_api.parameter_value.TimeSeries spinedb_api.parameter_value.TimeSeriesFixedResolution spinedb_api.parameter_value.TimeSeriesVariableResolution spinedb_api.parameter_value.Map Functions --------- .. autoapisummary:: spinedb_api.parameter_value.from_database spinedb_api.parameter_value.to_database spinedb_api.parameter_value.convert_map_to_dict spinedb_api.parameter_value.type_for_value spinedb_api.parameter_value.type_for_scalar Module Contents --------------- .. py:function:: from_database(value: bytes, type_: Optional[str]) -> Optional[Value] Converts a parameter value from the DB into a Python object. :param value: The binary blob containing the value data from database. :param type_: Value's type. :returns: A Python object representing the value. .. py:function:: to_database(parsed_value: Optional[Value]) -> tuple[bytes, Optional[str]] Converts a Python object representing a parameter value into its DB representation. :param parsed_value: A Python object representing the value. :returns: The value as a binary blob and its type string. .. py:class:: ParameterValue Base for all classes representing parameter values. .. py:method:: type_() -> str :classmethod: Returns the type of the parameter value represented by this object. .. py:method:: to_database() -> tuple[bytes, str] Returns the DB representation of this object. Equivalent to calling :func:`to_database` with it. :returns: The `value` and `type` fields that would go in the ``parameter_value`` table. .. py:class:: DateTime(value: Optional[Union[str, DateTime, datetime.datetime]] = None) Bases: :py:obj:`ParameterValue` A parameter value of type 'date_time'. A point in time. :param The `date_time` value.: .. py:class:: Duration(value: Optional[Union[str, dateutil.relativedelta.relativedelta, Duration]] = None) Bases: :py:obj:`ParameterValue` A parameter value of type 'duration'. An extension of time. :param value: the `duration` value. .. py:class:: IndexedValue(values: collections.abc.Sequence[Any], value_type: Optional[Type] = None, index_name: str = '') Bases: :py:obj:`ParameterValue` Base for all classes representing indexed parameter values. .. py:property:: values :type: collections.abc.Sequence[Any] The values. .. py:property:: indexes :type: numpy.typing.NDArray The indexes. .. py:property:: value_type :type: Type The type of the values. .. py:method:: get_nearest(index: Any) -> Any Returns the value at the nearest index to the given one. :param index: The index. :returns: The value. .. py:method:: get_value(index: Any) -> Any Returns the value at the given index. :param index: The index. :returns: The value. .. py:method:: set_value(index, value) Sets the value at the given index. :param index: The index. :type index: any :param value: The value. :type value: any .. py:class:: Array(values: collections.abc.Sequence[ScalarValue], value_type: Optional[Type] = None, index_name: str = '') Bases: :py:obj:`IndexedValue` A parameter value of type 'array'. A one dimensional array with zero based indexing. :param values: the array values. :param value_type: the type of the values; if not given, it will be deduced from `values`. Defaults to float if `values` is empty. :param index_name: the name you would give to the array index in your application. .. py:attribute:: indexes The indexes. .. py:class:: TimePattern(indexes: list[str], values: collections.abc.Sequence[float], index_name: str = '') Bases: :py:obj:`IndexedValue` A parameter value of type 'time_pattern'. A mapping from time patterns strings to numerical values. :param indexes: the time pattern strings. :param values: the values associated to different patterns. :param index_name: index name .. py:attribute:: indexes The indexes. .. py:class:: TimeSeries(values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '') Bases: :py:obj:`IndexedValue` Base for all classes representing 'time_series' parameter values. .. py:property:: ignore_year Whether the year should be ignored. :rtype: bool .. py:property:: repeat Whether the series is repeating. :rtype: bool .. py:class:: TimeSeriesFixedResolution(start: Union[str, datetime.datetime, numpy.datetime64], resolution: Union[str, dateutil.relativedelta.relativedelta, list[Union[str, dateutil.relativedelta.relativedelta]]], values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '') Bases: :py:obj:`TimeSeries` A parameter value of type 'time_series'. A mapping from time stamps to numerical values, with fixed durations between the time stamps. When getting the indexes the durations are applied cyclically. Currently, there is no support for the `ignore_year` and `repeat` options other than having getters for their values. :param start: the first time stamp :param resolution: duration(s) between the time stamps. :param values: the values in the time-series. :param ignore_year: True if the year should be ignored. :param repeat: True if the series is repeating. :param index_name: index name. .. py:property:: start :type: numpy.datetime64 Returns the start index. .. py:property:: resolution :type: list[dateutil.relativedelta.relativedelta] Returns the resolution as list of durations. .. py:property:: indexes The indexes. .. py:method:: get_value(index: numpy.datetime64) -> Optional[numpy.float64] Returns the value at the given time stamp. .. py:method:: set_value(index: numpy.datetime64, value: float) -> None Sets the value at the given index. .. py:class:: TimeSeriesVariableResolution(indexes: collections.abc.Sequence[Union[str, datetime.datetime, numpy.datetime64, DateTime]], values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '') Bases: :py:obj:`TimeSeries` A parameter value of type 'time_series'. A mapping from time stamps to numerical values with arbitrary time steps. :param indexes: the time stamps. :param values: the value for each time stamp. :param ignore_year: True if the year should be ignored. :param repeat: True if the series is repeating. :param index_name: index name. .. py:attribute:: indexes The indexes. .. py:class:: Map(indexes: collections.abc.Sequence[MapIndex], values: collections.abc.Sequence[Value], index_type: Optional[Type] = None, index_name: str = '') Bases: :py:obj:`IndexedValue` A parameter value of type 'map'. A mapping from key to value, where the values can be other instances of :class:`ParameterValue`. :param indexes: the indexes in the map. :param values: the value for each index. :param index_type: index type or None to deduce from ``indexes``. :param index_name: index name. .. py:attribute:: indexes The indexes. .. py:method:: is_nested() -> bool Whether any of the values is also a map. .. py:method:: value_to_database_data() -> tuple[list[list[Union[float, str]]], int] Returns map's database representation's 'data' dictionary. .. py:function:: convert_map_to_dict(map_: Map) -> dict Converts a :class:`Map` to a nested dictionary. .. py:function:: type_for_value(value: Value) -> tuple[str, int] Declares value's database type and rank. :param value: value to inspect :returns: type and rank .. py:function:: type_for_scalar(parsed_value: JSONValue) -> Optional[str] Declares scalar value's database type. :param parsed_value: parsed scalar :returns: value's type