Docstring changes to pandas.Series.dt.to_pydatetime

pandas/core/indexes/accessors.py

@@ -126,6 +126,48 @@ class DatetimeProperties(Properties):
     """
 
     def to_pydatetime(self):
+        """
+        Return an ndarray of native Python datetime objects.
+
+        Timezone information is retained if present.
+
+        .. warning::
+
+           Python's datetimes use microsecond resolution, which is lower than
+           pandas' (nanosecond). The values are truncated.
+
+        Returns
+        -------
+        numpy.ndarray
+            object dtype array containing native Python datetime objects.
+
+        See Also
+        --------
+        datetime.datetime : Standard library value for a datetime.
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.date_range('20180310', periods=2))
+        >>> s.head()
+        0   2018-03-10
+        1   2018-03-11
+        dtype: datetime64[ns]
+
+        >>> s.dt.to_pydatetime()
+        array([datetime.datetime(2018, 3, 10, 0, 0),
+               datetime.datetime(2018, 3, 11, 0, 0)], dtype=object)
+
+        pandas' nanosecond precision is truncated to microseconds.
+
+        >>> idx = pd.date_range('2017', periods=2, freq='ns')
+        >>> idx
+        DatetimeIndex(['2017-01-01 00:00:00', '2017-01-01 00:00:00.000000001'],
+                      dtype='datetime64[ns]', freq='N')
+
+        >>> idx.to_pydatetime()
+        array([datetime.datetime(2017, 1, 1, 0, 0),
+               datetime.datetime(2017, 1, 1, 0, 0)], dtype=object)
+        """
         return self._get_values().to_pydatetime()
 
     @property