nitypes.bintime.DateTime ======================== .. py:class:: nitypes.bintime.DateTime DateTime(value: _OtherDateTime, /) 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 :any:`datetime.datetime` and :any:`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 :any:`datetime.datetime`, you can construct a :class:`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:: :class:`DateTime` only supports :any:`datetime.timezone.utc`. It does not support time-zone-naive objects or time zones other than UTC. You can also construct a :class:`DateTime` from a :any:`datetime.datetime` or :any:`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 :any:`DateTime.now`: >>> DateTime.now(datetime.timezone.utc) # doctest: +ELLIPSIS nitypes.bintime.DateTime(...) Properties ^^^^^^^^^^ Like other ``datetime`` objects, :class:`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 :any:`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 :any:`datetime.datetime`. However, :any:`hightime.datetime` has even higher resolution: ======================== ================================ Class Smallest Time Increment ======================== ================================ :any:`datetime.datetime` 1 microsecond (1e-6 sec) :class:`DateTime` 54210 yoctoseconds (5.4e-20 sec) :any:`hightime.datetime` 1 yoctosecond (1e-24 sec) ======================== ================================ As a result, :any:`hightime.datetime` can represent the time down to the exact yoctosecond, but :class:`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) # doctest: +NORMALIZE_WHITESPACE 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) # doctest: +NORMALIZE_WHITESPACE nitypes.bintime.DateTime(2025, 1, 1, 0, 0, 0, 99, 999999999, 999991239, tzinfo=datetime.timezone.utc) Class members ^^^^^^^^^^^^^ .. py:attribute:: min :type: ClassVar[DateTime] The earliest supported :class:`DateTime` object, midnight on Jan 1, 0001, UTC. .. py:attribute:: max :type: ClassVar[DateTime] The latest supported :class:`DateTime` object, before midnight on Dec 31, 9999, UTC. .. py:attribute:: __slots__ :value: ['_offset', '_hightime_cache'] .. py:method:: from_ticks(ticks: SupportsIndex) -> typing_extensions.Self :classmethod: Create an DateTime from a 128-bit fixed point number expressed as an integer. .. py:method:: from_tuple(value: nitypes.bintime.TimeValueTuple) -> typing_extensions.Self :classmethod: Create a DateTime from whole and fractional seconds as 64-bit ints. .. py:method:: from_offset(offset: nitypes.bintime.TimeDelta) -> typing_extensions.Self :classmethod: Create an DateTime from a TimeValue offset from the epoch, Jan 1, 1904. .. py:property:: year :type: int The year. .. py:property:: month :type: int The month, between 1 and 12 inclusive. .. py:property:: day :type: int The day of the month, between 1 and 31 inclusive. .. py:property:: hour :type: int The hour, between 0 and 23 inclusive. .. py:property:: minute :type: int The minute, between 0 and 59 inclusive. .. py:property:: second :type: int The second, between 0 and 59 inclusive. .. py:property:: microsecond :type: int The microsecond, between 0 and 999_999 inclusive. .. py:property:: femtosecond :type: int The femtosecond, between 0 and 999_999_999 inclusive. .. py:property:: yoctosecond :type: 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. .. py:property:: ticks :type: int The number of ticks since the epoch, Jan 1, 1904. .. py:property:: tzinfo :type: datetime.tzinfo | None The time zone. .. py:method:: to_tuple() -> nitypes.bintime.TimeValueTuple Convert to the number of whole and fractional seconds since the epoch, Jan 1, 1904. .. py:method:: now(tz: datetime.tzinfo | None = None) -> typing_extensions.Self :classmethod: Return the current absolute time. .. py:method:: __add__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) -> DateTime Return self+value. .. py:attribute:: __radd__ .. py:method:: __sub__(value: DateTime | _OtherDateTime, /) -> nitypes.bintime.TimeDelta __sub__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) -> DateTime Return self-value. .. py:method:: __rsub__(value: DateTime | _OtherDateTime, /) -> nitypes.bintime.TimeDelta __rsub__(value: nitypes.bintime.TimeDelta | nitypes.bintime._timedelta._OtherTimeDelta, /) -> DateTime Return value-self. .. py:method:: __lt__(value: DateTime | _OtherDateTime, /) -> bool Return self bool Return self<=value. .. py:method:: __eq__(value: object, /) -> bool Return self==value. .. py:method:: __gt__(value: DateTime | _OtherDateTime, /) -> bool Return self bool Return self>=value. .. py:method:: __hash__() -> int Return hash(self). .. py:method:: __reduce__() -> tuple[Any, Ellipsis] Return object state for pickling. .. py:method:: __str__() -> str Return repr(self). .. py:method:: __repr__() -> str Return repr(self).