Class Item

This class implements the following methods and properties:

class lib.item.item.Item(smarthome, parent, path, config, items_instance=None)

Bases: object

Class from which item objects are created

The class Item implements the methods and attributes of an item. Each item is represented by an instance of the class Item. For an item to be valid and usable, it has to be part of the item tree, which is maintained by an object of class Items.

This class is used by the method `load_itemdefinitions() of the Items object.

class TypeHandler(item)

Bases: object

Class for dict/list type item handling

This class is a base class to enable modifying lists or dicts stored in item values. As item() yields a copy of the stored objects, changes are not written back to the item. This set of classes provides methods which handle storing the modified object and at the same time ensure that all item metadata handling (updated, changed, changed_age etc) are properly set.

The class method for either object type correspond to the Python list/ dict class methods for easy usage.

When an item of type list/dict is created, the appropriate sub-class is instantiated as <item>.list resp. <item>.dict as to minimize collisions between item methods and names of sub-items (e.g. update).

item_functions = []

class ListHandler(item)

Bases: TypeHandler

handle list type items

item_functions = ['append', 'prepend', 'insert', 'pop', 'extend', 'clear', 'delete', 'remove']

append(value, caller='Logic', source=None, dest=None)

prepend(value, caller='Logic', source=None, dest=None)

insert(index, value, caller='Logic', source=None, dest=None)

pop(index=None, caller='Logic', source=None, dest=None)

extend(value, caller='Logic', source=None, dest=None)

clear(caller='Logic', source=None, dest=None)

delete(value, caller='Logic', source=None, dest=None)

mimic the del list[x:y] behaviour - supply „x:y“ as value needs to be called delete instead of del for syntax reasons

remove(value, caller='Logic', source=None, dest=None)

class DictHandler(item)

Bases: TypeHandler

handle dict type items

item_functions = ['get', 'delete', 'clear', 'pop', 'popitem', 'update']

get(key, default=None)

delete(key, caller='Logic', source=None, dest=None)

needs to be called delete instead of del for syntax reasons

clear(caller='Logic', source=None, dest=None)

pop(key, caller='Logic', source=None, dest=None, default=None)

popitem(caller='Logic', source=None, dest=None)

update(value, caller='Logic', source=None, dest=None)

remove()

Cleanup item usage before item deletion Calls all plugins to remove the item and its references. :return: success :rtype: bool

find_attribute(attr, default='', level=-1, strict=False)

Find attribute value from item (level == 0) or parent item of given level

If level < 0, search up the whole item tree If strict is set and level is not reached, return ‚‘

Parameter:

• attr – Get the value from this attribute of the parent item

• level (int) – number of parent-levels

• strict (bool) – define if level is max-level or exact level

Rückgabe:

value from attribute of parent item

Ptype level:

int

Ptype strict:

bool

Rückgabe:

attribute value

Rückgabetyp:

str

path()

Path of the item

Available only in SmartHomeNG v1.6, not in versions above

Rückgabe:

String with the path of the item

Rückgabetyp:

str

id()

Old method name - Use item.property.path instead of item.property.path

type()

Datatype of the item

Rückgabe:

Datatype of the item

Rückgabetyp:

str

last_change()

Timestamp of last change of item’s value

Rückgabe:

Timestamp of last change

age()

Age of the item’s actual value. Returns the time in seconds since the last change of the value

Rückgabe:

Age of the value

Rückgabetyp:

int

last_update()

Timestamp of last update of item’s value (not necessarily change)

Rückgabe:

Timestamp of last update

update_age()

Update-age of the item’s actual value. Returns the time in seconds since the value has been updated (not necessarily changed)

Rückgabe:

Update-age of the value

Rückgabetyp:

int

last_trigger()

Timestamp of last trigger of item’s eval expression (if available)

Rückgabe:

Timestamp of last update

trigger_age()

Trigger-age of the item’s last eval trigger. Returns the time in seconds since the eval has been triggered

Rückgabe:

Update-age of the value

Rückgabetyp:

int

prev_change()

Timestamp of the previous (next-to-last) change of item’s value

Rückgabe:

Timestamp of previous change

prev_age()

Age of the item’s previous value. Returns the time in seconds the item had the the previous value

Rückgabe:

Age of the previous value

Rückgabetyp:

int

prev_update()

Timestamp of previous (next-to-last) update of item’s value (not necessarily change)

Rückgabe:

Timestamp of previous update

prev_update_age()

Update-age of the item’s previous value. Returns the time in seconds the previous value existed since it had been updated (not necessarily changed)

Rückgabe:

Update-age of the previous value

Rückgabetyp:

int

prev_trigger()

Timestamp of previous (next-to-last) trigger of item’s eval

Rückgabe:

Timestamp of previous update

prev_trigger_age()

Trigger-age of the item’s previous eval trigger. Returns the time in seconds of the previous eval trigger

Rückgabe:

Update-age of the previous value

Rückgabetyp:

int

prev_value()

Next-to-last value of the item

Rückgabe:

Next-to-last value of the item

changed_by()

Returns an indication, which plugin, logic or event changed the item’s value

Rückgabe:

Changer of item’s value

Rückgabetyp:

str

updated_by()

Returns an indication, which plugin, logic or event updated (not necessarily changed) the item’s value

Rückgabe:

Updater of item’s value

Rückgabetyp:

str

triggered_by()

Returns an indication, which plugin, logic or event triggered the item’s eval

Rückgabe:

Updater of item’s value

Rückgabetyp:

str

get_absolutepath(relativepath, attribute='')

Builds an absolute item path relative to the current item

Parameter:

• relativepath – string with the relative item path

• attribute – string with the name of the item’s attribute, which contains the relative path (for log entries)

Rückgabe:

string with the absolute item path

expand_relativepathes(attr, begintag, endtag)

converts a configuration attribute containing relative item paths to absolute paths

The item’s attribute can be of type str or list (of strings)

The begintag and the endtag remain in the result string!

Parameter:

• attr – Name of the attribute. Use * as a wildcard at the end

• begintag – string or list of strings that signals the beginning of a relative path is following

• endtag – string or list of strings that signals the end of a relative path

get_stringwithabsolutepathes(evalstr, begintag, endtag, attribute='')

converts a string containing relative item paths to a string with absolute item paths

The begintag and the endtag remain in the result string!

Parameter:

• evalstr – string with the statement that may contain relative item paths

• begintag – string that signals the beginning of a relative path is following

• endtag – string that signals the end of a relative path

• attribute – string with the name of the item’s attribute, which contains the relative path

Rückgabe:

string with the statement containing absolute item paths

get_class_from_frame(fr)

get_calling_item_from_frame(fr)

get_stack_info()

get_attr_time(attr)

return attribute time, possibly recalculated at call time

Parameter:

attr (str) – attribute to calculate time for, e.g. „cycle“ or „autotimer“

Rückgabetyp:

Optional[int]

get_attr_value(attr, value=None)

return attribute value, possibly recalculated at call time

Parameter:

attr (str) – attribute to calculate value for, e.g. cycle or autotimer

hysteresis_state()

Return the inner hysteresis_state

Available in SmartHomeNG v1.10 and above

TODO: Return right state, if value is from init:cache

Rückgabe:

hysteresis state of the item

Rückgabetyp:

str

hysteresis_data()

Return the inner hysteresis_state

returns a dict with the current hysteresis data (lower threshold, upper threshold, input value, output value and internal state)

Available in SmartHomeNG v1.10 and above

Rückgabe:

hysteresis state of the item

Rückgabetyp:

dict

add_logic_trigger(logic)

Add a logic trigger to the item

Parameter:

logic –

Rückgabe:

remove_logic_trigger(logic)

get_logic_triggers()

Returns a list of logics to trigger, if the item gets changed

Rückgabe:

Logics to trigger

Rückgabetyp:

list

add_method_trigger(method)

remove_method_trigger(method)

get_method_triggers()

Returns a list of plugin methods to trigger, if this item gets changed

Rückgabe:

methods to trigger

Rückgabetyp:

list

get_item_triggers()

Returns a list of items to trigger, if this item gets changed

Rückgabe:

methods to trigger

Rückgabetyp:

list

get_hysteresis_item_triggers()

Returns a list of items to trigger, if this item gets changed

Rückgabe:

methods to trigger

Rückgabetyp:

list

timer(time, value, auto=False, caller=None, source=None, compat='latest')

Starts a timer for this item

Parameter:

• time – Duration till the value of the item is set

• value – Value the item should be set to

• auto – Optional: If False a single timer is started, else the duration/value information is set as an autotimer

• caller – Optional: The caller of this function

• source – Optional: The source of the timer-request

• compat – Not used anymore, only defined for backward compatibility

remove_timer()

Remove a running timer for this item from the scheduler

autotimer(time=None, value=None, compat='latest')

Defines or removes an autotimer for the item

If time and value are not given (or None), an existing autotimer is removed

Parameter:

• time – Time until the value is set

• value – Value to set the item to

• compat – Not used anymore, only defined for backward compatibility

fade(dest, step=1, delta=1, caller=None, stop_fade=None, continue_fade=None, instant_set=True, update=False)

fades an item value to a given destination value

Parameter:

• dest – destination value of fade job

• step – step size for fading

• delta – time interval between value changes

• caller – Used as a source for upcoming item changes. Caller will always be „Fader“

• stop_fade – list of callers that can stop the fading (all others won’t stop it!)

• continue_fade – list of callers that can continue fading exclusively (all others will stop it)

• instant_set – If set to True, first fade value is set immediately after fade method is called, otherwise only after delta time

• update – If set to True, an ongoing fade will be updated by the new parameters on the fly

return_children()

return_parent(level=1, strict=False)

Return ancestor item of given level

If item doesn’t have <level> ancestors, and… - strict is set, return None - strict is not set, return the highest found ancestor

If level is < 1, method returns this item

Parameter:

• level (int) – number of parent-levels

• strict (bool) – define if level is max-level or exact level

Ptype level:

int

Ptype strict:

bool

Rückgabe:

ancestor item (or this item, or None)

Rückgabetyp:

object | None

set(value, caller='Logic', source=None, dest=None, prev_change=None, last_change=None)

Set an Item value and optionally set prev_change and last_change timestamps

(This method is called eg. by the database plugin to initialize items from the database on start)

Parameter:

• value –

• caller –

• source –

• dest –

• prev_change –

• last_change –

Rückgabe:

get_children_path()

jsonvars()

Translation method from object members to json :return: Key / Value pairs from object members

to_json()