homeassistant.util.dt Namespace Reference

Functions
bool	_datetime_ambiguous (dt.datetime dattim)
bool	_datetime_exists (dt.datetime dattim)
dt.timedelta	_dst_offset_diff (dt.datetime dattim)
str	_get_timestring (float timediff, int precision=1)
int|None	_lower_bound (list[int] arr, int cmp)
dt.datetime	as_local (dt.datetime dattim)
float	as_timestamp (dt.datetime|str dt_value)
dt.datetime	as_utc (dt.datetime dattim)
zoneinfo.ZoneInfo|None	async_get_time_zone (str time_zone_str)
dt.datetime	find_next_time_expression_time (dt.datetime now, list[int] seconds, list[int] minutes, list[int] hours)
str	get_age (dt.datetime date, int precision=1)
dt.tzinfo	get_default_time_zone ()
str	get_time_remaining (dt.datetime date, int precision=1)
zoneinfo.ZoneInfo|None	get_time_zone (str time_zone_str)
dt.datetime	now (dt.tzinfo|None time_zone=None)
dt.date|None	parse_date (str dt_str)
dt.datetime|None	parse_datetime (str dt_str)
dt.datetime|None	parse_datetime (str dt_str, *bool raise_on_error=False)
dt.datetime|None	parse_datetime (str dt_str, *Literal[False] raise_on_error)
dt.datetime	parse_datetime (str dt_str, *Literal[True] raise_on_error)
dt.timedelta|None	parse_duration (str value)
dt.time|None	parse_time (str time_str)
list[int]	parse_time_expression (Any parameter, int min_value, int max_value)
None	set_default_time_zone (dt.tzinfo time_zone)
dt.datetime	start_of_local_day (dt.date|dt.datetime|None dt_or_d=None)
float	utc_to_timestamp (dt.datetime utc_dt)

Variables
	__doc__
string	DATE_STR_FORMAT = "%Y-%m-%d"
	DATETIME_RE
	EPOCHORDINAL = dt.datetime(1970, 1, 1).toordinal()
	ISO8601_DURATION_RE
	POSTGRES_INTERVAL_RE
	STANDARD_DURATION_RE
	tzinfo
	UTC = dt.UTC
	utc_from_timestamp = partial(dt.datetime.fromtimestamp, tz=UTC)
	utcnow = partial(dt.datetime.now, UTC)

Detailed Description

Helper methods to handle the time in Home Assistant.

Function Documentation

_datetime_ambiguous()

bool homeassistant.util.dt._datetime_ambiguous ( dt.datetime  dattim )

private

Check whether a datetime is ambiguous.

Definition at line 557 of file dt.py.

_datetime_exists()

bool homeassistant.util.dt._datetime_exists ( dt.datetime  dattim )

private

Check if a datetime exists.

Definition at line 549 of file dt.py.

_dst_offset_diff()

dt.timedelta homeassistant.util.dt._dst_offset_diff ( dt.datetime  dattim )

private

Return the offset when crossing the DST barrier.

Definition at line 409 of file dt.py.

_get_timestring()

str homeassistant.util.dt._get_timestring ( float  timediff, int   precision = 1  )

private

Return a string representation of a time diff.

Definition at line 309 of file dt.py.

_lower_bound()

int | None homeassistant.util.dt._lower_bound ( list[int]  arr, int  cmp  )

private

Return the first value in arr greater or equal to cmp.

Return None if no such value exists.

Definition at line 417 of file dt.py.

as_local()

dt.datetime homeassistant.util.dt.as_local

(

dt.datetime

dattim

)

Convert a UTC datetime object to local time zone.

Definition at line 157 of file dt.py.

as_timestamp()

float homeassistant.util.dt.as_timestamp

(

dt.datetime | str

dt_value

)

Convert a date/time into a unix time (seconds since 1970).

Definition at line 145 of file dt.py.

as_utc()

dt.datetime homeassistant.util.dt.as_utc

(

dt.datetime

dattim

)

Return a datetime as UTC time.

