DEPR: Restrict nanosecond range in Timestamp constructor

[mroeschke]

xref #48255

In the normal datetime.datetime constructor, each component is bounded to [0, next_largest_component) e.g.

In [5]: import datetime

In [6]: datetime.datetime(year=2022, month=1, day=1, microsecond=1000000)
ValueError: microsecond must be in 0..999999

In [7]: Timestamp(year=2022, month=1, day=1, microsecond=1000000)
ValueError: microsecond must be in 0..999999

Since Timestamp supports nanosecond, ideally it should be bounded to [0, microsecond_boundary) but this is not the case

In [10]: Timestamp(year=2022, month=1, day=1, nanosecond=1_000)
Out[10]: Timestamp('2022-01-01 00:00:00.000001000')

In [12]: Timestamp(year=2022, month=1, day=1, nanosecond=1_000_000)
Out[12]: Timestamp('2022-01-01 00:00:00.001000000')

# Explained by GH 48255
In [13]: Timestamp(year=2022, month=1, day=1, nanosecond=1_000_000_000)
Out[13]: Timestamp('2022-01-01 00:00:00.-00727380')

Thoughts @jbrockmendel?

[jbrockmendel]

makes sense. microsecond_boundary is 1_000?

[mroeschke]

microsecond_boundary is 1_000?

Correct