Shtime-API

There are two ways to access the API

  1. Directly

    Use it the following way to access the api, if you have no access to the sh object in your method or function:

    # to get access to the object instance:
    from lib.shtime import Shtime
    shtime = Shtime.get_instance()
    
    # to access a method (eg. to get timezone info):
    shtime.tzinfo()
    
  2. Through the main SmartHome object

    If you have access to the sh object in your method or function, you can use the following way:

    # to access a method (eg. to get timezone info):
    sh.shtime.tzinfo()
    

The API is implemented through the following library:

lib.shtime

class lib.shtime.Shtime(smarthome)[Quellcode]

Bases: object

holidays = None
public_holidays = None
static get_instance()[Quellcode]

Returns the instance of the Shtime class, to be used to access the shtime-API

   from lib.shtime import Shtime
   shtime = Shtime.get_instance()

   # to access a method (eg. to get timezone info):
   shtime.tzinfo()


:return: shinfo instance
:rtype: object or None
translate(txt, vars=None)[Quellcode]

Returns translated text

Parameter

txt (str) – text to translate

Rückgabe

translated text

Rückgabetyp

str

set_tz(tz)[Quellcode]

set timezone info from name of timezone

set_tzinfo(tzinfo)[Quellcode]

Set the timezone info

now()[Quellcode]

Returns the actual time in a timezone aware format

Rückgabe

Actual time for the local timezone

Rückgabetyp

datetime.datetime

tz()[Quellcode]

Returns the the actual local timezone

Rückgabe

Timezone

Rückgabetyp

str

tzinfo()[Quellcode]

Returns the info about the actual local timezone

Rückgabe

Timezone info

Rückgabetyp

dateutil.tz.tz.tzfile

tzname()[Quellcode]

Returns the name about the actual local timezone (e.g. CET)

Rückgabe

Timezone info

Rückgabetyp

str

tznameST()[Quellcode]

Returns the name for Standard Time in the local timezone (e.g. CET)

Rückgabe

Timezone info

Rückgabetyp

str

tznameDST()[Quellcode]

Returns the name for Daylight Saving Time (DST) in the local timezone (e.g. CEST)

Rückgabe

Timezone info

Rückgabetyp

str

utcnow()[Quellcode]

Returns the actual time in GMT

Rückgabe

Actual time in GMT

Rückgabetyp

datetime.datetime

utcinfo()[Quellcode]

Returns the info about the GMT timezone

Rückgabe

Timezone info

Rückgabetyp

dateutil.tz.tz.tzfile

runtime()[Quellcode]

Returns the uptime of SmartHomeNG

Rückgabe

Uptime in days, hours, minutes and seconds

Rückgabetyp

datetime.timedelta

runtime_as_dict()[Quellcode]

Returns the uptime of SmartHomeNG as a dict of integers

Rückgabe

{days, hours, minutes, seconds}

Rückgabetyp

dict

time_since(dt, resulttype='s')[Quellcode]

Calculates the time that has elapsed since the given datetime parameter

Parameter
  • dt – point in time (in the past)

  • resulttype (str) – type in which the result should be returned (s, m, h, d, im, ih, id, dhms, ds)

Type

dt: str | datetime.datetime | datetime.date | int | float

Rückgabe

Elapsed time

Rückgabetyp

int|float|tuple

time_until(dt, resulttype='s')[Quellcode]

Calculates the time that will elapse from now to the given datetime parameter

Parameter
  • dt – point in time (in the past)

  • resulttype (str) – type in which the result should be returned (s, m, h, d, im, ih, id, dhms, ds)

Type

dt: str|datetime.datetime|datetime.date|int|float

Rückgabe

Elapsed time

Rückgabetyp

int|float|tuple

time_diff(dt1, dt2, resulttype='s')[Quellcode]

Calculates the time between the two given datetime parameters

Parameter
  • dt1 – first point in time

  • dt2 – second point in time

  • resulttype (str) – type in which the result should be returned (s, m, h, d, im, ih, id, dhms, ds)

Type

dt1: str|datetime.datetime|datetime.date|int|float

Type

dt2: str|datetime.datetime|datetime.date|int|float

Rückgabe

Elapsed time

Rückgabetyp

int|float|tuple

seconds_to_displaystring(sec)[Quellcode]

Convert number of seconds to time display-string

Parameter

sec (int) – Number of seconds to convert

Rückgabe

Display-string (in the form x days, y hours, z minutes, s seconds)

Rückgabetyp

str

datetime_transform(key)[Quellcode]

Converts Date/Time parameter from various formats to a datetime.datetime format

Parameter

key (str|datetime.datetime|datetime.date|int|float) – date/time

Rückgabe

Date/Time

Rückgabetyp

datetime.datetime

date_transform(key)[Quellcode]

Converts Date parameter from various formats to a datetime.date format

Parameter

key (str|datetime.datetime|datetime.date|int|float) – date/time

Rückgabe

Date

Rückgabetyp

datetime.date

beginning_of_week(week=None, year=None)[Quellcode]

Calculates the date of the beginning of a given week