Assumes datetime without tzinfo to be in the DEFAULT_TIME_ZONE.

Definition at line 132 of file dt.py.

async_get_time_zone()

zoneinfo.ZoneInfo | None homeassistant.util.dt.async_get_time_zone

(

str

time_zone_str

)

Get time zone from string. Return None if unable to determine.

Async friendly.

Definition at line 110 of file dt.py.

find_next_time_expression_time()

dt.datetime homeassistant.util.dt.find_next_time_expression_time	(	dt.datetime	now,
		list[int]	seconds,
		list[int]	minutes,
		list[int]	hours
	)

Find the next datetime from now for which the time expression matches.

The algorithm looks at each time unit separately and tries to find the
next one that matches for each. If any of them would roll over, all
time units below that are reset to the first matching value.

Timezones are also handled (the tzinfo of the now object is used),
including daylight saving time.

Definition at line 427 of file dt.py.

get_age()

str homeassistant.util.dt.get_age	(	dt.datetime	date,
		int	precision = 1
	)

Take a datetime and return its "age" as a string.

The age can be in second, minute, hour, day, month and year.

depth number of units will be returned, with the last unit rounded

The date must be in the past or a ValueException will be raised.

Definition at line 344 of file dt.py.

get_default_time_zone()

dt.tzinfo homeassistant.util.dt.get_default_time_zone

(

)

Get the default time zone.

Definition at line 79 of file dt.py.

get_time_remaining()

str homeassistant.util.dt.get_time_remaining	(	dt.datetime	date,
		int	precision = 1
	)

Take a datetime and return its "age" as a string.

The age can be in second, minute, hour, day, month and year.

depth number of units will be returned, with the last unit rounded

The date must be in the future or a ValueException will be raised.

Definition at line 363 of file dt.py.

get_time_zone()

zoneinfo.ZoneInfo | None homeassistant.util.dt.get_time_zone

(

str

time_zone_str

)

Get time zone from string. Return None if unable to determine.

Must be run in the executor if the ZoneInfo is not already
in the cache. If you are not sure, use async_get_time_zone.

Definition at line 98 of file dt.py.

now()

dt.datetime homeassistant.util.dt.now

(

dt.tzinfo | None

time_zone = None

)

Get now in specified time zone.

Definition at line 127 of file dt.py.

parse_date()

dt.date | None homeassistant.util.dt.parse_date

(

str

dt_str

)

Convert a date string to a date object.

Definition at line 254 of file dt.py.

parse_datetime() [1/4]

dt.datetime | None homeassistant.util.dt.parse_datetime

(

str

dt_str

)

Definition at line 202 of file dt.py.

parse_datetime() [2/4]

dt.datetime | None homeassistant.util.dt.parse_datetime	(	str	dt_str,
		*bool	raise_on_error = False
	)

Parse a string and return a datetime.datetime.

This function supports time zone offsets. When the input contains one,
the output uses a timezone with a fixed offset from UTC.
Raises ValueError if the input is well formatted but not a valid datetime.

If the input isn't well formatted, returns None if raise_on_error is False
or raises ValueError if it's True.

Definition at line 215 of file dt.py.

parse_datetime() [3/4]

dt.datetime | None homeassistant.util.dt.parse_datetime	(	str	dt_str,
		*Literal[False]	raise_on_error
	)

Definition at line 210 of file dt.py.

parse_datetime() [4/4]

dt.datetime homeassistant.util.dt.parse_datetime	(	str	dt_str,
		*Literal[True]	raise_on_error
	)

Definition at line 206 of file dt.py.

parse_duration()

dt.timedelta | None homeassistant.util.dt.parse_duration

(

str

value

)

Parse a duration string and return a datetime.timedelta.

Also supports ISO 8601 representation and PostgreSQL's day-time interval
format.

Definition at line 265 of file dt.py.

parse_time()

dt.time | None homeassistant.util.dt.parse_time

(

str

time_str

)

Parse a time string (00:20:00) into Time object.

Return None if invalid.

Definition at line 291 of file dt.py.

parse_time_expression()

