Timeseries utils

pingthings.timeseries.utils.timez

FUNCTION	DESCRIPTION
currently_as_ns	Returns the current UTC time as nanoseconds since epoch
datetime_to_ns	Converts a datetime object to nanoseconds since epoch. If a timezone-aware
nearest_point_width	Convert time delta of days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds or hertz to the nearest
ns_delta	Similar to timedelta, ns_delta represents a span of time but as
ns_to_datetime	Converts nanoseconds to a UTC datetime object (UTC+0)
to_nanoseconds	Converts datetime, datetime64, float, str (RFC 2822) to nanoseconds. If a

Attributes

Functions

currently_as_ns

currently_as_ns() -> int

Returns the current UTC time as nanoseconds since epoch

datetime_to_ns

datetime_to_ns(dt: datetime) -> int

Converts a datetime object to nanoseconds since epoch. If a timezone-aware object is received then it will be converted to UTC. If a timezone-naive object is received then it will be assumed to be in UTC.

PARAMETER	DESCRIPTION
dt	The datetime object to convert. TYPE: datetime

RETURNS	DESCRIPTION
int	The number of nanoseconds since the Unix epoch.

nearest_point_width

nearest_point_width(
    days: float | Decimal = 0,
    hours: float | Decimal = 0,
    minutes: float | Decimal = 0,
    seconds: float | Decimal = 0,
    milliseconds: float | Decimal = 0,
    microseconds: float | Decimal = 0,
    nanoseconds: int = 0,
    hertz: float | Decimal = 0,
) -> _PW

Convert time delta of days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds or hertz to the nearest point-width.

PARAMETER	DESCRIPTION
days	Days (as 24 hours) to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
hours	Hours to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
minutes	Minutes to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
seconds	Seconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
milliseconds	Milliseconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
microseconds	Microseconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
nanoseconds	Nanoseconds to add to the time span TYPE: int DEFAULT: 0
hertz	Alternatively, provide the frequency in Hz TYPE: float | Decimal DEFAULT: 0

RETURNS	DESCRIPTION
_PW	The nearest point-width-aligned value.

ns_delta

ns_delta(
    days: float | Decimal = 0,
    hours: float | Decimal = 0,
    minutes: float | Decimal = 0,
    seconds: float | Decimal = 0,
    milliseconds: float | Decimal = 0,
    microseconds: float | Decimal = 0,
    nanoseconds: int = 0,
) -> int

Similar to timedelta, ns_delta represents a span of time but as the total number of nanoseconds.

PARAMETER	DESCRIPTION
days	Days (as 24 hours) to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
hours	Hours to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
minutes	Minutes to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
seconds	Seconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
milliseconds	Milliseconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
microseconds	Microseconds to convert to nanoseconds TYPE: float | Decimal DEFAULT: 0
nanoseconds	Nanoseconds to add to the time span TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
int	Amount of time in nanoseconds

ns_to_datetime

ns_to_datetime(ns: int) -> datetime

Converts nanoseconds to a UTC datetime object (UTC+0)

PARAMETER	DESCRIPTION
ns	Nanoseconds since epoch TYPE: int

RETURNS	DESCRIPTION
datetime	Nanoseconds since epoch as a datetime object

to_nanoseconds

to_nanoseconds(
    val: datetime | datetime64 | float | str | None,
) -> int | None

Converts datetime, datetime64, float, str (RFC 2822) to nanoseconds. If a datetime-like object is received then nanoseconds since epoch is returned.

The following string formats are supported for conversion.

Format String	Description
%Y-%m-%d %H:%M:%S.%f%z	most common RFC3339 nanoseconds
%Y-%m-%d %H:%M:%S.%f	expects UTC default timezone
%Y-%m-%dT%H:%M:%S.%fZ	JSON encoding, UTC timezone
%Y-%m-%dT%H:%M:%SZ	JSON encoding, UTC timezone
%Y-%m-%dT%H:%M:%S.%f%z	less common JSON-ish encoding
%Y-%m-%dT%H:%M:%S.%f	for completeness, UTC+0 default timezone
%Y-%m-%d %H:%M:%S%z	human readable date time with TZ
%Y-%m-%d %H:%M:%S	human readable date time UTC+0 default
%Y-%m-%d	human readable date time at midnight UTC default

PARAMETER	DESCRIPTION
val	An object to convert to nanoseconds TYPE: datetime | datetime64 | float | str | None

RETURNS	DESCRIPTION
int | None	Object converted to nanoseconds