If no week and no year are specified, the beginning of the current week is calculated

Parameter
  • week (int) – week to use for calculation

  • year (int) – year to use for calculation

Rückgabe

date the monday of given week

Rückgabetyp

datetime.date

beginning_of_month(month=None, year=None)[Quellcode]

Calculates the date of the beginning of a given month

This method is used to make code more readable

If no month is specified, the current month is used If no year is specified, the current year is used

Parameter
  • month (int) – month to use for calculation

  • year (int) – year to use for calculation

Rückgabe

date the first day of given month

Rückgabetyp

datetime.date

beginning_of_year(year=None)[Quellcode]

Calculates the date of the beginning of a given year

This method is used to make code more readable

If no year is specified, the current year is used

Parameter

year (int) – year to use for calculation

Rückgabe

date the first day of given year

Rückgabetyp

datetime.date

today()[Quellcode]

Return today’s date

Rückgabe

date of today

Rückgabetyp

datetime.date

tomorrow()[Quellcode]

Return tomorrow’s date

Rückgabe

date of tomorrow

Rückgabetyp

datetime.date

yesterday()[Quellcode]

Return yesterday’s date

Rückgabe

date of yesterday

Rückgabetyp

datetime.date

current_year()[Quellcode]

Return the current year

Rückgabe

year

Rückgabetyp

int

current_month()[Quellcode]

Return the current month

Rückgabe

month

Rückgabetyp

int

current_day()[Quellcode]

Return the current day

Rückgabe

day

Rückgabetyp

int

length_of_year(year=None)[Quellcode]

Returns the length of a given year

Parameter

year (int) – year to use for calculation

Rückgabe

Length of year in days

Rückgabetyp

int

length_of_month(month=None, year=None)[Quellcode]

Returns the length of a given month for a given year

Parameter
  • month (int) – month to use for calculation

  • year (int) – year to use for calculation

Rückgabe

Length of month in days

Rückgabetyp

int

day_of_year(date=None)[Quellcode]

Calculate which day of the year the given date is

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date

Rückgabe

day of year

Rückgabetyp

int

weekday(date=None)[Quellcode]

Returns the ISO weekday of a given date (or of today, if date is None)

Return the day of the week as an integer, where Monday is 1 and Sunday is 7. (ISO weekday)

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date

Rückgabe

weekday (1=Monday …. 7=Sunday)

Rückgabetyp

int

calendar_week(date=None)[Quellcode]

Returns the calendar week (according to ISO)

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date

Rückgabe

week (ISO)

Rückgabetyp

int

weekday_name(date=None)[Quellcode]

Returns the name of the weekday for a given date

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date

Rückgabe

weekday name

Rückgabetyp

str

add_custom_holiday(cust_date)[Quellcode]

Add a custom holiday from etc/holidays.yaml to the initialized list of holidays

Parameter

cust_date (dict) – Dictionary with holiday definition (see: /etc/holidays.yaml.default)

add_custom_holiday_range(from_date, to_date=None, holiday_name='')[Quellcode]

Add a range of dates to the custom holidays

Parameter
  • from_date (str|datetime.datetime|datetime.date|int|float) – First date to add

  • to_date (str|datetime.datetime|datetime.date|int|float) – Last date to add

  • holiday_name (str) – Name of the holidays

is_weekend(date=None)[Quellcode]

Returns True, if the date is on a weekend

Note: Easter sunday is not considered a holiday (since it is a sunday already)!

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date for which the weekday should be returned. If not specified, today is used

Rückgabe

True, if date is on a weekend

Rückgabetyp

bool

is_holiday(date=None)[Quellcode]

Returns True, if the date is a holiday (custom or public)

Note: Easter sunday is not concidered a holiday (since it is a sunday already)!

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date for which the weekday should be returned. If not specified, today is used

Rückgabe

True, if date is on a holiday

Rückgabetyp

bool

is_public_holiday(date=None)[Quellcode]

Returns True, if the date is a public holiday

Note: Easter sunday is not concidered a public holiday (since it is a sunday already)!

Parameter

date (str|datetime.datetime|datetime.date|int|float) – date for which the weekday should be returned. If not specified, today is used

Rückgabe

True, if date is on a holiday

Rückgabetyp

bool

holiday_name(date=None, as_list=False)[Quellcode]

Returns the name of the holiday, if date is a holiday

If there are multiple holidays on that date, all are returned

Parameter
  • date (str|datetime.datetime|datetime.date|int|float) – date for which the holiday-name should be returned. If not specified, today is used

  • as_list – If True, result is a list and not a str (comma delimited)

Rückgabe

name of the holiday(s)

Rückgabetyp

str|list

holiday_list(year=None)[Quellcode]

Returns a list with the defined holidays

Parameter

year (int) – Year for which the holiday list sould be returned

Rückgabe

List with holiday information

Rtpye

list

public_holiday_list(year=None)[Quellcode]

Returns a list with the defined public holidays

Parameter

year (int) – Year for which the holiday list sould be returned

Rückgabe

List with holiday information

Rtpye

list