Code Monkey home page Code Monkey logo

easy-time-jinja's Introduction

hacs_badge Version

Easy Time

Tired of getting help performing math with time? Look no further. This Template extension for home assistant makes time easy calculations easy!

Installation

Install this in HACS or download the easy_time.jinja from this repository and place the files into your config\custom_templates directory.

After installation, you can edit the first line to set a default language, this will make the macros easier to use in your native language.

{%- set default_language = 'en' %}

Languages

The current supported languages are:

Time Macros

clock(time_format)

A simple clock's time. Using clock() without arguments will use your languages settings.

Argument Type Default Example Description
time_format str - '12-hr' (Optional) '12-hr', '24-hr'
Format Output
'12-hr' 8:45 AM
'24-hr' 08:45

Examples

{% from 'easy_time.jinja' import clock %}
{{ clock() }}

clock_icon(hour)

A simple clock's icon. Using clock_icon() without arguments will produce the current time's clock icon to the nearest half hour.

Argument Type Default Example Description
hour int - 1 (Optional) Hour of the day.

Examples

{% from 'easy_time.jinja' import clock_icon %}

{# Return the current time icon #}
{{ clock_icon() }}

{# Return midnight or noon's current time icon #}
{{ clock_icon(0) }}
{{ clock_icon(12) }}

Relative Time Macros

Looking for times in the future or the past in your language? Look no further. These easy macros will pave the way to the future...

Also, please check out Relative-Time-Plus by TheFes. It has differnt options for relative time, and it's more flexible than easy_custom_time.

easy_time(entity_id_or_time)

easy_time returns the most significant friendly relative time. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours in your default language.

Argument Type Default Example Description
entity_id_or_time string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.
floor boolean False True (Optional) The time will chop the value instead of rounding. E.g. If the duration is 10.6 mintues, the output will be 10 Minutes instead of 11 minutes.

Examples

{% from 'easy_time.jinja' import easy_time %}

{# From an entity state #}
{{ easy_time('input_datetime.alarm_time') }}

{# Last Updated #}
{{ easy_time(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ easy_time('calendar.my_events') }}
{# Calendars - end time #}
{{ easy_time('calendar.my_events', 'end_time') }}

{# Overriding language or utc entity attribute #}
{{ easy_time("2023-04-07 00:00:00", None, 'en', True) }}
{{ easy_time("2023-04-07 00:00:00", language='en', utc=True) }}
{{ easy_time("2023-04-07 00:00:00", max_period='hour') }}
{{ easy_time('calendar.my_events', 'end_time', 'en', True) }}
{{ easy_time('calendar.my_events', 'end_time', language='en', utc=True) }}

big_time(entity_id_or_time)

big_time returns the friendly relative time without missing any details. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours, 2 minutes, and 1 second in your default language.

Argument Type Default Example Description
entity_id_or_time string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import big_time %}

{# From an entity state #}
{{ big_time('input_datetime.alarm_time') }}

{# Last Updated #}
{{ big_time(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ big_time('calendar.my_events') }}
{# Calendars - end time #}
{{ big_time('calendar.my_events', 'end_time') }}

{# Overriding language or utc entity attribute #}
{{ big_time("2023-04-07 00:00:00", None, 'en', True) }}
{{ big_time("2023-04-07 00:00:00", language='en', utc=True) }}
{{ big_time("2023-04-07 00:00:00", max_period='hour') }}
{{ big_time('calendar.my_events', 'end_time', 'en', True) }}
{{ big_time('calendar.my_events', 'end_time', language='en', utc=True) }}

custom_time(entity_id_or_time, values) and custom_time_attr(entity_id, attribute, values)

custom_time and custom_time_attr returns the friendly relative time providing details that match your needs. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours and 2 minutes in your default language.

Argument Type Default Example Description
uptime string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Required for custom_time_attr) attribute to extract the desired time from.
values string none 'day, hour, minute' (Required) Options for displaying time. Available options: year, week, day, hour, minute and second.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import custom_time, custom_time_attr %}

{# From an entity state #}
{# NOTE: the value after the = sign for minute and hour can be anything. #}
{{ custom_time('input_datetime.alarm_time', 'hour, minute') }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ custom_time('calendar.my_events', 'hour, minute') }}
{# Calendars - end time #}
{{ custom_time_attr('calendar.my_events', 'end_time', 'hour, minute') }}

{# Last Updated #}
{{ custom_time(states.sensor.my_energy_meter.last_updated, 'hour, minute') }}

{# Overriding language or utc entity attribute #}
{{ custom_time("2023-04-07 00:00:00", 'hour, minute', language='en', utc=True) }}
{{ custom_time_attr('calendar.my_events', 'end_time', 'hour, minute', language='en', utc=True) }}

easy_relative_time(entity_id_or_time)

easy_relative_time returns the most significant friendly relative time. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return in 3 hours or 3 hours ago in your default language.

Argument Type Default Example Description
uptime string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.
floor boolean False True (Optional) The time will chop the value instead of rounding. E.g. If the duration is 10.6 mintues, the output will be 10 Minutes instead of 11 minutes.

Examples

{% from 'easy_time.jinja' import easy_relative_time %}

{# From an entity state #}
{{ easy_relative_time('input_datetime.alarm_time') }}

{# Last Updated #}
{{ easy_relative_time(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ easy_relative_time('calendar.my_events', 'hour, minute') }}
{# Calendars - end time #}
{{ easy_relative_time('calendar.my_events', 'end_time', 'hour, minute') }}

{# Overriding language or utc entity attribute #}
{{ easy_relative_time("2023-04-07 00:00:00", None, 'en', True) }}
{{ easy_relative_time("2023-04-07 00:00:00", language='en', utc=True) }}
{{ easy_relative_time("2023-04-07 00:00:00", max_period='hour') }}
{{ easy_relative_time('calendar.my_events', 'end_time', 'en', True) }}
{{ easy_relative_time('calendar.my_events', 'end_time', language='en', utc=True) }}

big_relative_time(entity_id_or_time)

big_relative_time returns the friendly relative time without missing any details. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return in 3 hours, 2 minutes and 1 second or 3 hours, 2 minutes and 1 second ago in your default language.

Argument Type Default Example Description
uptime string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import big_relative_time %}

{# From an entity state #}
{{ big_relative_time('input_datetime.alarm_time') }}

{# Last Updated #}
{{ big_relative_time(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ big_relative_time('calendar.my_events') }}
{# Calendars - end time #}
{{ big_relative_time('calendar.my_events', 'end_time') }}

{# Overriding language or utc entity attribute #}
{{ big_relative_time("2023-04-07 00:00:00", None, 'en', True) }}
{{ big_relative_time("2023-04-07 00:00:00", language='en', utc=True) }}
{{ big_relative_time("2023-04-07 00:00:00", max_period='hour') }}
{{ big_relative_time('calendar.my_events', 'end_time', 'en', True) }}
{{ big_relative_time('calendar.my_events', 'end_time', language='en', utc=True) }}

custom_relative_time(entity_id_or_time, values) and custom_relative_time_attr(entity_id, attribute, values)

custom_relative_time and custom_relative_time_attr returns the friendly relative time providing details that are to your needs... most of the time. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours and 2 minutes in your default language.

Argument Type Default Example Description
uptime string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Required for custom_relative_time_attr) attribute to extract the desired time from.
values string none 'day, hour, minute' (Required) Options for displaying time. Available options: year, week, day, hour, minute and second.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import custom_relative_time, custom_relative_time_attr %}

{# From an entity state #}
{{ custom_relative_time('input_datetime.alarm_time', 'hour, minute') }}

{# Last Updated #}
{{ custom_relative_time(states.sensor.my_energy_meter.last_updated, 'hour, minute') }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ custom_relative_time('calendar.my_events', 'hour, minute') }}
{# Calendars - end time #}
{{ custom_relative_time_attr('calendar.my_events', 'end_time', 'hour, minute') }}

{# Overriding language or utc entity attribute #}
{{ custom_relative_time("2023-04-07 00:00:00", 'hour, minute', language='en', utc=True) }}
{{ custom_relative_time_attr('calendar.my_events', 'end_time', 'hour, minute', language='en', utc=True) }}

Difference Macros

These macros create times or phrases between 2 inputs.

easy_time_between(entity_id_or_time1, entity_id_or_time2)

easy_time_between returns the most significant friendly relative time. For example, if the time between t1 and t2 is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours in your default language.

Argument Type Default Example Description
entity_id_or_time1 string, datetime, or entity_id - 'calendar.abc' (Required) The first entity_id, date string, or datetime object.
entity_id_or_time2 string, datetime, or entity_id - 'calendar.xyz' (Required) The second entity_id, date string, or datetime object.
attr1 str or None No None (Optional) attribute to extract from entity_id_or_time1
attr2 str or None No None (Optional) attribute to extract from entity_id_or_time2
language string set by user 'en' (Optional) Override the default language.
utc1 boolean False True (Optional) If your entity_id_or_time1 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
utc1 boolean False True (Optional) If your entity_id_or_time2 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.
floor boolean False True (Optional) The time will chop the value instead of rounding. E.g. If the duration is 10.6 mintues, the output will be 10 Minutes instead of 11 minutes.

Examples

{% from 'easy_time.jinja' import easy_time_between %}

{# Between 2 entities #}
{{ easy_time_between('sensor.a', 'sensor.b') }}

{# Calendars - start time #}
{# By default, easy_time_between macros assumes you'd like the start time #}
{{ easy_time_between('calendar.my_events', 'calendar.my_orther_events') }}
{# Calendars - end time #}
{{ easy_time_between('calendar.my_events', 'calendar.my_events', 'end_time', 'end_time') }}
{{ easy_time_between('calendar.my_events', 'calendar.my_events', attr1='end_time', attr2='end_time') }}
{# Duration of your calendar event #}
{{ easy_time_between('calendar.my_events', 'calendar.my_events', attr2='end_time') }}

{# Overriding language or utc entity attribute #}
{{ easy_time_between("2023-04-07 00:00:00", now(), language='en', utc=True) }}

big_time_between(entity_id_or_time1, entity_id_or_time2)

big_time_between returns the most significant friendly relative time. For example, if the time between t1 and t2 is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours, 2 minutes, and 1 second in your default language.

Argument Type Default Example Description
entity_id_or_time1 string, datetime, or entity_id - 'calendar.abc' (Required) The first entity_id, date string, or datetime object.
entity_id_or_time2 string, datetime, or entity_id - 'calendar.xyz' (Required) The second entity_id, date string, or datetime object.
attr1 str or None No None (Optional) attribute to extract from entity_id_or_time1
attr2 str or None No None (Optional) attribute to extract from entity_id_or_time2
language string set by user 'en' (Optional) Override the default language.
utc1 boolean False True (Optional) If your entity_id_or_time1 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
utc1 boolean False True (Optional) If your entity_id_or_time2 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
max_period string 'year' 'hour' (Optional) Truncate the maximum significant period. Available options: year, week, day, hour, minute and second
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import big_time_between %}

{# Between 2 entities #}
{{ big_time_between('sensor.a', 'sensor.b') }}

{# Calendars - start time #}
{# By default, big_time_between macros assumes you'd like the start time #}
{{ big_time_between('calendar.my_events', 'calendar.my_orther_events') }}
{# Calendars - end time #}
{{ big_time_between('calendar.my_events', 'calendar.my_events', 'end_time', 'end_time') }}
{{ big_time_between('calendar.my_events', 'calendar.my_events', attr1='end_time', attr2='end_time') }}
{# Duration of your calendar event #}
{{ big_time_between('calendar.my_events', 'calendar.my_events', attr2='end_time') }}

{# Overriding language or utc entity attribute #}
{{ big_time_between("2023-04-07 00:00:00", now(), language='en', utc=True) }}

custom_time_between(entity_id_or_time, entity_id_or_time2, values)

custom_time_between returns the friendly relative time providing details that match your needs. For example, if your uptime is 3 hours, 2 minutes, and 1 second, this macro will return 3 hours and 2 minutes in your default language.

Argument Type Default Example Description
entity_id_or_time1 string, datetime, or entity_id - 'calendar.abc' (Required) The first entity_id, date string, or datetime object.
entity_id_or_time2 string, datetime, or entity_id - 'calendar.xyz' (Required) The second entity_id, date string, or datetime object.
values string none 'day, hour, minute' (Required) Options for displaying time. Available options: year, week, day, hour, minute and second.
attr1 str or None No None (Optional) attribute to extract from entity_id_or_time1
attr2 str or None No None (Optional) attribute to extract from entity_id_or_time2
language string set by user 'en' (Optional) Override the default language.
utc1 boolean False True (Optional) If your entity_id_or_time1 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
utc1 boolean False True (Optional) If your entity_id_or_time2 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
short boolean False True (Optional) Outputs abbreviated values. E.g. 12hr 50min.

Examples

{% from 'easy_time.jinja' import custom_time_between %}

{# Between 2 entities #}
{{ custom_time_between('sensor.a', 'sensor.b', 'hour, minute') }}

{# Calendars - start time #}
{# By default, custom_time_between macros assumes you'd like the start time #}
{{ custom_time_between('calendar.my_events', 'calendar.my_orther_events', 'hour, minute') }}
{# Calendars - end time #}
{{ custom_time_between('calendar.my_events', 'calendar.my_events', 'hour, minute', 'end_time', 'end_time') }}
{{ custom_time_between('calendar.my_events', 'calendar.my_events', 'hour, minute', attr1='end_time', attr2='end_time') }}
{# Duration of your calendar event #}
{{ custom_time_between('calendar.my_events', 'calendar.my_events', 'hour, minute', attr2='end_time') }}

{# Overriding language or utc entity attribute #}
{{ custom_time_between("2023-04-07 00:00:00", now(), 'hour, minute', language='en', utc=True) }}

time_between(entity_id_or_time1, entity_id_or_time2)

time_between returns a time_delta between two entities.

Argument Type Default Example Description
entity_id_or_time1 string, datetime, or entity_id - 'calendar.abc' (Required) The first entity_id, date string, or datetime object.
entity_id_or_time2 string, datetime, or entity_id - 'calendar.xyz' (Required) The second entity_id, date string, or datetime object.
attr1 str or None No None (Optional) attribute to extract from entity_id_or_time1
attr2 str or None No None (Optional) attribute to extract from entity_id_or_time2
utc1 boolean False True (Optional) If your entity_id_or_time1 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.
utc1 boolean False True (Optional) If your entity_id_or_time2 argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.

Examples

{% from 'easy_time.jinja' import time_between %}

{# Between 2 entities #}
{{ time_between('sensor.a', 'sensor.b') }}

{# Calendars - start time #}
{# By default, easy_time_between macros assumes you'd like the start time #}
{{ time_between('calendar.my_events', 'calendar.my_orther_events') }}
{# Calendars - end time #}
{{ time_between('calendar.my_events', 'calendar.my_events', 'end_time', 'end_time') }}
{{ time_between('calendar.my_events', 'calendar.my_events', attr1='end_time', attr2='end_time') }}
{# Duration of your calendar event #}
{{ time_between('calendar.my_events', 'calendar.my_events', attr2='end_time') }}

Date Macros

These macros create iso formatted date strings that can easily be turned into datetime objects.

Date Arguments

month number
January 1
February 2
March 3
April 4
May 5
June 6
July 7
August 8
September 9
October 10
November 11
December 12
week number
1st 1
2nd 2
3rd 3
4th 4
5th 5
6th 6
weekday number
Monday 1
Tuesday 2
Wednesday 3
Thursday 4
Friday 5
Saturday 6
Sunday 7
day number
1st 1
2nd 2
3rd 3
4th 4
5th 5
6th 6
7th 7
8th 8
9th 9
10th 10
11th 11
12th 12
13th 13
14th 14
15th 15
16th 16
17th 17
18th 18
19th 19
20th 20
21st 21
22nd 22
23rd 23
24th 24
25th 25
26th 26
27th 27
28th 28
29th 29
30th 30
31st 31

this_weekday(weekday), last_weekday(weekday), next_weekday(weekday)

Get the day of the week, in the future or past.

Examples

{% from 'easy_time.jinja' import this_weekday, last_weekday, next_weekday %}

{# Get Tuesdays date, this week #}
{{ this_weekday(2) | as_datetime }}

{# Get Tuesdays date, next week #}
{{ next_weekday(2) | as_datetime }}

{# Get last Tuesdays date #}
{{ last_weekday(2) | as_datetime}}

month_week_day(month, week, weekday)

This macro will return the nth day in the nth week of a month. This is best used to get the 2nd tuesday of any month, or the Thanksgiving American Holiday!

Examples

{% from 'easy_time.jinja' import month_week_day %}

{# Thanksgiving as a iso string #}
{{ month_week_day(11, 4, 3) }} 

{# Thanksgiving as a datetime for math#}
{{ month_week_day(11, 4, 3) | as_datetime }} 

{# 2nd sunday in January as an ios string #}
{{ month_week_day(1, 2, 2) }} 

{# 2nd sunday in January as a datetime #}
{{ month_week_day(1, 2, 2) | as_datetime }}

month_day(month, day)

This macro will return the nth day in the nth week of a month. This is best used to get the 2nd tuesday of any month, or the Thanksgiving American Holiday!

Examples

{% from 'easy_time.jinja' import month_day %}

{# 4th of july #}
{{ month_day(7, 4) }} 
{{ month_day(7, 4) | as_datetime }}

last_day_in_month(month, weekday)

This macro will return the last day in a moth. Do you ever want the last Sunday of each month? Look no futhur.

Examples

{% from 'easy_time.jinja' import last_day_in_month %}

{# Last Sunday in August #}
{{ last_day_in_month(8, 6) }} 
{{ last_day_in_month(8, 6) | as_datetime }}

easter()

Apparently easter falls on a different sunday ever year and it takes a small army to figure it out.

Examples

{% from 'easy_time.jinja' import easter %}

{# Last Sunday in August #}
{{ easter() }} 
{{ easter() | as_datetime }}

Counts

days_in_month(month), days_next_month(offset), days_last_month(offset)

Output the number of days this month, or next month, or any month!

Examples

{% from 'easy_time.jinja' import days_in_month %}

{# Number of days this month #}
{{ days_in_month() | int }}

{# Number of days in december #}
{{ days_in_month(12) | int }}

{# Number of days in February #}
{# works on leap year #}
{{ days_in_month(2) | int }}

{# Number of days next month #}
{{ days_next_month() | int }}
{# Optionally add an offset for further in the future #}
{{ days_next_month(2) | int }}

{# Number of days last month #}
{{ days_last_month() | int }}

count_the_days(entity_id_or_time)

count_the_days returns the number of days between now and your event. For example, if your event is in 1 day, this macro will return 1.

Argument Type Default Example Description
entity_id_or_time string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.

Examples

{% from 'easy_time.jinja' import count_the_days %}

{# From an entity state #}
{{ count_the_days('input_datetime.alarm_time') }}

{# Last Updated #}
{{ count_the_days(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ count_the_days('calendar.my_events') }}
{# Calendars - end time #}
{{ count_the_days('calendar.my_events', 'end_time') }}

{# Overriding language or utc entity attribute #}
{{ count_the_days("2023-04-07 00:00:00", utc=True) }}
{{ count_the_days('calendar.my_events', 'end_time', True) }}
{{ count_the_days('calendar.my_events', 'end_time', utc=True) }}

speak_the_days(entity_id_or_time)

speak_the_days returns the number of days between now and your event on your default language. For example, if your event is in 1 day, this macro will return tomorrow in your default language.

Argument Type Default Example Description
entity_id_or_time string, datetime, or entity_id - 'sensor.uptime' (Required) The entity_id, date string, or datetime object.
attribute str or None No None (Optional) attribute to extract the desired time from.
language string set by user 'en' (Optional) Override the default language.
utc boolean False True (Optional) If your uptime argument does not have a timezone and you wish to treat it as a UTC timestamp, set this to True. Otherwise the function assumes Local calculations.

Examples

{% from 'easy_time.jinja' import speak_the_days %}

{# From an entity state #}
{{ speak_the_days('input_datetime.alarm_time') }}

{# Last Updated #}
{{ speak_the_days(states.sensor.my_energy_meter.last_updated) }}

{# Calendars - start time #}
{# By default, easy_time macros assumes you'd like the start time #}
{{ speak_the_days('calendar.my_events') }}
{# Calendars - end time #}
{{ speak_the_days('calendar.my_events', 'end_time') }}

{# Overriding language or utc entity attribute #}
{{ speak_the_days("2023-04-07 00:00:00", 'en', True) }}
{{ speak_the_days("2023-04-07 00:00:00", language='en', utc=True) }}
{{ speak_the_days('calendar.my_events', 'end_time', 'en', True) }}
{{ speak_the_days('calendar.my_events', 'end_time', language='en', utc=True) }}

Daylight Savings

Ever wonder if you're falling behind or jumping ahead? Want to be notified a week before daylight savings? These templates will help with that.

next_dst()

Returns an iso formatted time string of the exact minute the next DST goes into affect.

Examples

{% from 'easy_time.jinja' import next_dst %}

{# Next daylight savings time #}
{{ next_dst() }} 
{{ next_dst() | as_datetime }}

next_dst_phrase()

Want a friendly phrase telling you whether you will gain or lose time? gain 1 hour or lose 1 hour

Examples

{% from 'easy_time.jinja' import next_dst_phrase %}

{# Next daylight savings time #}
{{ next_dst_phrase() }} 
{{ next_dst_phrase() | as_datetime }}

days_until_dst()

This outputs the number of days until the next DST. Useful for notifications. When the number of days is 7, send a notification. "You will gain 1 hour in 7 days"

Examples

{% from 'easy_time.jinja' import days_until_dst %}

{# Next daylight savings time #}
{{ days_until_dst() }} 
{{ days_until_dst() | int }}

Translations

month(month)

Outputs the current month in your langauge. (Optional) Add the month argument to get any translated month. The month argument can also be a datetime object.

{% from 'easy_time.jinja' import month %}

{# current month #}
{{ month() }}

{# December #}
{{ month(12) }}

weekday(weekday)

Outputs the current weekday in your langauge. (Optional) Add the weekday argument to get any translated weekday. The weekday argument can also be a datetime object.

{% from 'easy_time.jinja' import weekday %}

{# current weekday #}
{{ weekday() }}

{# Monday #}
{{ weekday(1) }}

Questions & Support

For questions or support, please visit the home assistant forums here

easy-time-jinja's People

Contributors

chrismancini avatar durgnomis-drol avatar fragmenthor avatar freedom- avatar jumping2000 avatar mariosemes avatar misa1515 avatar petro31 avatar philippwaller avatar pstray avatar pulpyyyy avatar sjankowski avatar thefes avatar viper5000 avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar

Forkers

baylanger mkcologne didgeridrew durgnomis-drol jumping2000 ppistole fragmenthor tm24fan8 igorsimic repsionu sjankowski homecodex marco-hacs viper5000 pstray misa1515 arvevm xion92 mariosemes kai-zer-ru electrick5 laktiv

easy-time-jinja's Issues

several issues using sensor.next_alarm_timestamp

as followup from https://discord.com/channels/330944238910963714/672223497736421388/1129046663105892403

using the main source timestamp template for various other template sensors:

      - unique_id: next_alarm_timestamp
        state: >
          {% macro getalarm(offsetday=0) %}
          {% set day = (now().weekday() + offsetday) % 7 %}
          {% set offset = offsetday * 86400 %}
          {% if day in range(5) %}
            {% set hour = state_attr('input_datetime.alarmclock_wd','hour') %}
            {% set minute = state_attr('input_datetime.alarmclock_wd','minute') %}
          {% else %}
            {% set hour = state_attr('input_datetime.alarmclock_we','hour') %}
            {% set minute = state_attr('input_datetime.alarmclock_we','minute') %}
          {% endif %}
          {% set alarm = hour|float|multiply(3600) + minute|float|multiply(60) %}
          {% set time = now().hour * 3600 + now().minute * 60 %}
          {{(offset - time) + alarm if offsetday else alarm - time}}
          {% endmacro %}

          {% set weekday = is_state('input_boolean.alarmclock_wd_enabled','on') %}
          {% set weekend = is_state('input_boolean.alarmclock_we_enabled','on') %}
          {% set weekdays = [0,1,2,3,4] %}
          {% set weekends = [5,6] %}
          {% set day = now().weekday() %}
          {% set nextday = day + 1 if day != 6 else 0 %}
          {% if nextday in weekdays %}
            {% if weekday %}
              {% set offsetday = nextday %}
            {% elif weekend %}
              {% set offsetday = weekends[0] %}
            {% else %}
              {% set offsetday = None %}
            {% endif %}
          {% elif nextday in weekends %}
            {% if weekend %}
              {% set offsetday = nextday %}
            {% elif weekday %}
              {% set offsetday = weekdays[0] %}
            {% else %}
              {% set offsetday = None %}
            {% endif %}
          {% else %}
            {% set offsetday = None %}
          {% endif %}

          {% if offsetday != None %}
            {% set offset = offsetday-day if offsetday > day else offsetday - day + 7 %}
            {% if (day in weekdays and weekday) or (day in weekends and weekend) %}
              {% set today_alarm = getalarm()|float %}
            {% else %}
              {% set today_alarm = -1 %}
            {% endif %}
            {% set next_alarm = getalarm(offset)|float %}
            {% set time = now().replace(second=0).replace(microsecond=0) %}
            {% if today_alarm > 0 %}
              {{as_timestamp(time) + today_alarm}}
            {% else %}
              {{as_timestamp(time) + next_alarm}}
            {% endif %}
          {% else %}
            0
          {% endif %}

and eg datetime sensor:

      - unique_id: next_alarm_datetime
        state: >
          {% set timestamp = states('sensor.next_alarm_timestamp')|int(default=0) %}
          {{as_datetime(timestamp)|as_local}}
        device_class: timestamp
        availability: >
          {% set timestamp = states('sensor.next_alarm_timestamp')|int(default=0) %}
          {{timestamp != 0}}

several the easy_time sensors produce unexpected results:

{% from 'easy_time.jinja' import speak_the_days %}
{{speak_the_days('sensor.next_alarm_datetime')}}

returns 'in 1 day', and you've posted it should be 'tomorrow'

{{states('sensor.next_alarm_timestamp')}} returns 1689309000.0

{{states('sensor.next_alarm_datetime')}} returns 2023-07-14 06:30:00+02:00

I also noted that because the main source sensors sets 0 when no alarm is set, the sensors using easy_time throw an error in that case.
Hope this suffices for you to check functionality, if not please let me know

Month option

Is it possible to make the period to be displayed as follows (including division into months):
“1 year, 5 month, 2 weeks and 3 days ago”?

big_time_between showing 1 decimal place for hour field

Since installing v2, the hour part of big_time_between is rounded, but given a .0 decimal place.

For example, the following returns 1.0 hour and 59 minutes:

{% from 'easy_time.jinja' import big_time_between %}
{{ big_time_between(now(), now() + timedelta( hours = 1, minutes = 59 )) }}

FR next and last full moon

Hi Petro,

if you have too much time at any point of time in the future and as you are already calculating Easter, would it be possible to get the dates of last and next full moon as well? :-)

custom_time_attr bug

Hello

Testing macros I found something strange
image
With 0 , Day should be in singular instead of plural.
Even better :

  • if day value is >1 and <2, souldn't it return tomorrow ?
  • if day value is >0 and <1, returns today ?
  • if day value >-1 and <0 returns yesterday ?

FR add support for datetimes

following our Discord chat, please add support for those datetimes?

https://discord.com/channels/330944238910963714/672223497736421388/1175066825042694334

this is what we talked about:

{% from 'easy_time.jinja' import month, weekday %}
{% set date = strptime(states('sensor.afvalwijzer_next_date'),'%d-%m-%Y')|as_local %}
{{ weekday(date.isoweekday()) }} {{ date.day }} {{date.month}} {{ month(date) }} {{month(date.month)}} {{ date.year }}

also please see your suggestion to self ;-)

https://discord.com/channels/330944238910963714/672223497736421388/1175060756652367983
fwiw, I had a custom_template all-in-1

{%- macro datum(datetime, add_year=false, add_hour = false) -%}
  {%- set nu = as_timestamp(datetime) %}
  {%- set months = ['januari','februari','maart','april','mei','juni','juli',
                    'augustus','september','oktober','november','december'] -%}
  {%- set wdays = ['zondag','maandag','dinsdag','woensdag','donderdag',
                  'vrijdag','zaterdag'] -%}
  {%- set wday = nu|timestamp_custom('%w',default=none)|int(default=0) -%}
  {%- set month = nu|timestamp_custom('%m',default=none)|int(default=0) -%}
  {%- set datum = nu|timestamp_custom(wdays[wday]  ~ ' %-d ' ~ months[month-1]) -%}
  {%- set datum = datum ~ ' ' ~ datetime.year if add_year else datum -%}
  {%- set datum = datum ~ ', om ' ~ datetime.hour ~ ' uur' if add_hour else datum -%}
  {{- datum -}}
{%- endmacro -%}

allowing this
https://discord.com/channels/330944238910963714/672223497736421388/1175030376046006312

{% from 'tijd.jinja' import datum %}
{{datum([ns.spring,ns.fall]|min,add_year=true, add_hour=true)}}

# non dst date times too
{{datum(strptime(states('sensor.afvalwijzer_next_date'),'%d-%m-%Y')|as_local, add_year=true, add_hour=true)}}

Having problems running some of your examples in Developer Tools Template

First, thank you for your work on this, useful!

In the Developer Tools (HA 2023.5.4), trying this function in the example, returns the error below:

last_day_in_month(month, weekday)
https://github.com/Petro31/easy-time-jinja#last_day_in_monthmonth-weekday

{% from 'easy_time.jinja' import last_day_in_month %}

{# Last Sunday in August #}
{{ last_day_in_month(8, 6) }} 
{{ last_day_in_month(8, 6) | as_datetime }}

returns:

UndefinedError: 'day' is undefined

Returns a rather odd answer:

{% from 'easy_time.jinja' import next_dst_phrase %}

{# Next daylight savings time #}
{{ next_dst_phrase() }} 
{{ next_dst_phrase() | as_datetime }} 

Result type: string
gain 53 years 
None

I have to do multiple imports to get below to run:

{% from 'easy_time.jinja' import days_in_month %}
{% from 'easy_time.jinja' import days_next_month %}
{% from 'easy_time.jinja' import days_last_month %}

{# Number of days this month #}
{{ days_in_month() | int }}

{# Number of days in december #}
{{ days_in_month(12) | int }}

{# Number of days in February #}
{# works on leap year #}
{{ days_in_month(2) | int }}

{# Number of days next month #}
{{ days_next_month() | int }}
{# Optionally add an offset for further in the future #}
{{ days_next_month(2) | int }}

{# Number of days last month #}
{{ days_last_month() | int }}

weekday macro returns wrong days and does not accept datetime argument as documented

The weekday macro seems to be broken and not working according to doc.
The guide says it also accepts datetime optionally, but the macro itself does not have code to support datetime.
Furthermore the index for weekdays is calculated wrong since 1 is substracted. the datetime.weekday() function usually returns 0-6 (Mon-Sun), but the weekday macro expects 1-7

I fixed this locally with following idx line:

{%- macro weekday(weekday=None, language=default_language) %}
{%- set idx = weekday % 7 if weekday is integer and weekday >= 0 else weekday.weekday() if weekday is datetime else now().weekday() %}
{{- languages.get(language, {}).get('days', [_bad_value]*7)[idx] }}
{%- endmacro %}

Please check what would be the best official fix for weekday in order to support datetime arguments and keep documentation and weekday index in line with the weekday() datetime function

in french, ago is before the time

hello
with easy_relative_time the french result isn't correct
ex: "5 days ago" is translate to "5 jours il y a" but the right translation is "Il y a 5 jours"
is there any way to solve this ?

FR: add drop in functionality for month() on timestamp entities

followup from Discord

have a timestamp entity like

{{states('sensor.afvalwijzer_plastic')}}

which outputs ' 2024-02-02'

for various dashboards/templates, it would be very nice to be able to do

{% set trash = 'sensor.afvalwijzer_plastic' %}
{% from 'easy_time.jinja' import month %}
{{month(trash)}}

or

month(states(trash))

to output the month name

which would be much nicer than

{{month(as_datetime(states(trash)).month)}}

which currently does the job alright

please consider adding that?
thx

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.