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:

English
Dutch - Thanks TheFes
Swedish - Thanks Hellis81
German - Thanks kCologne
Danish - Thanks CMDK
French - Thanks baylanger
Spanish - Thanks Didgeridrew
Italian - Thanks Gianpi
Portuguese - Thanks FragMenthor
Croatian - Thanks IgorSimic
Polish - Thanks Szymon Jankowski
Norwegian (Bokmål and Nynorsk) - Thanks Peder Stray
Slavic - Thanks Misa1515
Russian - Thanks ildar170975

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

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 or entity_id.

{% 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 or entity_id.

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

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

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

`hour(hour)`

Outputs the current hour in your language. (Optional) Add the hour argument to get any translated hour. The hour argument can also be a datetime object or entity_id.

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

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

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

Voice

`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) }}

`clock_phrase(entity_id_or_time)`

clock_phrase returns the current time in your default language. For example, if your event is at noon, this macro will return noon in your default language. If the event is at 11:15, the phrase will say quarter past 11.

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 clock_phrase %}

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

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

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

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

Questions & Support

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

Files

README.md

Latest commit

History

README.md

File metadata and controls

Easy Time

Installation

Languages

Time Macros

clock(time_format)

Examples

clock_icon(hour)

Examples

Relative Time Macros

easy_time(entity_id_or_time)

Examples

big_time(entity_id_or_time)

Examples

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

Examples

easy_relative_time(entity_id_or_time)

Examples

big_relative_time(entity_id_or_time)

Examples

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

Examples

Difference Macros

easy_time_between(entity_id_or_time1, entity_id_or_time2)

Examples

big_time_between(entity_id_or_time1, entity_id_or_time2)

Examples

custom_time_between(entity_id_or_time, entity_id_or_time2, values)

Examples

time_between(entity_id_or_time1, entity_id_or_time2)

Examples

Date Macros

Date Arguments

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

Examples

month_week_day(month, week, weekday)

Examples

month_day(month, day)

Examples

last_day_in_month(month, weekday)

Examples

easter()

Examples

Counts

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

Examples

count_the_days(entity_id_or_time)

Examples

Daylight Savings

next_dst()

Examples

next_dst_phrase()

Examples

days_until_dst()

Examples

Translations

month(month)

weekday(weekday)

hour(hour)

Voice

speak_the_days(entity_id_or_time)

Examples

clock_phrase(entity_id_or_time)

Examples

Questions & Support

`clock(time_format)`

`clock_icon(hour)`

`easy_time(entity_id_or_time)`

`big_time(entity_id_or_time)`

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

`easy_relative_time(entity_id_or_time)`

`big_relative_time(entity_id_or_time)`

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

`easy_time_between(entity_id_or_time1, entity_id_or_time2)`

`big_time_between(entity_id_or_time1, entity_id_or_time2)`

`custom_time_between(entity_id_or_time, entity_id_or_time2, values)`

`time_between(entity_id_or_time1, entity_id_or_time2)`

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

`month_week_day(month, week, weekday)`

`month_day(month, day)`

`last_day_in_month(month, weekday)`

`easter()`

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

`count_the_days(entity_id_or_time)`

`next_dst()`

`next_dst_phrase()`

`days_until_dst()`

`month(month)`

`weekday(weekday)`

`hour(hour)`

`speak_the_days(entity_id_or_time)`

`clock_phrase(entity_id_or_time)`