Repository: pandas-dev/pandas
Pull request: DOC: fix timestamp timedelta quotes
- [X] closes #24070 
- [ ] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Problem statement:
DOC: Fix quotes position in Timestamp and Timedelta
To keep out docstrings consistent, and make them easier to read, we try to keep always the same exact format. In the case of the opening and closing quotes, the right format is:
```
def foo():
    """
    Summary of the docstring.

    Returns
    -------
    str
        Explaining what is being returned.
    """
```

But for historical reasons, we have many docstrings with different format, for example:
```
def foo():
    """Summary of the docstring.

    Returns
    -------
    str
        Explaining what is being returned."""
```

Besides being inconsistent, having docstrings with the wrong format doesn't let us start validating and enforcing automatically the wanted format. So, we need to change all the wrong cases.

For this issue, all the wrong cases of methods of `Timestamp` and `Timedelta` should be fixed. The list can be obtained with the next command (the command should not report any error when this is fixed):
```
$ ./scripts/validate_docstrings.py --prefix=pandas.Time --errors=GL01,GL02
pandas.Timestamp: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.asm8: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.asm8: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.day: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.day: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.dayofweek: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.dayofweek: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.dayofyear: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.dayofyear: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.days_in_month: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.days_in_month: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.daysinmonth: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.daysinmonth: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.fold: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.fold: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.hour: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.hour: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_leap_year: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_leap_year: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_month_end: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_month_end: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_month_start: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_month_start: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_quarter_end: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_quarter_end: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_quarter_start: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_quarter_start: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_year_end: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_year_end: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.is_year_start: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.is_year_start: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.max: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.microsecond: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.microsecond: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.min: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.minute: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.minute: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.month: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.month: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.nanosecond: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.nanosecond: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.quarter: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.quarter: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.second: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.second: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.tzinfo: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.tzinfo: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.value: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.value: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.week: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.week: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.weekofyear: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.weekofyear: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.year: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.year: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.ctime: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.ctime: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.date: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.date: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.dst: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.dst: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.freq: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.freq: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.freqstr: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.freqstr: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.isocalendar: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.isocalendar: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.isoformat: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.isoformat: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.isoweekday: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.isoweekday: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.strftime: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.strftime: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.strptime: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.strptime: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.time: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.time: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.timestamp: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.timestamp: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.timetuple: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.timetuple: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.timetz: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.timetz: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.to_datetime64: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.to_datetime64: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.toordinal: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.toordinal: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.tzname: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.tzname: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.utcoffset: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.utcoffset: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.utctimetuple: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.utctimetuple: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timestamp.weekday: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timestamp.weekday: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.components: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.components: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.days: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.days: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.freq: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.freq: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.is_populated: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.is_populated: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.max: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.microseconds: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.microseconds: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.min: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.seconds: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.seconds: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.value: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.value: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.view: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.view: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Timedelta.to_timedelta64: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Timedelta.to_timedelta64: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
```

Hints from issue discussion:
Hello! May I work on this issue?
Yes please, let me know if you need help.
Thanks @datapythonista, I will!
Hi! @datapythonista, I see that methods that do not have docstrings also return errors GL01 & GL02. I assume resolving this issue also involves adding in docstrings for these methods?
no, if I'm not wrong we merged a PR today that makes the methods without a docstring generate a different error. If we didn't merge it yet, we should merge it soon
Got it, thanks!
Can you give me a little help please? I can't seem to clear the error even with the correct format. For example, in the file '\pandas\_libs\tslibs\timedeltas.pyx':

```
def to_timedelta64(self):
        """
	Returns a numpy.timedelta64 object with 'ns' precision
	"""
        return np.timedelta64(self.value, 'ns')
```

still returns the errors:

> pandas.Timedelta.to_timedelta64: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
> pandas.Timedelta.to_timedelta64: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)

Can you give me a little tip please?
This file is a `pyx`, which means that it's compiled before running. The docstring being validated is the old version which is in the compiled file. If you compile pandas again `python setup.py build_ext --inplace` you shouldn't get the error anymore.
Thank you for your quick reply! I am new to python so I didn't know about pyx files. I will try to have a PR ready by tonight :)
I will try this one.

Commit message: DOC: consolidate pandas.Timedelta.to_pytimedelta docstring

