DOC: fix to_numpy explanation for tz aware data (pandas-dev#24595)

Author: jorisvandenbossche

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"))

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]')

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)
         ================== ================================