diff --git a/doc/source/basics.rst b/doc/source/basics.rst index 8dca000dfa969..73ae26150b946 100644 --- a/doc/source/basics.rst +++ b/doc/source/basics.rst @@ -99,27 +99,6 @@ are two possibly useful representations: Timezones may be preserved with ``dtype=object`` -.. ipython:: python - - ser = pd.Series(pd.date_range('2000', periods=2, tz="CET")) - ser.to_numpy(dtype=object) - -Or thrown away with ``dtype='datetime64[ns]'`` - - ser.to_numpy(dtype="datetime64[ns]") - -:meth:`~Series.to_numpy` gives some control over the ``dtype`` of the -resulting :class:`ndarray`. For example, consider datetimes with timezones. -NumPy doesn't have a dtype to represent timezone-aware datetimes, so there -are two possibly useful representations: - -1. An object-dtype :class:`ndarray` with :class:`Timestamp` objects, each - with the correct ``tz`` -2. A ``datetime64[ns]`` -dtype :class:`ndarray`, where the values have - been converted to UTC and the timezone discarded - -Timezones may be preserved with ``dtype=object`` - .. ipython:: python ser = pd.Series(pd.date_range('2000', periods=2, tz="CET")) diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index a391d73b8922e..f56ad710973dd 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -2425,21 +2425,25 @@ a convert on an aware stamp. .. note:: Using :meth:`Series.to_numpy` on a ``Series``, returns a NumPy array of the data. - These values are converted to UTC, as NumPy does not currently support timezones (even though it is *printing* in the local timezone!). + NumPy does not currently support timezones (even though it is *printing* in the local timezone!), + therefore an object array of Timestamps is returned for timezone aware data: .. ipython:: python s_naive.to_numpy() s_aware.to_numpy() - Further note that once converted to a NumPy array these would lose the tz tenor. + By converting to an object array of Timestamps, it preserves the timezone + information. For example, when converting back to a Series: .. ipython:: python pd.Series(s_aware.to_numpy()) - However, these can be easily converted: + However, if you want an actual NumPy ``datetime64[ns]`` array (with the values + converted to UTC) instead of an array of objects, you can specify the + ``dtype`` argument: .. ipython:: python - pd.Series(s_aware.to_numpy()).dt.tz_localize('UTC').dt.tz_convert('US/Eastern') + s_aware.to_numpy(dtype='datetime64[ns]') diff --git a/pandas/core/base.py b/pandas/core/base.py index c37ab48de7cb8..c02ba88ea7fda 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -899,7 +899,6 @@ def to_numpy(self, dtype=None, copy=False): ``to_numpy()`` will return a NumPy array and the categorical dtype will be lost. - For NumPy dtypes, this will be a reference to the actual data stored in this Series or Index (assuming ``copy=False``). Modifying the result in place will modify the data stored in the Series or Index (not that @@ -910,7 +909,7 @@ def to_numpy(self, dtype=None, copy=False): expensive. When you need a no-copy reference to the underlying data, :attr:`Series.array` should be used instead. - This table lays out the different dtypes and return types of + This table lays out the different dtypes and default return types of ``to_numpy()`` for various dtypes within pandas. ================== ================================ @@ -920,6 +919,7 @@ def to_numpy(self, dtype=None, copy=False): period ndarray[object] (Periods) interval ndarray[object] (Intervals) IntegerNA ndarray[object] + datetime64[ns] datetime64[ns] datetime64[ns, tz] ndarray[object] (Timestamps) ================== ================================