Timeseries utils

pingthings.timeseries.utils.timez

Functions:

Name	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.

Parameters:

Name	Type	Description	Default
dt	datetime	The datetime object to convert.	required

Returns:

Type	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.

Parameters:

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

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
days	float | Decimal	Days (as 24 hours) to convert to nanoseconds	0
hours	float | Decimal	Hours to convert to nanoseconds	0
minutes	float | Decimal	Minutes to convert to nanoseconds	0
seconds	float | Decimal	Seconds to convert to nanoseconds	0
milliseconds	float | Decimal	Milliseconds to convert to nanoseconds	0
microseconds	float | Decimal	Microseconds to convert to nanoseconds	0
nanoseconds	int	Nanoseconds to add to the time span	0

Returns:

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

Parameters:

Name	Type	Description	Default
ns	int	Nanoseconds since epoch	required

Returns:

Type	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

Parameters:

Name	Type	Description	Default
val	datetime | datetime64 | float | str | None	An object to convert to nanoseconds	required

Returns:

Type	Description
int | None	Object converted to nanoseconds