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

set timezone info from name of timezone

Parameter: tz – Name of the timezone (like ‚Europe/Berlin‘)
Type: tz: 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: dateutil.tz.tz.tzfile

tzname()[Quellcode]

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

Rückgabe: timezone string (like: ‚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: 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, 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_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