Fixed docstrings for pandas.DataFrame.keys, pandas.read_clipboard and some of pandas.ExcelFile.parse (issue pandas-dev#27979)

Author: realjohnward

pandas/core/generic.py

@@ -1875,7 +1875,7 @@ def __iter__(self):
     # can we get a better explanation of this?
     def keys(self):
         """
-        Get the 'info axis' (see Indexing for more)
+        Get the 'info axis' (see Indexing for more).
 
         This is index for Series, columns for DataFrame.
 

pandas/io/clipboards.py

@@ -9,18 +9,21 @@
 
 def read_clipboard(sep=r"\s+", **kwargs):  # pragma: no cover
     r"""
-    Read text from clipboard and pass to read_csv. See read_csv for the
-    full argument list
+    Read text from clipboard and pass to read_csv.
 
     Parameters
     ----------
     sep : str, default '\s+'
         A string or regex delimiter. The default of '\s+' denotes
         one or more whitespace characters.
 
+    **kwargs
+        See read_csv for the full argument list.
+
     Returns
     -------
-    parsed : DataFrame
+    DataFrame
+        A parsed DataFrame object.
     """
     encoding = kwargs.pop("encoding", "utf-8")
 

pandas/io/excel/_base.py

@@ -837,10 +837,10 @@ def parse(
         **kwds
     ):
         """
-        Parse specified sheet(s) into a DataFrame
+        Parse specified sheet(s) into a DataFrame.
 
         Equivalent to read_excel(ExcelFile, ...)  See the read_excel
-        docstring for more info on accepted parameters
+        docstring for more info on accepted parameters.
 
         Returns
         -------

pandas/tseries/offsets.py

@@ -204,8 +204,7 @@ def __add__(date):
     normalize : bool, default False
         Whether to round the result of a DateOffset addition down to the
         previous midnight.
-    **kwds
-        Temporal parameter that add to or replace the offset value.
+    **kwds : Temporal parameter that add to or replace the offset value.
 
         Parameters that **add** to the offset (like Timedelta):
 
@@ -231,18 +230,21 @@ def __add__(date):
         - microsecond
         - nanosecond
 
+        .
+
     See Also
     --------
-    dateutil.relativedelta.relativedelta
+    dateutil.relativedelta.relativedelta :     The relativedelta type is designed to be applied to an existing datetime an can replace specific components of that datetime, or represents an interval of time.
 
     Examples
     --------
+    >>> from pandas.tseries.offsets import DateOffset
     >>> ts = pd.Timestamp('2017-01-01 09:10:11')
     >>> ts + DateOffset(months=3)
     Timestamp('2017-04-01 09:10:11')
 
     >>> ts = pd.Timestamp('2017-01-01 09:10:11')
-    >>> ts + DateOffset(month=3)
+    >>> ts + DateOffset(months=2)
     Timestamp('2017-03-01 09:10:11')
     """
 
@@ -471,6 +473,97 @@ def nanos(self):
 
 
 class SingleConstructorOffset(DateOffset):
+    """
+    Standard kind of date increment used for a date range.
+
+    Works exactly like relativedelta in terms of the keyword args you
+    pass in, use of the keyword n is discouraged-- you would be better
+    off specifying n in the keywords you use, but regardless it is
+    there for you. n is needed for DateOffset subclasses.
+
+    DateOffset work as follows.  Each offset specify a set of dates
+    that conform to the DateOffset.  For example, Bday defines this
+    set to be the set of dates that are weekdays (M-F).  To test if a
+    date is in the set of a DateOffset dateOffset we can use the
+    onOffset method: dateOffset.onOffset(date).
+
+    If a date is not on a valid date, the rollback and rollforward
+    methods can be used to roll the date to the nearest valid date
+    before/after the date.
+
+    DateOffsets can be created to move dates forward a given number of
+    valid dates.  For example, Bday(2) can be added to a date to move
+    it two business days forward.  If the date does not start on a
+    valid date, first it is moved to a valid date.  Thus pseudo code
+    is:
+
+    def __add__(date):
+      date = rollback(date) # does nothing if date is valid
+      return date + <n number of periods>
+
+    When a date offset is created for a negative number of periods,
+    the date is first rolled forward.  The pseudo code is:
+
+    def __add__(date):
+      date = rollforward(date) # does nothing is date is valid
+      return date + <n number of periods>
+
+    Zero presents a problem.  Should it roll forward or back?  We
+    arbitrarily have it rollforward:
+
+    date + BDay(0) == BDay.rollforward(date)
+
+    Since 0 is a bit weird, we suggest avoiding its use.
+
+    Parameters
+    ----------
+    n : int, default 1
+        The number of time periods the offset represents.
+    normalize : bool, default False
+        Whether to round the result of a DateOffset addition down to the
+        previous midnight.
+    **kwds : Temporal parameter that add to or replace the offset value.
+
+        Parameters that **add** to the offset (like Timedelta):
+
+        - years
+        - months
+        - weeks
+        - days
+        - hours
+        - minutes
+        - seconds
+        - microseconds
+        - nanoseconds
+
+        Parameters that **replace** the offset value:
+
+        - year
+        - month
+        - day
+        - weekday
+        - hour
+        - minute
+        - second
+        - microsecond
+        - nanosecond
+
+        .
+
+    See Also
+    --------
+
+    Examples
+    --------
+    >>> from pandas.tseries.offsets import DateOffset
+    >>> ts = pd.Timestamp('2017-01-01 09:10:11')
+    >>> ts + DateOffset(months=3)
+    Timestamp('2017-04-01 09:10:11')
+
+    >>> ts = pd.Timestamp('2017-01-01 09:10:11')
+    >>> ts + DateOffset(months=2)
+    Timestamp('2017-03-01 09:10:11')
+    """
     @classmethod
     def _from_name(cls, suffix=None):
         # default _from_name calls cls with no args