whatsnew

Author: TomAugspurger

doc/source/whatsnew/v0.24.0.rst

@@ -1352,6 +1352,53 @@ the object's ``freq`` attribute (:issue:`21939`, :issue:`23878`).
     dti + pd.Index([1 * dti.freq, 2 * dti.freq])
 
 
+.. _whatsnew_0240.deprecations.integer_tz:
+
+Passing Integer data and a timezone to DatetimeIndex
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The behavior of :class:`DatetimeIndex` when passed integer data and
+a timezone is changing in a future version of pandas. Previously, these
+were interpreted as wall times in the desired timezone. In the future,
+these will be interpreted as wall times in UTC, which are then converted
+to the desired timezone (:issue:`24559`).
+
+The default behavior remains the same, but issues a warning:
+
+.. code-block:: ipython
+
+   In [3]: pd.DatetimeIndex([946684800000000000], tz="US/Central")
+   /bin/ipython:1: FutureWarning:
+       Passing integer-dtype data and a timezone to DatetimeIndex.
+       Integer values will be interpreted differently in a future version
+       of pandas. Previously, these were viewed as datetime64[ns] values
+       representing the wall time *in the specified timezone*.
+       In the future, these will be viewed as datetime64[ns] values
+       representing the wall time *in UTC*. This is similar to a
+       nanosecond-precision UNIX epoch.
+       To accept the future behavior, use
+
+           pd.to_datetime(integer_data, utc=True).tz_convert(tz)
+
+       To keep the previous behavior, use
+
+       pd.to_datetime(integer_data).tz_localize(tz)
+
+      #!/bin/python3
+    Out[3]: DatetimeIndex(['2000-01-01 00:00:00-06:00'], dtype='datetime64[ns, US/Central]', freq=None)
+
+As the warning message explains, opt in to the future behavior with
+
+.. ipython:: python
+
+   pd.to_datetime([946684800000000000], utc=True).tz_convert('US/Central')
+
+And the old behavior can be retained with
+
+.. ipython:: python
+
+   pd.to_datetime([946684800000000000]).tz_localize('US/Central')
+
 .. _whatsnew_0240.deprecations.tz_aware_array:
 
 Converting Timezone-Aware Series and Index to NumPy Arrays