Shtime-API

There are two ways to access the API

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()

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(tzone)[Quellcode]

set timezone info from name of timezone

Parameter:: tzone – Name of the timezone (like ‚Europe/Berlin‘)
Type:: tzone: str

set_tzinfo(tzinfo)[Quellcode]

Set the timezone info

Parameter:: tzinfo –

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:: Name of the timezone (like ‚Europe/Berlin‘, or ‚UTC‘ if not set)
Rückgabetyp:: str

tzinfo()[Quellcode]

Returns the info about the actual local timezone

Rückgabe:: Timezone info
Rückgabetyp:: tz.tz.tzfile

tzlocal()[Quellcode]: POSSIBLE REPLACEMENT FOR tz.tzlocal :return:

tzname()[Quellcode]

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

Rückgabe:: timezone string (like: ‚CEST‘ or ‚CET‘)
Rückgabetyp:: str

tznameST()[Quellcode]

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

Rückgabe:: Timezone info (like: ‚CET‘)
Rückgabetyp:: str

tznameDST()[Quellcode]

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

Rückgabe:: Timezone info (like: ‚CEST‘)
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:: 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

to_seconds(time_str, test=False)[Quellcode]

casts a time value string (e.g. ‚5m‘) to an integer (duration in seconds) used for autotimer, timer, cycle

if ‚test‘ is set to True the warning log message is suppressed

supported formats for time parameter: - seconds as integer (45) - seconds as a string (‚45‘) - seconds as a string, trailed by ‚s‘ (e.g. ‚45s‘) - minutes as a string, trailed by ‚m‘ (e.g. ‚5m‘), is converted to seconds (300) - hours as a string, trailed by ‚h‘ (e.g. ‚2h‘), is converted to seconds (7200) - a combination of the above (e.g. ‚2h5m45s‘)

Parameter:

time_str – string containing the duration
test – if set to True, no warning ist logged in case of an error, only -1 is returned

Rückgabe:

number of seconds as an integer

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, offset=0)[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) – calender week to use for calculation
year (int) – year to use for calculation
offset (int) – negative number for previous weeks, positive for future ones

Rückgabe:

date the monday of given calender week

Rückgabetyp:

datetime.date

beginning_of_month(month=None, year=None, offset=0)[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
offset (int) – negative number for previous months, positive for future ones

Rückgabe:

date the first day of given month

Rückgabetyp:

datetime.date

beginning_of_year(year=None, offset=0)[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
offset (int) – negative number for previous years, positive for future ones

Rückgabe:

date the first day of given year

Rückgabetyp:

datetime.date

today(offset=0)[Quellcode]

Return today’s date

Parameter:: offset (int) – negative number for previous days, positive for future ones
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(offset=0)[Quellcode]

Return the current year

Parameter:: offset (int) – negative number for previous years, positive for future ones
Rückgabe:: year
Rückgabetyp:: int

current_month(offset=0)[Quellcode]

Return the current month

Parameter:: offset (int) – negative number for previous months, positive for future ones
Rückgabe:: month
Rückgabetyp:: int

current_monthname(offset=0)[Quellcode]

Return the name of the current month for a given date

Parameter:: offset (int) – negative number for previous months, positive for future ones
Rückgabe:: monthname NAME
Rückgabetyp:: str

current_day(offset=0)[Quellcode]

Return the current day

Parameter:: offset (int) – negative number for previous days, positive for future ones
Rückgabe:: day
Rückgabetyp:: int

length_of_year(year=None, offset=0)[Quellcode]

Returns the length of a given year

Parameter:

year (int) – year to use for calculation
offset (int) – negative number for previous months, positive for future ones

Rückgabe:

Length of year in days

Rückgabetyp:

int

length_of_month(month=None, year=None, offset=0)[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
offset (int) – negative number for previous months, positive for future ones

Rückgabe:

Length of month in days

Rückgabetyp:

int

day_of_year(date=None, offset=0)[Quellcode]

Calculate which day of the year the given date is

Parameter:

date (str|datetime.datetime|datetime.date|int|float) – date
offset (int) – negative number for previous days, positive for future ones

Rückgabe:

day of year

Rückgabetyp:

int

weekday(date=None, offset=0)[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
offset (int) – negative number for previous days, positive for future ones

Rückgabe:

weekday (1=Monday …. 7=Sunday)

Rückgabetyp:

int

calendar_week(date=None, offset=0)[Quellcode]

Returns the calendar week (according to ISO)

Parameter:

date (str|datetime.datetime|datetime.date|int|float) – date
offset (int) – negative number for previous weeks, positive for future ones

Rückgabe:

week (ISO)

Rückgabetyp:

int

weekday_name(date=None, offset=0)[Quellcode]

Returns the name of the weekday for a given date

Parameter:

date (str|datetime.datetime|datetime.date|int|float) – date
offset (int) – negative number for previous days, positive for future ones

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