feat: add special datatype for timestamp

[nankolena]

Linked issue(s)

Towards KOL-3547. Backend and frontend changes are WIP.

What change does this PR introduce and why?

Create a new data type class for timestamp, as SPECIAL/TIMESTAMP

Users can either create a timestamp object using a float epoch time (Timestamp(epoch_time=1735689600)), or a string along with its format (Timestamp(value="12/31/2024, 00:00:00", format="%m/%d/%Y, %H:%M:%S"). For the latter, the Kolena client would convert the timestamp into the epoch float time in order to be used to filter/sort on Kolena. Unless an offset such as GMT-05:00 is specified, these timestamps are assumed to be in GMT timezone.

For now, leave the special data classes under experimental. Screenshot of the generated API reference is attached below:

Please check if the PR fulfills these requirements

• Include reference to internal ticket and/or GitHub issue "Fixes #NNNN" (if applicable)
• Relevant tests for the changes have been added
• Relevant docs have been added / updated

[yifanwu-kolena]

in my understanding we only need this tz for line 80, could we set it at the func calling side like from datetime import timezone; datetime.strptime(self.value, self.format).replace(tzinfo=timezone.utc).timestamp() for better locality?

[nankolena]

Yea that was my initial approach, but it turned out that .replace() will strip out the timezone info in the input string and lead to incorrect epoch time. In the following, this call basically just ignores the input timezone:

[nankolena]

Let me know what you think of this commit. I agree that manipulating os is bad practice and at the same time did not want to introduce new dependencies for this alone. Looking at the python doc:

Changed in version 3.2: When the %z directive is provided to the strptime() method, an aware datetime object will be produced. The tzinfo of the result will be set to a timezone instance.

The change is to simply check for presence of %z and append it to the string if not exists

[yifanwu-kolena]

thanks for the detailed explanation, i like the changes

[munkyshi]

This feels a bit strict -- was there a reason we didn't do a best guess attempt at parsing with python-dateutil + just default to a display format?

[nankolena]

Agreed that this can be one of the next steps to improve the experience, and our focus so far has been to support timestamp across the platform. Before using something like python-dateutil we'll want to validate across different use cases and make sure that it results in the correct epoch time.