SmartHomeNG Methoden

Feiertage, Daten und Zeiten

Das Modul shtime stellt eine Reihe von Funktionen zur Verfügung, die es erlauben festzustellen ob ein Datum ein Feiertag ist (und welcher). Dazu muss die Verwendung von Feiertagen in /etc/holidays.yaml konfiguriert sein.

Weiterhin gibt es Funktionen, die den Umgang mit Datums- und Zeitangaben vereinfachen.

Wenn eine Funktion als Parameter ein Datum oder einen Datum/Zeit Wert erwartet, kann der Parameter in einer der folgenden Formate angegeben werden:

  • date Objekt - Wenn ein date Objekt an eine Funktion übergeben wird, welche ein datetime Objekt erwartet, wird als Uhrzeit 0 Uhr, 0 Minuten und 0 Sekunden angenommen

  • datetime Objekt - Wenn ein datetime Objekt an eine Funktion übergeben wird, welche ein date Objekt erwartet, wird die Zeitangabe ignoriert

  • string mit Datum in der Form „yyyy-mm-dd“, „yy-mm-dd“, „dd.mm.yyyy“, „dd.mm.yy“, „mm/dd/yy“ oder „mm/dd/yyyy“

  • string mit einer Datum/Zeit Angabe wie z.B. „dd.mm.yyyy hh:mm“ oder „dd.mm.yyyy hh:mm:ss“

Bemerkung

Diese Funktionen können außer in Logiken auch in eval Ausdrücken in Item Attributen verwendet werden.

Die Funktionen für Feiertags- und Wochenend-Handling sind folgende:

Funktion

Erläuterung

shtime.is_holiday(date)

Liefert True, falls das Datum ein Feiertag (gesetzlich oder benutzerdefiniert) ist

shtime.is_public_holiday(date)

Liefert True, falls das Datum ein gesetzlicher Feiertag ist

shtime.holiday_name(date, as_list=False)

Liefert den Namen des Feiertags, falls das Datum ein Feriertag ist. Wenn mehrere Feiertage auf das selbe Datum fallen, werden sie Komma- getrennt zurück geleifert. Falls as_list auf True gesetzt wird, ist das Ergebnis kein String, sondern eine Liste mit den Feiertagsnamen.

shtime.holiday_list(year)

Liefert eine Liste aller Feiertage für ein Jahr

shtime.public_holiday_list(year)

Liefert eine Liste aller gesetzlichen Feiertage für ein Jahr

shtime.is_weekend(date)

Liefert True, falls das Datum auf ein Wochenende (Sa, So) fällt

shtime.add_custom_holiday(cust_date)

Trägt benutzerdefinierte Feiertage ein, die den Bedingungen des übergebenen dict cust_date entsprechen. Das dict hat die selbe Struktur, wie in der Definition in /etc/holidays.yaml

shtime.add_custom_holiday_range(from_date, to_date=None, holiday_name=‘ ‚)

Markiert jeden Tag, beginnend mit fromdate bis inklusive to_date als Ferientag mit dem angegebenen Namen

shtime.time_since(dt, resulttype)

Liefert die Zeitdifferenz zwischen dem angegeben Zeitpunkt dt und jetzt. resulttype gibt an, ob das Ergebnis als str (s) , als float Minuten (m), Stunden (h), Tagen (+d*), als int Minuten (im), Stunden (ih), Tagen (+id*) oder als tuple (dhms) bzw. (ds) zurück gegeben werden soll. Falls nicht angegeben, wird s verwendet.

shtime.time_until(dt, resulttype)

Liefert die Zeitdifferenz zwischen jetzt und dem angegeben Zeitpunkt dt. resulttype ist analog zu time_since() zu verwenden.

shtime.time_diff(dt1, dt2, resulttype)

Liefert die Zeitdifferenz zwischen den beiden angegebenen Zeitpunkten dt1 und dt2. resulttype ist analog zu time_since() zu verwenden.

shtime.beginning_of_week(week, year, offset)

Liefert das Datum des ersten Tages der angegebenen Woche. Falls week oder year nicht angegeben werden, wird der jeweils aktuelle Wert verwendet. offset ermöglicht es, den Wochenstart einer früheren oder späteren Woche zu eruieren (default 0).

shtime.beginning_of_month(month, year, offset)

Liefert das Datum des ersten Tages des angegebenen Monats. Falls month oder year nicht angegeben werden, wird der jeweils aktuelle Wert verwendet. offset ermöglicht es, den Wochenstart eines früheren oder späteren Monats zu eruieren (default 0).

shtime.beginning_of_year(year, offset)

