Return TIMESTAMP types as timezone-aware native Python datetime objects

[amotl]

About

When requested, make the driver return timezone-aware native Python datetime objects for CrateDB's TIMESTAMP types. The user can easily supply the desired time zone by different means.

Rationale

@mfussenegger asked at #442 (review):

I think something common like setting the timezone for datetime objects could be made even easier for users.

I shared some initial thoughts about it at #442 (review) ff., and finally settled with this implementation, separately from the baseline implementation for the data type converter.

Details

This patch adds additional convenience based on the data type converter machinery added with #442.

• A time_zone keyword argument can be passed to both the connect() method, or when creating new Cursor objects.
• The time_zone attribute can also be changed at runtime on both the connection and cursor object instances.

Different ways to populate the time_zone value are supported. Some examples::

• datetime.timezone.utc
• datetime.timezone(datetime.timedelta(hours=7), name="MST")
• pytz.timezone("Australia/Sydney")
• zoneinfo.ZoneInfo("Australia/Sydney")
• +0530 (UTC offset in string format)

Acknowledgements

This interface was inspired by the DBAPI drivers for MySQL and Elasticsearch. Thanks.

• https://dev.mysql.com/doc/connector-python/en/connector-python-api-mysqlconnection-time-zone.html
• https://github.com/preset-io/elasticsearch-dbapi#time-zone

Synopsis

Use time_zone argument when creating a new connection. Here, use a pytz.timezone object.

>>> import pytz
>>> from crate.client import connect

>>> connect("localhost:4200", time_zone=pytz.timezone("Australia/Sydney"))
>>> cursor = connection.cursor()
>>> cursor.execute(stmt)
>>> cursor.fetchone()
['foo', datetime.datetime(2022, 7, 19, 4, 10, 36, 758000, tzinfo=<DstTzInfo 'Australia/Sydney' AEST+10:00:00 STD>)]

Use time_zone argument when creating a new cursor. Here, use an UTC offset string.

>>> from crate.client import connect

>>> connection = connect("localhost:4200")
>>> cursor = connection.cursor(time_zone="+0530")
>>> cursor.execute(stmt)
>>> cursor.fetchone()
['foo', datetime.datetime(2022, 7, 18, 23, 40, 36, 758000, tzinfo=datetime.timezone(datetime.timedelta(seconds=19800), '+0530'))]

References

• Return TIMESTAMP columns as native Python datetime objects to improve support for Apache Superset #395
• Improve compatibility with Apache Superset by showing CrateDB table metadata in the SQL Lab editor #426
• Followup: Return TIMESTAMP columns as native Python datetime objects #437
• Add a generic data type converter to the Cursor object #442

Backlog

• For bringing this functionality to the SQLAlchemy dialect, https://github.com/spoqa/sqlalchemy-utc may be of interest.

[matriv]

Thank you! It looks good, I have some comments around docs.

[amotl]

Dear Marios,

I've added some commits and hopefully addressed your suggestions well. Please let me know about anything missing, or where the patch could be improved further.

With kind regards,
Andreas.

[matriv]

LGTM. thank you! Left a comment about a test method name.