epicsarchiver.common.date_util

Utility functions for date formatting and validation.

Attributes

NANO_PER_SECOND
MICRO_PER_SECOND
NANO_PER_MICROSECOND
EPOCH
_DATE_FORMATS

Exceptions

DateFormatError

Exception raised for invalid date formats.

Classes

QueryTimestamp	A microsecond-precision UTC timestamp for archiver queries.
ResponseTimestamp	A nanosecond-precision UTC timestamp from archiver responses.

Functions

ensure_utc(→ datetime.datetime)	Add UTC timezone if timezone missing, otherwise convert to UTC.
year_start_epoch_seconds(→ int)	Seconds from Unix epoch at the start of a given year.
_parse_datetime_str(→ datetime.datetime)	Parse a date string using known formats.

Module Contents

epicsarchiver.common.date_util.NANO_PER_SECOND = 1000000000

epicsarchiver.common.date_util.MICRO_PER_SECOND = 1000000

epicsarchiver.common.date_util.NANO_PER_MICROSECOND = 1000

epicsarchiver.common.date_util.EPOCH

epicsarchiver.common.date_util._DATE_FORMATS = ['%Y%m%d', '%Y%m%d %H:%M', '%Y%m%d %H:%M:%S', '%Y-%m-%d', '%Y-%m-%dT%H:%M', '%Y-%m-%d %H:%M',...

exception epicsarchiver.common.date_util.DateFormatError(date_str: str)

Bases: epicsarchiver.common.validation.ValidationError

Exception raised for invalid date formats.

epicsarchiver.common.date_util.ensure_utc(input_time: datetime.datetime) → datetime.datetime

Add UTC timezone if timezone missing, otherwise convert to UTC.

Parameters:

input_time (datetime.datetime) – A timestamp object.

Returns:

A timestamp object with timezone set to UTC.

Return type:

datetime.datetime

epicsarchiver.common.date_util.year_start_epoch_seconds(year: int) → int

Seconds from Unix epoch at the start of a given year.

Parameters:

year (int) – year

Returns:

seconds from epoch of start of year.

Return type:

int

epicsarchiver.common.date_util._parse_datetime_str(date_str: str) → datetime.datetime

Parse a date string using known formats.

Parameters:

date_str – A date/datetime string.

Returns:

UTC-aware datetime.

Return type:

datetime.datetime

Raises:

DateFormatError – If the string cannot be parsed.

class epicsarchiver.common.date_util.QueryTimestamp(dt: datetime.datetime)

A microsecond-precision UTC timestamp for archiver queries.

Wraps a UTC-aware datetime. Used for the input flow: user string/datetime to archiver HTTP query parameter.

__slots__ = ('_dt',)

_dt

classmethod from_input(date_or_str: datetime.datetime | str) → QueryTimestamp

Parse user input (string or datetime).

Strings are parsed using a set of known formats. Strings without timezone information are treated as UTC. Datetimes are normalised to UTC.

Parameters:

date_or_str – A datetime object or a date/datetime string.

Returns:

QueryTimestamp

classmethod from_datetime(dt: datetime.datetime) → QueryTimestamp

From a datetime (naive assumed UTC, aware converted).

Parameters:

dt – A datetime object.

Returns:

QueryTimestamp

property datetime: datetime.datetime

UTC-aware datetime.

Returns:

UTC datetime

Return type:

datetime.datetime

to_query_string() → str

ISO 8601 with ‘Z’ suffix for archiver HTTP params.

Returns:

e.g. ‘2018-07-04T13:00:00.000000Z’

Return type:

str

class epicsarchiver.common.date_util.ResponseTimestamp(timestamp_ns: int)

A nanosecond-precision UTC timestamp from archiver responses.

Internal representation is nanoseconds since Unix epoch (int). Used for the response flow: archiver data to datetime or display string. Precision is only lost when outputting to datetime (microsecond resolution).

__slots__ = ('_ns',)

_ns

classmethod from_yearsecondnanos(year: int, seconds: int, nanos: int) → ResponseTimestamp

From archiver PB format.

Full nanosecond precision is preserved.

Parameters:

• year (int) – year

• seconds (int) – seconds into year

• nanos (int) – nanoseconds

Returns:

ResponseTimestamp

property ns: int

Nanoseconds since Unix epoch. Full precision.

Returns:

nanoseconds since epoch

Return type:

int

property datetime: datetime.datetime

UTC-aware datetime (microsecond precision).

Sub-microsecond nanoseconds are truncated.

Returns:

UTC datetime

Return type:

datetime.datetime

to_local_string() → str

Local timezone string for display.

Returns:

local timezone datetime string

Return type:

str