Use of standard vs. timezone-aware date types

[DaveSkender]

A user raised a valid point about needing timezone awareness or offsets. I appreciate the opportunity to discuss further and to get community feedback. Let me explain the current approach of using the simpler form of DateTime and the rationale behind it.

Why we use plain datetime data types

1. Industry norms: Financial market data is typically timestamped relative to the exchange's local timezone and rarely includes timezone offsets. For example:

   • NYSE and NASDAQ data is generally in U.S. Eastern Time without explicit offsets.
   • Many data feeds rely on users to know the context and handle any timezone normalization themselves.

   Given this, plain datetime objects align with the majority of use cases and data sources.

2. Performance and simplicity: timezone-aware types (e.g., DateTimeOffset in .NET or datetime with tzinfo in Python) add overhead in terms of size, computation, and complexity. For a performance-focused library, this trade-off is significant, especially when handling large datasets.

3. User-controlled normalization: The library assumes that users normalize data (e.g., to UTC) in their pre-processing pipelines. This keeps the library lightweight and focused on its core purpose—calculations and indicators.

Addressing concerns

We do recognize that timezone-aware dates could benefit use cases involving multiple exchanges or explicit timezone handling. However, introducing timezone support across the library would require careful consideration to avoid unintended side effects, such as increased memory usage, reduced performance, or breaking existing user workflows.

Possible Next Steps

• Community input: If you feel this feature would significantly enhance the library, let’s continue the conversation in this discussion. We’d love to understand more about your use cases and see if others in the community share this need.
• Custom extensions: One potential approach could be adding optional timezone support as an opt-in feature, where users explicitly enable it for their data. This would allow advanced use cases without impacting the majority of users.
• Documentation updates: To help users avoid unexpected behavior, we could improve documentation to emphasize that input datetime objects are treated as plain and recommend normalizing to UTC before passing them into the library.

Originally suggested by @goulashsoup in a bug report for our Python library

[goulashsoup]

The library assumes that users normalize data (e.g., to UTC) in their pre-processing pipelines.

That is a valid approach that not only keeps performance, but also unifies the usage of the library across projects: If we only allow UTC-times, there are no more questions and possible bugs because of different time zones.

@DaveSkender I also suggest to add a UTC timezone check to Quote and similar classes for the next major version...

[DaveSkender]

I see where you're coming from, but my point was more about emphasizing that timezone information is irrelevant when the library should simply passes through date-in/date-out without altering or interpreting it.

Requiring a specific timezone for all inputs might impose unnecessary constraints on users, especially when some workflows don't need timezone specifications at all.

For the issue you raised in your bug report, my focus is on ensuring the library doesn’t lose any date-related information, while keeping things as flexible and straightforward as possible for diverse use cases.

[beratdogan]

Hi @DaveSkender, impressive analysis! I couldn't see any updates in other related discussions as well. This one still impacts my workflow I really would appreciate giving another look for this one.

I don't have enough knowledge on the .NET implementation. Thus, I didn't look in the original implementation. Just as a user's perspective, it feels it should be handled in the .NET implementation. As I understand in the draft MR, retraining timezone awareness in Python "bridge" might add some overload as you have already mentioned.

According to my observation, .NET-side converts the time by the host's timezome to host's timezone but also is aware of the timezone. To work with the library I had to apply my utility function to return values of the indicators. As you can imagine it creates difficulties while working with the library.

from datetime import datetime as dt, timezone as tz

from stock_indicators._cstypes import DateTime as CsDateTime
from stock_indicators._cslib import CsCultureInfo


local_tz = dt.now(tz.utc).astimezone().tzinfo
def make_tz_aware(date: dt):
    return date.replace(tzinfo=local_tz).astimezone(tz.utc)


py_now = dt.now(tz=tz.utc)
print('py_now', py_now)

cs_now = CsDateTime(py_now)
print('cs_now', cs_now)

cs_now_tz_naive = cs_now.ToString("s", CsCultureInfo.InvariantCulture)
print('cs_now_tz_naive', cs_now_tz_naive)
print('cs_now_tz_naive_processed', make_tz_aware(dt.fromisoformat(cs_now_tz_naive)))

cs_now_tz_aware = cs_now.ToString("o", CsCultureInfo.InvariantCulture)
print('cs_now_tz_aware', cs_now_tz_aware)
print('cs_now_tz_aware_processed', make_tz_aware(dt.fromisoformat(cs_now_tz_aware)))

Logs

py_now 2025-02-22 18:10:13.714752+00:00
cs_now 2/22/2025 9:10:13 PM
cs_now_tz_naive 2025-02-22T21:10:13
cs_now_tz_naive_processed 2025-02-22 18:10:13+00:00
cs_now_tz_aware 2025-02-22T21:10:13.7147520+03:00
cs_now_tz_aware_processed 2025-02-22 18:10:13.714752+00:00

I believe expected behaviour should be the exactly what's given as input. Looking forward to any improvements on this issue.

[DaveSkender]

I haven't had much time lately to look deeply at this issue.

Converting to a specific date format isn't really the problem.

As a test-driven case, I'd like to have any date format provided (for the quotes), run an indicator, and have the results output with dates that (a) didn't add an assumption about timezone or (b) remove any information from the original dates. Whether the dates are output in a slightly different standard format isn't a primary concern, as long as it's not effectively altering the date. If that makes sense.

If you have time to do a PR with a mod and unit test(s), we'd love to see it.