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.

[Seneral]

Came across this, not sure if OP is AI generated or whatever, but it would be a very useful feature.
Currently a library I use (VRPN) returns non-timezone-aware timestamps, and without specifying the timezones explicitly in my python code, this results in silent errors (timedelta offset by X hours). The worst kind of errors.
Afaik currently there's nothing the library can do to fix this. The user has to remember to explicitly specify the timezone (UTC in this case) for their own objects, and convert the timestamp received from the library to be timezone-aware:

time_now = datetime.now(timezone.utc)
timestamp = received_timestamp.replace(tzinfo=timezone.utc);
dt = (time_now - timestamp) / timedelta(seconds=1)

As a novice python user, I could really have done without that friction point.