FEAT: Complex Data Type Support - DATETIMEOFFSET

[gargsaumya]

Work Item / Issue Reference

AB#34944

GitHub Issue: #<ISSUE_NUMBER>

---

Summary

This pull request adds comprehensive support for the SQL Server DATETIMEOFFSET type in the driver, including full round-trip handling of timezone-aware Python datetime objects. The changes span the C++ bindings, Python type mapping, and test coverage to ensure correct reading and writing of DATETIMEOFFSET values, as well as validation for timezone information.

DATETIMEOFFSET support in C++ bindings:

• Defined new constants and a DateTimeOffset struct in ddbc_bindings.cpp to represent and handle the SQL Server DATETIMEOFFSET type and its C type mapping (SQL_SS_TIMESTAMPOFFSET, SQL_C_SS_TIMESTAMPOFFSET). [1] [2]
• Implemented logic in parameter binding to convert Python timezone-aware datetime objects into the DateTimeOffset struct, including extracting and validating timezone offsets. Naive datetimes are rejected for this type.
• Added logic to fetch DATETIMEOFFSET values from the database and convert them back into Python datetime objects with the correct timezone information.

Python type mapping and constants:

• Added SQL_DATETIMEOFFSET and SQL_C_SS_TIMESTAMPOFFSET to the driver's constants in constants.py.
• Updated the cursor's type mapping logic to use DATETIMEOFFSET for timezone-aware datetime objects, and TIMESTAMP for naive ones.

Testing improvements:

• Introduced a new test, test_datetimeoffset_read_write, which verifies correct round-trip handling of DATETIMEOFFSET values, including various timezone offsets and microsecond precision, and ensures that naive datetimes are rejected.
• Added necessary imports for timezone handling in the test module.

These changes ensure that the driver now robustly supports SQL Server's DATETIMEOFFSET type, providing accurate and safe handling of timezone-aware datetimes between Python and the database.

[Copilot]

Pull Request Overview

This PR adds comprehensive support for SQL Server's DATETIMEOFFSET type in the Python driver, enabling proper handling of timezone-aware datetime objects. The implementation includes C++ bindings, Python type mapping, and comprehensive test coverage.

• Adds DateTimeOffset struct and constants for handling SQL Server DATETIMEOFFSET type
• Implements parameter binding and data retrieval logic for timezone-aware datetime objects
• Updates cursor type mapping to distinguish between timezone-aware and naive datetime objects

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
ddbc_bindings.cpp	Implements C++ binding logic for DATETIMEOFFSET including struct definition, parameter binding, and data retrieval
cursor.py	Updates type mapping to use DATETIMEOFFSET for timezone-aware datetime objects
constants.py	Adds SQL_DATETIMEOFFSET and SQL_C_SS_TIMESTAMPOFFSET constants
test_004_cursor.py	Adds comprehensive test coverage for DATETIMEOFFSET round-trip functionality

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[sumitmsft]

Added a couple of comments

[bewithgaurav]

minor formatting changes under tests