Liefert das Datum des ersten Tages des angegebenen Jahres. Falls year nicht angegeben wird, wird das aktuelle Jahr verwendet. offset ermöglicht es, den Jahresstart eines früheren oder späteren Jahrs zu eruieren (default 0).

Die Funktionen für das Datums-Handling sind folgende:

Funktion

Erläuterung

shtime.today(offset=0)

Liefert das aktuelle Datum als date

shtime.tomorrow()

Liefert das Datum des folgenden Tages als date

shtime.yesterday()

Liefert das Datum des zurück liegenden Tages als date

shtime.beginning_of_week(week=None, year=None, offset=0)

Liefert das Datum des Montags der Woche als date

shtime.beginning_of_month(month=None, year=None, offset=0)

Liefert das Datum des 1. des angegebenen Monats als date

shtime.beginning_of_year(year=None, offset=0)

Liefert das Datum des 1. Januar des angegebenen Jahres als date

shtime.current_year(offset=0)

Liefert das aktuelle Jahr

shtime.current_month(offset=0)

Liefert den aktuellen Monat

shtime.current_monthname(offset=0)

Liefert den Namens des aktuellen Monats

shtime.current_day(offset=0)

Liefert den aktuellen Tag

shtime.day_of_year(date=None, offset=0)

Liefert als Ergebnis, der wievielte Tag im Jahr das angegebene Datum ist

shtime.length_of_year(year=None, offset=0)

Liefert die Anzahl Tage, die das angegebene Jahr hat

shtime.length_of_month(month=None, year=None, offset=0)

Liefert die Anzahl Tage, die der angegebene Monat im angegebenen Jahr hat

shtime.calendar_week(date=None, offset=0)

Liefert die Kalenderwoche (nach ISO), in der das angegebene Datum liegt

shtime.weekday(date=None, offset=0)

Liefert den Wochentag nach ISO (1=Montag - 7=Sonntag) für das angegebene Datum

shtime.weekday_name(date=None, offset=0)

Liefert den Namen des Wochentags für das angegebene Datum

shtime.date_transform(date)

Wandelt ein Datum welches als date, datetime oder string angegeben wurde, in ein Datum vom Typ date

shtime.datetime_transform(date)

Wandelt eine Datums/Zeitangabe welche als date, datetime oder string angegeben wurde, in ein eine Datums/Zeitangabe vom Typ datetime

shtime.time_since(dt, resulttype=‘s‘)

Liefert die vergangene Zeit von der angegeben Datums/Zeitangabe bis jetzt. Über den Parameter resulttype kann festgelegt warden, in welcher Form das Ergebnis zurück geliefert werden soll:

  • s -> Anzahl Sekunden

  • m -> Minuten (mit Nachkommastellen)

  • h -> Stunden (mit Nachkommastellen)

  • d -> Tage (mit Nachkommastellen)

  • im -> Anzahl Minuten (Ganzzahl)

  • ih -> Anzahl Stunden (Ganzzahl)

  • id -> Anzahl Tage (Ganzzahl)

  • dhms -> Tuple (<Tage>, <Stunden>, <Minuten>, <Sekunden>)

  • ds -> Tuple (<Tage>, <Sekunden>)

shtime.time_until(dt, resulttype=‘s‘)

Liefert die vergehende Zeit von jetzt bis zur angegeben Datums/Zeitangabe. Der Parameter resulttype ist bei der Funktion shtime.time_since() beschrieben.

shtime.time_diff(dt1, dt2, resulttype=‘s‘)

Liefert die vergehende Zeit von jetzt bis zur angegeben Datums/Zeitangabe. Der Parameter resulttype ist bei der Funktion shtime.time_since() beschrieben.

Bemerkung

Funktionen, die als Parameter ein date erwarten, können ohne diesen Parameter aufgerufen werden. Dann wird das aktuelle Datum verwendet.

Funktionen, die als Parameter ein year und/oder month erwarten, können ohne diesen Parameter aufgerufen werden. Dann wird eine Liste über alle vorberechneten Feiertage zurück geliefert.

Funktionen, die als Parameter ein offset erwarten, können ohne diesen Parameter aufgerufen werden. Der Standardwert ist 0. Offset ist ein positiver (für zukünftige Werte) oder negativer (für vergangene Werte) Integerwert. Beispiel: shtime.beginning_of_week(None, -2) würde das Startdatum der vorletzten Woche liefern. shtime.day_of_year(shtime.today(), 2) oder shtime.day_of_year(shtime.today(2)) den Tag innerhalb des aktuellen Jahres von übermorgen.

Tipp

Die Funktionen wie shtime.today() sind im Zusammenhang mit den Feiertags-Funktionen nützlich. Um z.B. festzustellen, ob der folgende Tag ein Feiertag ist, kann einfach shtime.is_holiday(shtime.tomorrow()) aufgerufen werden.