Patch to review:
diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx
index f2de3fda3be15..53ed507f41eac 100644
--- a/pandas/_libs/tslibs/nattype.pyx
+++ b/pandas/_libs/tslibs/nattype.pyx
@@ -207,7 +207,7 @@ cdef class _NaT(datetime):
 
     def total_seconds(self):
         """
-        Total duration of timedelta in seconds (to ns precision)
+        Total duration of timedelta in seconds (to ns precision).
         """
         # GH#10939
         return np.nan
diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index 0a19d8749fc7c..c6885347a0ada 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
+
+        Timedelta objects are typecast to numpy datetime64[ns] dtype,
+        use to_pytimedelta() to convert back to object dtype.
+
+        Returns
+        -------
+        datetime.timedelta or numpy.array of datetime.timedelta
+
+        See Also
+        --------
+        to_timedelta : Convert argument to Timedelta type.
+
+        Notes
+        -----
+        Any nanosecond resolution will be lost.
+
+        Examples
+        --------
+        Converting an array of Timedeltas:
+
+        >>> arr = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
+        >>> arr
+        TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015',
+                       NaT],
+                       dtype='timedelta64[ns]', freq=None)
+        >>> arr[1].to_pytimedelta()
+        datetime.timedelta(0, 0, 16)
+        >>> arr.to_pytimedelta()
+        array([datetime.timedelta(1, 21901, 30), datetime.timedelta(0, 0, 16),
+        NaT], dtype=object)
         """
         return timedelta(microseconds=int(self.value) / 1000)
 
     def to_timedelta64(self):
-        """ Returns a numpy.timedelta64 object with 'ns' precision """
+        """
+        Returns a numpy.timedelta64 object with 'ns' precision.
+        """
         return np.timedelta64(self.value, 'ns')
 
     def total_seconds(self):
         """
-        Total duration of timedelta in seconds (to ns precision)
+        Total duration of timedelta in seconds (to ns precision).
         """
         return self.value / 1e9
 
     def view(self, dtype):
-        """ array view compat """
+        """
+        Array view compatibility.
+        """
         return np.timedelta64(self.value).view(dtype)
 
     @property
     def components(self):
-        """ Return a Components NamedTuple-like """
+        """
+        Return a Components NamedTuple-like.
+        """
         self._ensure_components()
         # return the named tuple
         return Components(self._d, self._h, self._m, self._s,
@@ -1135,8 +1170,8 @@ class Timedelta(_Timedelta):
     Notes
     -----
     The ``.value`` attribute is always in ns.
-
     """
+
     def __new__(cls, object value=_no_input, unit=None, **kwargs):
         cdef _Timedelta td_base
 
diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx
index a9be60214080a..9bcfb1357e850 100644
--- a/pandas/_libs/tslibs/timestamps.pyx
+++ b/pandas/_libs/tslibs/timestamps.pyx
@@ -526,7 +526,8 @@ cdef class _Timestamp(datetime):
 
 
 class Timestamp(_Timestamp):
-    """Pandas replacement for datetime.datetime
+    """
+    Pandas replacement for python datetime.datetime object.
 
     Timestamp is the pandas equivalent of python's Datetime
     and is interchangeable with it in most cases. It's the type used
@@ -536,9 +537,9 @@ class Timestamp(_Timestamp):
     Parameters
     ----------
     ts_input : datetime-like, str, int, float
-        Value to be converted to Timestamp
+        Value to be converted to Timestamp.
     freq : str, DateOffset
-        Offset which Timestamp will have
+        Offset which Timestamp will have.
     tz : str, pytz.timezone, dateutil.tz.tzfile or None
         Time zone for time which Timestamp will have.
     unit : str


Code review comments:
diff_hunk: @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
+
+        Timedelta objects are typecast to numpy datetime64[ns] dtype,
+        use to_pytimedelta() to convert back to object dtype.
+
+        Returns
+        -------
+        datetime.timedelta or numpy.array of datetime.timedelta
+
+        See Also
+        --------
+        to_timedelta : Convert argument to Timedelta type.
+
+        Notes
+        -----
+        Any nanosecond resolution will be lost.
+
+        Examples
+        --------
+        Converting an array of Timedeltas:
path: pandas/_libs/tslibs/timedeltas.pyx
text: @user1:
Remove this, as you're also converting a scalar, and it's misleading.

