Combine Timestamp and Timezone into a Single CPython Object for Timezone-Aware Timestamps [

[Earammak]

Feature or enhancement

Proposal:

Currently, in CPython, we have two separate objects to handle timestamps and timezones, but there is no single object that combines both concepts into one coherent representation of a "timestamp with timezone."

1. Timestamp: The PyDateTime_FromDateAndTime function is used to create timestamp objects from date and time components. This function takes in year, month, day, hour, minute, second, and microsecond parameters to represent a point in time, but it does not inherently associate the timestamp with a specific timezone.
   Reference: PyDateTime_FromDateAndTime

2. Timezone: The PyDateTime_TZInfoType represents the Python tzinfo class and allows the creation and management of time zone information. It is used in conjunction with datetime objects to make them timezone-aware by associating them with a specific time zone (e.g., UTC offset).
   Reference: PyDateTime_TZInfoType

However, these two objects, while related, are separate and currently cannot be combined into a single object that represents a "timestamp with timezone." As a result, users are forced to manually pair a timestamp object with a timezone object, which leads to inefficiency and complexity when working with timezone-aware timestamps.

Expected Behavior: We propose an enhancement to allow for the creation of a single CPython object that combines both the timestamp and its associated timezone information. This object would encapsulate both the date-time (timestamp) and the tzinfo object, making it possible to represent a complete timestamp with timezone in a single C API object.

Below is structure used for timestamp with timezone:

struct TIMESTAMP_STRUCT_EXT_TZ
{
SQLSMALLINT year;
SQLUSMALLINT month;
SQLUSMALLINT day;
SQLUSMALLINT hour;
SQLUSMALLINT minute;
SQLUSMALLINT second;
SQLUINTEGER fraction; /* 1-9 digits fractional /
/ seconds /
SQLUINTEGER fraction2; / 10-12 digits fractional /
/ seconds /
SQLSMALLINT timezone_hour; / -12 to 14 /
SQLUSMALLINT timezone_minute; / 0 to 59 */
} TIMESTAMP_STRUCT_EXT_TZ;

For example, a single object could represent a timezone-aware timestamp like:
2025-01-10 12:00:00+03:00

This object should:
Allow users to create a timestamp with timezone by combining the functionality of PyDateTime_FromDateAndTime and PyDateTime_TZInfoType.
Provide access to both the timestamp and its associated timezone information through a unified object.
Allow easy manipulation of the timezone-aware timestamp, such as adjusting for daylight saving time or converting to different timezones.

Use Case:
Users would be able to create a timezone-aware timestamp object in a single step, avoiding the need to separately create a datetime object and a tzinfo object.
This would simplify working with time zone-aware dates and times, particularly in scenarios where both the timestamp and time zone information need to be manipulated together.
Example
// Pseudocode for creating a timezone-aware timestamp object
PyObject *timezone_aware_timestamp = PyDateTime_FromTimestampWithTimezone(
2025, 1, 10, 12, 0, 0, 0, // year, month, day, hour, minute, second, microsecond
timezone_obj // timezone object (e.g., UTC+3)
);

This enhancement would provide a more natural and unified API for handling timezone-aware timestamps and improve the ease of use when working with datetime objects in C extensions.
Motivation:
Efficiency: Reduces the need for users to manually combine separate timestamp and timezone objects.

Consistency: Provides a more Pythonic and seamless way to work with timezone-aware timestamps.
Usability: Simplifies code by allowing a single object to represent both the timestamp and its associated timezone, reducing potential for errors and confusion.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

[ZeroIntensity]

Hi, please don't use LLMs to generate feature proposals. This is large enough that it should have it's own thread on DPO first. My initial concerns are:

• Why make this specific to the C API? The better candidate would be the datetime module, and then it could move to the C API.
• Either way, why can't you implement this object yourself? Or, why can't you use the pytz library?
• I haven't done too deep of a search, but I suspect you're not the first person to bring this up. There are two similar DPO threads that I found: https://discuss.python.org/t/get-now-with-local-system-timezone-without-knowing-the-timezone-first/22665 and https://discuss.python.org/t/datetime-api-no-atomic-way-to-get-aware-current-local-datetime-when-moving-between-time-zones/55041/

I'm going to close this for now. If things go well on discourse, please open a new issue with human-written text so it's more clear what the actual proposal is.