From 28a9071ad7b5e3d7ece4273dd15b5c9d57f899c0 Mon Sep 17 00:00:00 2001 From: rlippmann <70883373+rlippmann@users.noreply.github.com> Date: Tue, 30 Apr 2024 04:25:26 -0400 Subject: [PATCH] Deprecate relative_time in favor of time_since()/time_until() (#25631) Co-authored-by: haydndup <22921789+haydndup@users.noreply.github.com> Co-authored-by: Franck Nijhof Co-authored-by: Erik Montnemery Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_docs/configuration/templating.markdown | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index dc1f2e2d3c4..099bb0b4ac3 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -736,8 +736,12 @@ For example, if you wanted to select a field from `trigger` in an automation bas - `as_timestamp(value, default)` converts datetime object or string to UNIX timestamp. If that fails, returns the `default` value, or if omitted raises an error. This function can also be used as a filter. - `as_local()` converts datetime object to local time. This function can also be used as a filter. - `strptime(string, format, default)` parses a string based on a [format](https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior) and returns a datetime object. If that fails, it returns the `default` value or, if omitted, raises an error. -- `relative_time` converts datetime object to its human-friendly "age" string. The age can be in second, minute, hour, day, month or year (but only the biggest unit is considered, e.g., if it's 2 days and 3 hours, "2 days" will be returned). Note that it only works for dates _in the past_. - - Using `relative_time()` will cause templates to be refreshed at the start of every new minute. +- `time_since(datetime, precision)` converts a datetime object into its human-readable time string. The time string can be in seconds, minutes, hours, days, months, and years. `precision` takes an integer (full number) and indicates the number of units returned. The last unit is rounded. For example: `precision = 1` could return "2 years" while `precision = 2` could return "1 year 11 months". This function can also be used as a filter. +If the datetime is in the future, returns 0 seconds. +A precision of 0 returns all available units, default is 1. +- `time_until(datetime, precision)` converts a datetime object into a human-readable time string. The time string can be in seconds, minutes, hours, days, months, and years. `precision` takes an integer (full number) and indicates the number of units returned. The last unit is rounded. For example: `precision = 1` could return "2 years" while `precision = 2` could return "1 year 11 months". This function can also be used as a filter. +If the datetime is in the past, returns 0 seconds. +A precision of 0 returns all available units, default is 1. - `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. {% raw %}