Die Funktionen für das Zeit-Handling sind folgende:

Funktion

Erläuterung

shtime.now()

Liefert die aktuelle Zeit, unter Berücksichtigung der Zeitzone

shtime.tz()

Liefert die aktuelle lokale Zeitzone

shtime.tzname()

Liefert den Namen der aktuellen lokalen Zeitzone (z.B. CET)

shtime.utcnow()

Liefert die aktuelle Zeit in GMT, also ohne Berücksichtigung der Zeitzone

shtime.runtime()

Liefert die Laufzeit von SmartHomeNG, seit SmartHomeNG das letzte mal gestartet wurde.

Astronomie (Sonne und Mond)

sh.sun

Dieses Objekt bietet Zugriff auf Parameter der Sonne. Um dieses Objekt zu verwenden, ist es erforderlich, den Breitengrad (latitude, z.B. lat: 53.5989481) und den Längengrad (longitude z.B. lon: 10.0459898), sowie die Höhe über dem Meeresspiegel (elevation z.B.: elev: 20) in der Datei ../etc/smarthome.yaml anzugeben.

sh.sun.pos()

Die Methode sh.sun.pos() liefert die Position der Sonne und hat zwei optionale Parameter:

  • Der erste Parameter offset ist der zeitliche Offset zu jetzt in Minuten

  • Der zweite Parameter degree gibt an, ob das Ergebnis im Bogenmaß oder in Grad erfolgen soll.

Beispiele zur Sonnenstandsberechnung
# sh.sun.pos(offset)   hierbei gibt offset die Differenz in Zeit-Minuten zur aktuellen Zeit an

azimut, altitude = sh.sun.pos()   # liefert die aktuelle Position der Sonne, Ergbnis im Bogenmaß
azimut, altitude = sh.sun.pos(30) # liefert die Position, welche die Sonne in 30 Minuten haben wird im Bogenmaß

azimut, altitude = sh.sun.pos(degree=True) # liefert die aktuelle Position der Sonne in Grad
azimut, altitude = sh.sun.pos(-45, True)   # liefert die Position, welche die Sonne vor 45 Minuten hatte in Grad

sh.sun.set()

Die Methode sh.sun.set() hat liefert den Zeitpunkt des nächsten Sonnenuntergangs und hat einen optionale Parameter:

  • Der Parameter offset ist der Offset zum Sonnenuntergang in Grad (eine negative Zahl gibt an, wieviel Grad die Sonne unter dem Horizont stehen soll)

Das Ergebnis ist ein auf UTC basierendes datetime Objekt

Beispiele zur Sonnenuntergangsberechnung
# sh.sun.set(offset)   hierbei gibt offset die Differenz in Grad zum nächsten Sonnenuntergang an

sunset = sh.sun.set()      # liefert den utc-basierten Zeitpunkt des nächsten Sonnenuntergangs
sunset_tw = sh.sun.set(-6) # liefert den utc-basierten Zeitpunkt zu dem die Sonne 6° unter dem Horizont
                           # steht. (Ende der bürgerlichen Abenddämmerung)

sh.sun.rise()

Die Methode sh.sun.rise() hat liefert den Zeitpunkt des nächsten Sonnenuntergangs und hat einen optionale Parameter:

  • Der Parameter offset ist der Offset zum Sonnenuntergang in Grad (eine negative Zahl gibt an, wieviel Grad die Sonne unter dem Horizont stehen soll)

Das Ergebnis ist ein auf UTC basierendes datetime Objekt

Beispiele zur Sonnenaufgangsberechnung
# sh.sun.rise(offset)  hierbei gibt offset die Differenz in Grad zum nächsten Sonnenaufganges an

sunrise = sh.sun.rise()      # liefert den utc-basierten Zeitpunkt des nächsten Sonnenaufganges
sunrise_tw = sh.sun.rise(-6) # liefert den utc-basierten Zeitpunkt zu dem die Sonne wieder 6° unter
                             # dem Horizont steht. (Beginn der nächsten bürgerlichen Morgendämmerung)

sh.moon

Neben den drei Funktionen pos, set und rise (wie beim Objekt sh.sun) gibt es noch zwei weitere Funktionen:

Neben den drei Funktionen sh.moon.pos(), sh.moon.set() und sh.moon.rise() (analog zum sh.sun Objekt) stehen zwei weitere Funktionen (sh.moon.light() und sh.moon.phase()) zur Verfügung.

sh.moon.pos()

Die Methode sh.moon.pos() liefert die Position des Mondes und hat zwei optionale Parameter:

  • Der erste Parameter offset ist der zeitliche Offset zu jetzt in Minuten

  • Der zweite Parameter degree gibt an, ob das Ergebnis im Bogenmaß oder in Grad erfolgen soll.

