Add TimestampInterpretation for flexible timestamp parsing

[doziestar]

Description

I added a new TimestampInterpretation enum and updates the TimeConfig to allow us specify how timestamps should be interpreted. This change provides more flexibility in parsing timestamps, especially for systems that may receive timestamps in different formats.

Changes

1. Added TimestampInterpretation enum with Auto and AlwaysSeconds variants.
2. Updated TimeConfig to include a timestamp_interpretation field.
3. Modified TimeConfigBuilder to allow setting the timestamp_interpretation.
4. Updated DateTime::from_timestamp_with_config to handle different interpretation modes.

How to Use

Setting up TimeConfig with TimestampInterpretation

Anyone can now specify how they want timestamps to be interpreted when creating a TimeConfig:

use speedate::{TimeConfigBuilder, TimestampInterpretation};

// Auto mode (default behavior)
let auto_config = TimeConfigBuilder::new()
    .timestamp_interpretation(TimestampInterpretation::Auto)
    .build();

// Always interpret as seconds
let always_seconds_config = TimeConfigBuilder::new()
    .timestamp_interpretation(TimestampInterpretation::AlwaysSeconds)
    .build();

// This will be interpreted as milliseconds in `Auto` mode
let auto_dt = DateTime::from_timestamp_with_config(1654619320123, 0, &auto_config).unwrap();
assert_eq!(auto_dt.to_string(), "2022-06-07T16:28:40.123000");

// This will be interpreted as seconds in `AlwaysSeconds` mode
// Please Take Note: This might result in a `DateTooLarge` error for very large timestamps
let always_seconds_dt = DateTime::from_timestamp_with_config(1654619320, 0, &always_seconds_config).unwrap();
assert_eq!(always_seconds_dt.to_string(), "2022-06-07T16:28:40");
   

Notes

• The Auto mode behaves like the previous implementation, automatically detecting if a timestamp is in seconds or milliseconds based on its magnitude.
• The AlwaysSeconds mode always interprets the timestamp as seconds, which may result in DateTooLarge errors for timestamps that would previously have been interpreted as milliseconds.

[codecov]

Codecov Report

Attention: Patch coverage is 97.43590% with 1 line in your changes missing coverage. Please review.

Files	Patch %	Lines
src/time.rs	97.14%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[davidhewitt]

Thanks very much for working on this, overall looks great!

I have a few thoughts around the position of the config and some changes we can probably skip...

[davidhewitt]

I think here we don't need to handle this case, as the limit of valid input is 86,400 seconds, i.e 86,400,000 milliseconds which is less than 20,000,000,000.

So my reading is that valid input here will always be treated as seconds anyway.

(A comment saying why we don't use timestamp_interpretation here might be useful.)

[doziestar]

You are right @davidhewitt, I will fix that

[davidhewitt]

Because of the limit of valid input I think the original u32 input made more sense.

Suggested change

	timestamp: i64,
	timestamp: u32,

[doziestar]

working on it

[davidhewitt]

It feels to me like this is actually config for DateTime, not Time.

So I suggest we make a DatetimeConfig { time_config: TimeConfig, timestamp_interpretation: TimestampInterpretation } in datetime.rs

It might also be worth trying out this branch against pydantic-core to see how painful it is to adjust to needing a different DatetimeConfig type.

[doziestar]

Thank you for the suggestion, @davidhewitt. I'll implement the DatetimeConfig in datetime.rs and aim to ensure backward compatibility. I'll test this branch against pydantic-core and update you on the results.