_convert_to_desired_timezone loses hightime accuracy for DST conversions

[bkeryan]

Bug Report

The type hint for _convert_to_desired_timezone indicates that it may return either a datetime.datetime or a hightime.datetime:

def _convert_to_desired_timezone(
    expected_time_utc: std_datetime | ht_datetime, tzinfo: dt_tzinfo | None = None
) -> std_datetime | ht_datetime:

This is true, but callers expect it to return a hightime.datetime:

    def to_datetime(  # noqa: D102 - Missing docstring in public method (auto-generated noqa)
        self, tzinfo: dt_tzinfo | None = None
    ) -> ht_datetime:
        total_yoctoseconds = int(
            round(AbsoluteTime._YS_PER_S * self.lsb / AbsoluteTime._NUM_SUBSECONDS)
        )
        dt = (
            AbsoluteTime._EPOCH_1904
            + ht_timedelta(seconds=self.msb)
            + ht_timedelta(yoctoseconds=total_yoctoseconds)
        )
        return _convert_to_desired_timezone(dt, tzinfo)

This case in particular does not preserve hightime accuracy:

    # use ZoneInfo here to account for daylight savings
    if isinstance(tzinfo, ZoneInfo):
        localized_time = expected_time_utc.replace(tzinfo=tzinfo)
        desired_expected_time = tzinfo.fromutc(localized_time)
        return desired_expected_time

tzinfo.fromutc() is a method of the tzinfo class and it doesn't know about our subclass hightime.datetime.

Repro or Code Sample

#858

Expected Behavior

Mypy passes with hightime type hints.

Current Behavior

generated/nidaqmx/_time.py:32: error: Unsupported operand types for + ("datetime" and "None")  [operator]
generated/nidaqmx/_time.py:32: note: Both left and right operands are unions
generated/nidaqmx/_lib_time.py:69: error: Incompatible return value type (got "datetime.datetime", expected "hightime._datetime.datetime")  [return-value]
generated/nidaqmx/_grpc_time.py:56: error: Incompatible return value type (got "datetime.datetime", expected "hightime._datetime.datetime")  [return-value]
tests/component/stream_readers/test_digital_single_channel_reader.py:228: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:247: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:264: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:282: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:299: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:316: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:419: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:472: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:491: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:529: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_single_channel_reader.py:567: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:349: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:378: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:386: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:395: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:431: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:438: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:446: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:458: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:512: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:537: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:617: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:712: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
tests/component/stream_readers/test_digital_multi_channel_reader.py:768: error: Argument 1 to "_is_timestamp_close_to_now" has incompatible type "Union[DateTime, datetime.datetime]"; expected "hightime._datetime.datetime"  [arg-type]
Found 27 errors in 5 files (checked 219 source files)

Context

#858

Your Environment

• Operating system and version: N/A
• NI-DAQmx version: N/A
• nidaqmx-python version: master
• Python version: N/A

AB#3439749

[bkeryan]

I am changing the function return type to hightime.datetime in #861
since that's what all of its callers want, and I am adding a type: ignore to work around this bug (#860).

The fix for #860 should remove the type: ignore and make the code return an actual hightime.

[bkeryan]

BTW, https://github.com/ni/nidaqmx-python/blob/master/tests/unit/test_lib_time.py has one convert_to_timestamp_with_dst test, which does not use femtoseconds. When fixing this, we should add a test case for DST + femtoseconds.