nitypes.bintime.DateTime

class nitypes.bintime.DateTime

class DateTime(value: _OtherDateTime, /)

class DateTime(year: SupportsIndex, month: SupportsIndex, day: SupportsIndex, hour: SupportsIndex = ..., minute: SupportsIndex = ..., second: SupportsIndex = ..., microsecond: SupportsIndex = ..., femtosecond: SupportsIndex = ..., yoctosecond: SupportsIndex = ..., tzinfo: datetime.tzinfo | None = None)

An absolute time in NI Binary Time Format (NI-BTF).

DateTime represents time as a 128-bit fixed point number with 64-bit whole seconds and 64-bit fractional seconds.

Warning

The fractional seconds are represented as a binary fraction, which is a sum of inverse powers of 2. Values that are not exactly representable as binary fractions will display rounding error or “bruising” similar to a floating point number.

DateTime instances are duck typing compatible with a subset of the method and properties supported by datetime.datetime and hightime.datetime.

This class only supports the UTC time zone and does not support timezone-naive times.

This class does not support the fold property for disambiguating repeated times for daylight saving time and time zone changes.

Constructing

As with datetime.datetime, you can construct a DateTime by specifying the year, month, day, etc.:

>>> import datetime
>>> DateTime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc)
nitypes.bintime.DateTime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc)

Note

DateTime only supports datetime.timezone.utc. It does not support time-zone-naive objects or time zones other than UTC.

You can also construct a DateTime from a datetime.datetime or hightime.datetime:

>>> DateTime(datetime.datetime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc))
nitypes.bintime.DateTime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc)
>>> import hightime
>>> DateTime(hightime.datetime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc))
nitypes.bintime.DateTime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc)

You can get the current time of day by calling DateTime.now:

>>> DateTime.now(datetime.timezone.utc)
nitypes.bintime.DateTime(...)

Properties

Like other datetime objects, DateTime has properties for the year, month, day, hour, minute, second, and microsecond.

>>> import datetime
>>> x = DateTime(datetime.datetime(2025, 5, 25, 16, 45, tzinfo=datetime.timezone.utc))
>>> (x.year, x.month, x.day)
(2025, 5, 25)
>>> (x.hour, x.minute, x.second, x.microsecond)
(16, 45, 0, 0)

Like hightime.datetime, it also supports the femtosecond and yoctosecond properties.

>>> (x.femtosecond, x.yoctosecond)
(0, 0)

Resolution

NI-BTF is a high-resolution time format, so it has significantly higher resolution than datetime.datetime. However, hightime.datetime has even higher resolution:

Class	Smallest Time Increment
`datetime.datetime`	1 microsecond (1e-6 sec)
`DateTime`	54210 yoctoseconds (5.4e-20 sec)
`hightime.datetime`	1 yoctosecond (1e-24 sec)

As a result, hightime.datetime can represent the time down to the exact yoctosecond, but DateTime rounds the yoctosecond field.

>>> import hightime
>>> x = hightime.datetime(2025, 1, 1, yoctosecond=123456789, tzinfo=datetime.timezone.utc)
>>> x
hightime.datetime(2025, 1, 1, 0, 0, 0, 0, 0, 123456789, tzinfo=datetime.timezone.utc)
>>> DateTime(x)
nitypes.bintime.DateTime(2025, 1, 1, 0, 0, 0, 0, 0, 123436417, tzinfo=datetime.timezone.utc)

Rounding

NI-BTF represents fractional seconds as a binary fraction, which is a sum of inverse powers of 2. Values that are not exactly representable as binary fractions will display rounding error or “bruising” similar to a floating point number.

For example, it may round 100 microseconds down to 99.9999… microseconds.

>>> x = hightime.datetime(2025, 1, 1, microsecond=100, tzinfo=datetime.timezone.utc)
>>> x
hightime.datetime(2025, 1, 1, 0, 0, 0, 100, tzinfo=datetime.timezone.utc)
>>> DateTime(x)
nitypes.bintime.DateTime(2025, 1, 1, 0, 0, 0, 99, 999999999, 999991239,
    tzinfo=datetime.timezone.utc)

Class members

min: ClassVar[DateTime]: The earliest supported DateTime object, midnight on Jan 1, 0001, UTC.

max: ClassVar[DateTime]: The latest supported DateTime object, before midnight on Dec 31, 9999, UTC.

__slots__ = ['_offset', '_hightime_cache']

classmethod from_ticks(ticks: SupportsIndex) → typing_extensions.Self: Create an DateTime from a 128-bit fixed point number expressed as an integer.

classmethod from_tuple(value: nitypes.bintime.TimeValueTuple) → typing_extensions.Self: Create a DateTime from whole and fractional seconds as 64-bit ints.

classmethod from_offset(offset: nitypes.bintime.TimeDelta) → typing_extensions.Self: Create an DateTime from a TimeValue offset from the epoch, Jan 1, 1904.

property year: int: The year.

property month: int: The month, between 1 and 12 inclusive.

property day: int: The day of the month, between 1 and 31 inclusive.

property hour: int: The hour, between 0 and 23 inclusive.

property minute: int: The minute, between 0 and 59 inclusive.

property second: int: The second, between 0 and 59 inclusive.

property microsecond: int: The microsecond, between 0 and 999_999 inclusive.

property femtosecond: int: The femtosecond, between 0 and 999_999_999 inclusive.

property yoctosecond: int: The yoctosecond, between 0 and 999_999_999 inclusive.

Warning

Because this class uses a 64-bit binary fraction, the smallest time increment it can represent is 1.0 / (1 << 64) seconds, which is about 54210 yoctoseconds.

property ticks: int: The number of ticks since the epoch, Jan 1, 1904.

property tzinfo: datetime.tzinfo | None: The time zone.

to_tuple() → nitypes.bintime.TimeValueTuple: Convert to the number of whole and fractional seconds since the epoch, Jan 1, 1904.

classmethod now(tz: datetime.tzinfo | None = None) → typing_extensions.Self: Return the current absolute time.

__add__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) → DateTime: Return self+value.

__radd__

__sub__(value: DateTime | _OtherDateTime, /) → nitypes.bintime.TimeDelta
__sub__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) → DateTime: Return self-value.

__rsub__(value: DateTime | _OtherDateTime, /) → nitypes.bintime.TimeDelta
__rsub__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) → DateTime: Return value-self.

__lt__(value: DateTime | _OtherDateTime, /) → bool: Return self<value.

__le__(value: DateTime | _OtherDateTime, /) → bool: Return self<=value.

__eq__(value: object, /) → bool: Return self==value.

__gt__(value: DateTime | _OtherDateTime, /) → bool: Return self<value.

__ge__(value: DateTime | _OtherDateTime, /) → bool: Return self>=value.

__hash__() → int: Return hash(self).

__reduce__() → tuple[Any, Ellipsis]: Return object state for pickling.

__str__() → str: Return repr(self).

__repr__() → str: Return repr(self).