feat: Add ability to use datetime objects or time-shift strings in TimestampRange

[MortGron]

Description

Let TimestampRange objects accept datetime objects as arguments. The motivation fot this is that it is a very common use pattern that users convert datetime objects to timestamps before making TimestampRange objects.

Checklist:

• Tests added/updated.
• Documentation updated. Documentation is generated from docstrings - these must be updated according to your change.
  If a new method has been added it should be referenced in cognite.rst in order to generate docs based on its docstring.
• The PR title follows the Conventional Commit spec.

[gemini-code-assist]

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.29%. Comparing base (1afc695) to head (f985c1f).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2432      +/-   ##
==========================================
+ Coverage   91.27%   91.29%   +0.02%     
==========================================
  Files         192      192              
  Lines       26190    26192       +2     
==========================================
+ Hits        23905    23913       +8     
+ Misses       2285     2279       -6     

Files with missing lines	Coverage Δ
cognite/client/data_classes/shared.py	93.44% <100.00%> (+0.22%)	⬆️

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[MortGron]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a useful enhancement by allowing datetime objects to be used in TimestampRange. The implementation is sound and includes corresponding tests. My review focuses on improving code style and consistency by addressing import ordering and ensuring the consistent use of timezone-aware datetime objects in tests, in line with the repository's style guide.

[MortGron]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds a convenient feature by allowing datetime objects to be used in TimestampRange. The implementation is a good start, but it contains a critical issue related to handling timezone-naive datetime objects, which could lead to incorrect timestamps and subtle bugs. I have provided a comment with a suggested fix to enforce the use of timezone-aware datetime objects, ensuring data correctness.

[gemini-code-assist]

The current implementation for converting datetime objects to timestamps is vulnerable to timezone-related bugs. The datetime.timestamp() method uses the system's local timezone for naive datetime objects (those without tzinfo). This can result in incorrect millisecond timestamps if the code is run on a machine not set to UTC, as the Cognite API expects UTC timestamps.

To prevent incorrect data from being sent to the API, you should enforce that any provided datetime object is timezone-aware. Raising a ValueError for naive datetime objects is the safest approach.

I also recommend updating the docstrings for min and max to clarify that datetime objects must be timezone-aware.

Suggested change

	self.max = int(max.timestamp() * 1000) if isinstance(max, datetime) else max
	self.min = int(min.timestamp() * 1000) if isinstance(min, datetime) else min
	if isinstance(max, datetime):
	if max.tzinfo is None:
	raise ValueError("datetime object for 'max' must be timezone-aware.")
	self.max = int(max.timestamp() * 1000)
	else:
	self.max = max
	if isinstance(min, datetime):
	if min.tzinfo is None:
	raise ValueError("datetime object for 'min' must be timezone-aware.")
	self.min = int(min.timestamp() * 1000)
	else:
	self.min = min

References

1. The style guide emphasizes specific exceptions and graceful error handling. Passing a naive datetime can lead to incorrect behavior, so raising a ValueError for this invalid input is appropriate to ensure data integrity. ^(link)

[MortGron]

@cognitedata/python-sdk-maintainers what do you think? Personally I think the SDK should be consistent, either enforcing timezone awareness or not.

[haakonvt]

@MortGron you can check in utils/_time.py for existing conversion functions. I vote to be strict on timezone, or at least throw a warning when naive. This PR won't be accepted until v8 is out btw.

[MortGron]

Thanks for the suggestion about the utils module! What do you think about letting the utils functions in the _time.py handle timezone enforcement or warnings?

[haakonvt]

Knock yourself out 👌