feat: Support creating timestamp arrays

[surister]

Fixes #459

With this PR we now support creating arrays with precission and timezone support:

from datetime import datetime, timezone
from arro3.core import Array, DataType

a = Array([datetime.now()], type=DataType.timestamp("ns"))
b = Array([datetime.now(tz=timezone.utc)], type=DataType.timestamp("s", tz="UTC"))
tz_name = "America/Chicago"
tzinfo = zoneinfo.ZoneInfo(tz_name)
expected: datetime = datetime.now().astimezone(timezone(tzinfo.utcoffset(datetime.now())))
c = Array([expected], type=DataType.timestamp("ms", tz=tz_name))
print(a, b, c)

arro3.core.Array<Timestamp(ns)>
[
  2025-12-05T16:47:26.094894,
]
 arro3.core.Array<Timestamp(s, "UTC")>
[
  2025-12-05T15:47:26Z,
]
 arro3.core.Array<Timestamp(ms, "America/Chicago")>
[
  2025-12-05T09:47:26.095-06:00,
]

[kylebarron]

Thanks for the PR! I think there are a few more test cases I'd like to see:

• Passing an array of tz-aware datetimes, each with a separate timezone
• Passing an array of partially tz-aware datetimes, some with a naive timezone
• Passing an array of tz-aware datetimes where the type passed has a naive timezone (not sure what happens here, maybe check pyarrow)
• Passing an array of tz-aware datetimes where the passed type has a tz that is not the same as the datetimes that are passed in
• Having partial and full nulls in the input array

Perhaps each of these test cases could also use the pyarrow constructor, so we know we're consistent with them

[kylebarron]

This says that if the type passed in doesn't have a tz, then ignore any tz passed with the input data. That seems easily wrong if we have a variety of timezones in our array of input timestamps; I'm curious how pyarrow handles this

[surister]

It does not ignore it, everything is converted to chrono::NaiveDateTime, so if there is a dt with tz it errors out:

dt = datetime(1999, 8, 7, 11, 12, 13, 141516)
tzinfo = zoneinfo.ZoneInfo('Europe/Madrid')
dt2: datetime = dt.astimezone(timezone(tzinfo.utcoffset(dt)))

arr = Array([dt, None, dt2], type=DataType.timestamp("ms"))
# E       TypeError: expected a datetime without tzinfo

In pyarrow it seems to work this way:

Same datetime, one has a tz and array type is tz

dt = datetime(1999, 8, 7, 11, 12, 13, 141516)
tzinfo = zoneinfo.ZoneInfo('Europe/Madrid')
dt2: datetime = dt.astimezone(timezone(tzinfo.utcoffset(dt)))
arr = pyarrow.array([dt, None, dt2], type=pyarrow.timestamp('ms', 'Europe/Madrid'))
print(arr.type)

It does not error out:

[
  1999-08-07 11:12:13.141Z,
  null,
  1999-08-07 09:12:13.141Z
]
timestamp[ms, tz=Europe/Madrid]

It applies the given tz to all dates.

Back to python:

[
    datetime.datetime(1999, 8, 7, 13, 12, 13, 141000, tzinfo=<DstTzInfo 'Europe/Madrid' CEST+2:00:00 DST>),
    None,
    datetime.datetime(1999, 8, 7, 11, 12, 13, 141000, tzinfo=<DstTzInfo 'Europe/Madrid' CEST+2:00:00 DST>)
]

Both have applied tz.

Same datetime, one has tz and array type does not have tz

[
    datetime.datetime(1999, 8, 7, 11, 12, 13, 141516),
    None, 
    datetime.datetime(1999, 8, 7, 9, 12, 13, 141516)
]

Both dates are still as is, but tz information is now lost.

So I guess the expected functionality would be to apply the given tz to all dates, if no tz exists just take the dates as is.

[kylebarron]

It does not error out:

[
  1999-08-07 11:12:13.141Z,
  null,
  1999-08-07 09:12:13.141Z
]
timestamp[ms, tz=Europe/Madrid]

That feels wrong...? You have two input datetimes that represent the same time. And when they are returned to Python they have the same time. But displayed from Rust they are displayed as different.

Edit: I didn't see that back in Python they are different

[kylebarron]

We should probably the case where nanosecond timestamps overflow and error instead of panic

[surister]

Thinking about this again, can this actually ever overflow? DataType.timestamp coerces things into datetime objects:

arr = Array([18_446_744_073_709_551_61, None], type=DataType.timestamp("ns"))
# E       TypeError: 'int' object cannot be cast as 'datetime'

And datetime objects support max precision of 6 digits (microseconds), so can we actually create an object with precision ns that actually hits that branch? Perhaps we can delete it altogether?

[surister]

Came to me as I hit comment, we can cast from a u64 and that'll have ns precission.

arr = Array([18_446_744_073_709_551_61, None], type=DataType.uint64()).cast(DataType.timestamp("ns"))
print(arr)

[
  2028-06-15T09:33:27.370955161,
  null,
]

[surister]

Btw, it does not panic when there is an overflow:

arr = Array([18_446_744_073_709_551_610, None], type=DataType.uint64()).cast(DataType.timestamp("ns"))
print(arr)

It just nulls it:

[
  null,
  null,
]

So what do we do with nano overflow?

Checking pyarrow it seems that they cannot overflow, since casting a uint64 to timestamp is not allowed:

arr = pyarrow.array([18_446_744_073_709_551_61, None], type=pyarrow.uint64()).cast(pyarrow.timestamp("ns"))
print(arr)

E   pyarrow.lib.ArrowNotImplementedError: Unsupported cast from uint64 to timestamp using function cast_timestamp

pyarrow/error.pxi:92: ArrowNotImplementedError

And if we try coerce an overflow:

dt = datetime(1999, 8, 7, 11, 12, 13, 141516)
arr = pyarrow.array([9_223_372_036_854_775_8070, None], type=pyarrow.int64()).cast(pyarrow.timestamp("ns"))
print(arr)

We get an overflow error but that's not time timestampo nano overflowing, but the creation of the int64.

So it's up to us to decide, do we silently null it, trunc it to nano precision or just raise an error?

[kylebarron]

Can you add a more detailed comment here, explaining why this is valid?