diff_hunk: @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
path: pandas/_libs/tslibs/timedeltas.pyx
text: @user1:
`Convert` instead of `Converts`

I think it'd be more clear: Convert a **pandas** Timedelta object into a python timedelta object.

diff_hunk: @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
+
+        Timedelta objects are typecast to numpy datetime64[ns] dtype,
+        use to_pytimedelta() to convert back to object dtype.
+
+        Returns
+        -------
+        datetime.timedelta or numpy.array of datetime.timedelta
+
+        See Also
+        --------
+        to_timedelta : Convert argument to Timedelta type.
+
+        Notes
+        -----
+        Any nanosecond resolution will be lost.
+
+        Examples
+        --------
+        Converting an array of Timedeltas:
+
+        >>> arr = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
+        >>> arr
+        TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015',
+                       NaT],
+                       dtype='timedelta64[ns]', freq=None)
+        >>> arr[1].to_pytimedelta()
+        datetime.timedelta(0, 0, 16)
+        >>> arr.to_pytimedelta()
+        array([datetime.timedelta(1, 21901, 30), datetime.timedelta(0, 0, 16),
+        NaT], dtype=object)
         """
         return timedelta(microseconds=int(self.value) / 1000)
 
     def to_timedelta64(self):
-        """ Returns a numpy.timedelta64 object with 'ns' precision """
+        """
+        Returns a numpy.timedelta64 object with 'ns' precision.
+        """
         return np.timedelta64(self.value, 'ns')
 
     def total_seconds(self):
         """
-        Total duration of timedelta in seconds (to ns precision)
+        Total duration of timedelta in seconds (to ns precision).
         """
         return self.value / 1e9
 
     def view(self, dtype):
-        """ array view compat """
+        """
+        Array view compatibility.
+        """
         return np.timedelta64(self.value).view(dtype)
 
     @property
     def components(self):
-        """ Return a Components NamedTuple-like """
+        """
+        Return a Components NamedTuple-like.
path: pandas/_libs/tslibs/timedeltas.pyx
text: @user1:
`namedtuple` (like the Python class), and make the `c` of components lowercase.

diff_hunk: @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
+
+        Timedelta objects are typecast to numpy datetime64[ns] dtype,
+        use to_pytimedelta() to convert back to object dtype.
+
+        Returns
+        -------
+        datetime.timedelta or numpy.array of datetime.timedelta
+
+        See Also
+        --------
+        to_timedelta : Convert argument to Timedelta type.
+
+        Notes
+        -----
+        Any nanosecond resolution will be lost.
+
+        Examples
+        --------
+        Converting an array of Timedeltas:
+
+        >>> arr = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
+        >>> arr
+        TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015',
+                       NaT],
+                       dtype='timedelta64[ns]', freq=None)
+        >>> arr[1].to_pytimedelta()
path: pandas/_libs/tslibs/timedeltas.pyx
text: @user1:
Leave a blank line before this line, and convert first the whole index, and then a single value. Better convert `idx[0]` and not `idx[1]`, as it feels like there must be a reason for that, and I don't think that's the case.

Feel free to use the comment on what you're doing in this part, if you add also a comment for the scalar (but I don't think it's necessary to explain, I find it's clear enough).

@author:
I chose `idx[1]` because it shows the loss of (500) nanosecond resolution. I chose the set of elements in that order to be consistent with the examples in `to_timedelta` . 
I can change it to `idx[0]` if you still want...

diff_hunk: @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        return an actual datetime.timedelta object
-        note: we lose nanosecond resolution if any
+        Converts a Timedelta object into a python datetime.timedelta object.
+
+        Timedelta objects are typecast to numpy datetime64[ns] dtype,
+        use to_pytimedelta() to convert back to object dtype.
+
+        Returns
+        -------
+        datetime.timedelta or numpy.array of datetime.timedelta
+
+        See Also
+        --------
+        to_timedelta : Convert argument to Timedelta type.
+
+        Notes
+        -----
+        Any nanosecond resolution will be lost.
+
+        Examples
+        --------
+        Converting an array of Timedeltas:
+
+        >>> arr = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
path: pandas/_libs/tslibs/timedeltas.pyx
text: @user1:
our convention is to use `idx` instead of `arr`