Beispiele zur Mondstandsberechnung
# sh.moon.pos(offset)   hierbei gibt offset die Differenz in Zeit-Minuten zur aktuellen Zeit an

azimut, altitude = sh.moon.pos()   # liefert die aktuelle Position des Mondes, Ergbnis im Bogenmaß
azimut, altitude = sh.moon.pos(30) # liefert die Position, welche der Mond in 30 Minuten haben wird im Bogenmaß

azimut, altitude = sh.moon.pos(degree=True) # liefert die aktuelle Position des Mondes in Grad
azimut, altitude = sh.moon.pos(-45, True)   # liefert die Position, welche der Mond vor 45 Minuten hatte in Grad

sh.moon.set()

Die Methode sh.moon.set() hat liefert den Zeitpunkt des nächsten Monduntergangs und hat einen optionale Parameter:

  • Der Parameter offset ist der Offset zum Monduntergang in Grad (eine negative Zahl gibt an, wieviel Grad der Mond unter dem Horizont stehen soll)

Das Ergebnis ist ein auf UTC basierendes datetime Objekt

Beispiele zur Monduntergangsberechnung
# sh.moon.set(offset)   hierbei gibt offset die Differenz in Grad zum nächsten Monduntergang an

moonset = sh.moon.set()      # liefert den utc-basierten Zeitpunkt des nächsten Monduntergangs
moonset_tw = sh.moon.set(-6) # liefert den utc-basierten Zeitpunkt zu dem der Mond 6° unter dem Horizont steht

sh.moon.rise()

Die Methode sh.moon.rise() hat liefert den Zeitpunkt des nächsten Monduntergangs und hat einen optionale Parameter:

  • Der Parameter offset ist der Offset zum Monduntergang in Grad (eine negative Zahl gibt an, wieviel Grad der Mond unter dem Horizont stehen soll)

Das Ergebnis ist ein auf UTC basierendes datetime Objekt

Beispiele zur Mondaufgangsberechnung
# sh.moon.rise(offset)  hierbei gibt offset die Differenz in Grad zum nächsten Mondaufganges an

moonrise = sh.moon.rise()      # liefert den utc-basierten Zeitpunkt des nächsten Mondaufganges
moonrise_tw = sh.moon.rise(-6) # liefert den utc-basierten Zeitpunkt zu dem der Mond wieder 6° unter
                               # dem Horizont steht.

sh.moon.light()

sh.moon.light(offset) liefert einen Wert von 0 bis 100 der beleuchteten Fläche zur aktuellen Zeit + Offset.

sh.moon.phase()

sh.moon.phase(offset) gibt die Mondphase als ganze Zahl (0 bis 7) zurück, wobei: 0 = Neumond, 4 = Vollmond, 6 = abnehmender Halbmond

sh.tools Objekt

Das sh.tools Objekt stellt folgende nützliche Funktionen zur Verfügung:

sh.tools.ping()

Sendet ein Ping an einen Computer und liefert das Ergebnis. Beispiel:

sh.office.laptop(sh.tools.ping('hostname'))

setzt das Item office.laptop entsprechend der Rückmeldung ob ein Ping erfolgreich war oder nicht.

sh.tools.dewpoint()

Berechnet den Taupunkt für eine gegebene Temperatur und Feuchtigkeit. Beispiel:

sh.office.dew(sh.tools.dewpoint(sh.office.temp(), sh.office.hum())

setzt das Item office.dew auf das Ergebnis der Taupunktberechnung der Itemwerte von office.temp und office.hum

sh.tools.fetch_url()

Liefert dem Inhalt einer Webseite als String oder False wenn ein Fehler auftritt.

sh.tools.fetch_url('https://www.regular.com')

Es ist möglich als Parameter den Benutzernamen und ein Password anzugeben um die Abfrage bei der zu authentifizieren.

sh.tools.fetch_url('https://www.special.com', 'username', 'password')

Weiterhin kann ein Parameter für eine Zeitüberschreitung bestimmt werden:

sh.tools.fetch_url('https://www.regular.com', timeout=4)

bricht nach 4 Sekunden ohne Ergebnis ab

sh.tools.dt2ts(dt)

Wandelt ein datetime Objekt in einen Unix Zeitstempel um.

sh.tools.dt2js(dt)

Wandelt ein datetime Objekt in einen json Zeitstempel um.

sh.tools.rel2abs(temp, hum)

Wandelt einen relativen Feuchtigkeitswert in einen absoluten Feuchtigkeitswert um.

sh.tools.runtime()

Liefert die Laufzeit von SmartHomeNG zurück.