list[int] homeassistant.util.dt.parse_time_expression	(	Any	parameter,
		int	min_value,
		int	max_value
	)

Parse the time expression part and return a list of times to match.

Definition at line 383 of file dt.py.

set_default_time_zone()

None homeassistant.util.dt.set_default_time_zone

(

dt.tzinfo

time_zone

)

Set a default time zone to be used when none is specified.

Async friendly.

Definition at line 84 of file dt.py.

start_of_local_day()

dt.datetime homeassistant.util.dt.start_of_local_day

(

dt.date | dt.datetime | None

dt_or_d = None

)

Return local datetime object of start of day from date or datetime.

Definition at line 186 of file dt.py.

utc_to_timestamp()

float homeassistant.util.dt.utc_to_timestamp

(

dt.datetime

utc_dt

)

Fast conversion of a datetime in UTC to a timestamp.

Definition at line 173 of file dt.py.

Variable Documentation

__doc__

homeassistant.util.dt.__doc__

private

Definition at line 124 of file dt.py.

DATE_STR_FORMAT

string homeassistant.util.dt.DATE_STR_FORMAT = "%Y-%m-%d"

Definition at line 16 of file dt.py.

DATETIME_RE

homeassistant.util.dt.DATETIME_RE

Initial value:

=  re.compile(
    r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})"
    r"[T ](?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
    r"(?::(?P<second>\d{1,2})(?:\.(?P<microsecond>\d{1,6})\d{0,6})?)?"
    r"(?P<tzinfo>Z|[+-]\d{2}(?::?\d{2})?)?$"
)

Definition at line 27 of file dt.py.

EPOCHORDINAL

homeassistant.util.dt.EPOCHORDINAL = dt.datetime(1970, 1, 1).toordinal()

Definition at line 22 of file dt.py.

ISO8601_DURATION_RE

homeassistant.util.dt.ISO8601_DURATION_RE

Initial value:

=  re.compile(
    r"^(?P<sign>[-+]?)"
    r"P"
    r"(?:(?P<days>\d+([\.,]\d+)?)D)?"
    r"(?:T"
    r"(?:(?P<hours>\d+([\.,]\d+)?)H)?"
    r"(?:(?P<minutes>\d+([\.,]\d+)?)M)?"
    r"(?:(?P<seconds>\d+([\.,]\d+)?)S)?"
    r")?"
    r"$"
)

Definition at line 51 of file dt.py.

POSTGRES_INTERVAL_RE

homeassistant.util.dt.POSTGRES_INTERVAL_RE

Initial value:

=  re.compile(
    r"^"
    r"(?:(?P<days>-?\d+) (days? ?))?"
    r"(?:(?P<sign>[-+])?"
    r"(?P<hours>\d+):"
    r"(?P<minutes>\d\d):"
    r"(?P<seconds>\d\d)"
    r"(?:\.(?P<microseconds>\d{1,6}))?"
    r")?$"
)

Definition at line 66 of file dt.py.

STANDARD_DURATION_RE

homeassistant.util.dt.STANDARD_DURATION_RE

Initial value:

=  re.compile(
    r"^"
    r"(?:(?P<days>-?\d+) (days?, )?)?"
    r"(?P<sign>-?)"
    r"((?:(?P<hours>\d+):)(?=\d+:\d+))?"
    r"(?:(?P<minutes>\d+):)?"
    r"(?P<seconds>\d+)"
    r"(?:[\.,](?P<microseconds>\d{1,6})\d{0,6})?"
    r"$"
)

Definition at line 37 of file dt.py.

tzinfo

homeassistant.util.dt.tzinfo

Definition at line 18 of file dt.py.

UTC

homeassistant.util.dt.UTC = dt.UTC

Definition at line 17 of file dt.py.

utc_from_timestamp

homeassistant.util.dt.utc_from_timestamp = partial(dt.datetime.fromtimestamp, tz=UTC)

Definition at line 169 of file dt.py.

utcnow

homeassistant.util.dt.utcnow = partial(dt.datetime.now, UTC)

Definition at line 123 of file dt.py.