DOC/CLN: docstring cleanups (#27942)

jbrockmendel · jorisvandenbossche · commit f4b4ec202632 · 2019-08-16T21:18:52.000+02:00
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -1190,7 +1190,7 @@ def to_numpy(self, dtype=None, copy=False):
         Parameters
         ----------
         dtype : str or numpy.dtype, optional
-            The dtype to pass to :meth:`numpy.asarray`
+            The dtype to pass to :meth:`numpy.asarray`.
         copy : bool, default False
             Whether to ensure that the returned value is a not a view on
             another array. Note that ``copy=False`` does not *ensure* that
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -131,7 +131,7 @@ class NDFrame(PandasObject, SelectionMixin):
     ----------
     data : BlockManager
     axes : list
-    copy : boolean, default False
+    copy : bool, default False
     """
 
     _internal_names = [
@@ -280,16 +280,17 @@ def _setup_axes(
         ns=None,
         docs=None,
     ):
-        """Provide axes setup for the major PandasObjects.
+        """
+        Provide axes setup for the major PandasObjects.
 
         Parameters
         ----------
         axes : the names of the axes in order (lowest to highest)
         info_axis_num : the axis of the selector dimension (int)
         stat_axis_num : the number of axis for the default stats (int)
         aliases : other names for a single axis (dict)
-        axes_are_reversed : boolean whether to treat passed axes as
-            reversed (DataFrame)
+        axes_are_reversed : bool
+            Whether to treat passed axes as reversed (DataFrame).
         build_axes : setup the axis properties (default True)
         """
 
@@ -676,7 +677,7 @@ def transpose(self, *args, **kwargs):
         Parameters
         ----------
         args : %(args_transpose)s
-        copy : boolean, default False
+        copy : bool, default False
             Make a copy of the underlying data. Mixed-dtype data will
             always result in a copy
         **kwargs
@@ -2257,10 +2258,10 @@ def to_json(
 
         Parameters
         ----------
-        path_or_buf : string or file handle, optional
+        path_or_buf : str or file handle, optional
             File path or object. If not specified, the result is returned as
             a string.
-        orient : string
+        orient : str
             Indication of expected JSON string format.
 
             * Series
@@ -2539,7 +2540,7 @@ def to_msgpack(self, path_or_buf=None, encoding="utf-8", **kwargs):
 
     def to_sql(
         self,
-        name,
+        name: str,
         con,
         schema=None,
         if_exists="fail",
@@ -2557,12 +2558,12 @@ def to_sql(
 
         Parameters
         ----------
-        name : string
+        name : str
             Name of SQL table.
         con : sqlalchemy.engine.Engine or sqlite3.Connection
             Using SQLAlchemy makes it possible to use any DB supported by that
             library. Legacy support is provided for sqlite3.Connection objects.
-        schema : string, optional
+        schema : str, optional
             Specify the schema (if database flavor supports this). If None, use
             default schema.
         if_exists : {'fail', 'replace', 'append'}, default 'fail'
@@ -2575,7 +2576,7 @@ def to_sql(
         index : bool, default True
             Write DataFrame index as a column. Uses `index_label` as the column
             name in the table.
-        index_label : string or sequence, default None
+        index_label : str or sequence, default None
             Column label for index column(s). If None is given (default) and
             `index` is True, then the index names are used.
             A sequence should be given if the DataFrame uses MultiIndex.
@@ -3251,11 +3252,10 @@ def _maybe_update_cacher(self, clear=False, verify_is_copy=True):
 
         Parameters
         ----------
-        clear : boolean, default False
-            clear the item cache
-        verify_is_copy : boolean, default True
-            provide is_copy checks
-
+        clear : bool, default False
+            Clear the item cache.
+        verify_is_copy : bool, default True
+            Provide is_copy checks.
         """
 
         cacher = getattr(self, "_cacher", None)
@@ -3621,11 +3621,11 @@ def _check_setitem_copy(self, stacklevel=4, t="setting", force=False):
 
         Parameters
         ----------
-        stacklevel : integer, default 4
+        stacklevel : int, default 4
            the level to show of the stack when the error is output
-        t : string, the type of setting error
-        force : boolean, default False
-           if True, then force showing an error
+        t : str, the type of setting error
+        force : bool, default False
+           If True, then force showing an error.
 
         validate if we are doing a setitem on a chained copy.
 
@@ -3954,9 +3954,8 @@ def _update_inplace(self, result, verify_is_copy=True):
 
         Parameters
         ----------
-        verify_is_copy : boolean, default True
-            provide is_copy checks
-
+        verify_is_copy : bool, default True
+            Provide is_copy checks.
         """
         # NOTE: This does *not* call __finalize__ and that's an explicit
         # decision that we may revisit in the future.
@@ -4571,9 +4570,9 @@ def filter(self, items=None, like=None, regex=None, axis=None):
         ----------
         items : list-like
             Keep labels from axis which are in items.
-        like : string
+        like : str
             Keep labels from axis for which "like in label == True".
-        regex : string (regular expression)
+        regex : str (regular expression)
             Keep labels from axis for which re.search(regex, label) == True.
         axis : int or string axis name
             The axis to filter on.  By default this is the info axis,
@@ -5233,8 +5232,8 @@ def _consolidate(self, inplace=False):
 
         Parameters
         ----------
-        inplace : boolean, default False
-            If False return new object, otherwise modify existing object
+        inplace : bool, default False
+            If False return new object, otherwise modify existing object.
 
         Returns
         -------
@@ -5680,11 +5679,12 @@ def as_blocks(self, copy=True):
 
         Parameters
         ----------
-        copy : boolean, default True
+        copy : bool, default True
 
         Returns
         -------
-        values : a dict of dtype -> Constructor Types
+        dict
+            Mapping dtype -> Constructor Types.
         """
         warnings.warn(
             "as_blocks is deprecated and will be removed in a future version",
@@ -5993,17 +5993,17 @@ def _convert(
 
         Parameters
         ----------
-        datetime : boolean, default False
+        datetime : bool, default False
             If True, convert to date where possible.
-        numeric : boolean, default False
+        numeric : bool, default False
             If True, attempt to convert to numbers (including strings), with
             unconvertible values becoming NaN.
-        timedelta : boolean, default False
+        timedelta : bool, default False
             If True, convert to timedelta where possible.
-        coerce : boolean, default False
+        coerce : bool, default False
             If True, force conversion with unconvertible values converted to
-            nulls (NaN or NaT)
-        copy : boolean, default True
+            nulls (NaN or NaT).
+        copy : bool, default True
             If True, return a copy even if no copy is necessary (e.g. no
             conversion was done). Note: This is meant for internal use, and
             should not be confused with inplace.
@@ -7870,7 +7870,7 @@ def asfreq(self, freq, method=None, how=None, normalize=False, fill_value=None):
 
         Parameters
         ----------
-        freq : DateOffset object, or string
+        freq : DateOffset or str
         method : {'backfill'/'bfill', 'pad'/'ffill'}, default None
             Method to use for filling holes in reindexed Series (note this
             does not fill NaNs that already were present):
@@ -8671,7 +8671,7 @@ def ranker(data):
         level : int or level name, default None
             Broadcast across a level, matching Index values on the
             passed MultiIndex level
-        copy : boolean, default True
+        copy : bool, default True
             Always returns new objects. If copy=False and no reindexing is
             required then original objects are returned.
         fill_value : scalar, default np.NaN
@@ -9463,7 +9463,7 @@ def truncate(self, before=None, after=None, axis=None, copy=True):
             Truncate all rows after this index value.
         axis : {0 or 'index', 1 or 'columns'}, optional
             Axis to truncate. Truncates the index (rows) by default.
-        copy : boolean, default is True,
+        copy : bool, default is True,
             Return a copy of the truncated section.
 
         Returns
@@ -9607,13 +9607,13 @@ def tz_convert(self, tz, axis=0, level=None, copy=True):
 
         Parameters
         ----------
-        tz : string or pytz.timezone object
+        tz : str or tzinfo object
         axis : the axis to convert
         level : int, str, default None
-            If axis ia a MultiIndex, convert a specific level. Otherwise
-            must be None
-        copy : boolean, default True
-            Also make a copy of the underlying data
+            If axis is a MultiIndex, convert a specific level. Otherwise
+            must be None.
+        copy : bool, default True
+            Also make a copy of the underlying data.
 
         Returns
         -------
@@ -9667,12 +9667,12 @@ def tz_localize(
 
         Parameters
         ----------
-        tz : string or pytz.timezone object
+        tz : str or tzinfo
         axis : the axis to localize
         level : int, str, default None
             If axis ia a MultiIndex, localize a specific level. Otherwise
             must be None
-        copy : boolean, default True
+        copy : bool, default True
             Also make a copy of the underlying data
         ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
             When clocks moved backward due to DST, ambiguous times may arise.
@@ -11009,7 +11009,7 @@ def _doc_parms(cls):
 ----------
 axis : {0 or 'index', 1 or 'columns'}, default 0
     The index or the name of the axis. 0 is equivalent to None or 'index'.
-skipna : boolean, default True
+skipna : bool, default True
     Exclude NA/null values. If an entire row/column is NA, the result
     will be NA.
 *args, **kwargs :
diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -675,8 +675,8 @@ def nonzero(self):
         3    4
         dtype: int64
 
-        >>> s = pd.Series([0, 3, 0, 4], index=['a', 'b', 'c', 'd'])
         # same return although index of s is different
+        >>> s = pd.Series([0, 3, 0, 4], index=['a', 'b', 'c', 'd'])
         >>> s.nonzero()
         (array([1, 3]),)
         >>> s.iloc[s.nonzero()[0]]
diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py
@@ -53,7 +53,7 @@ def hist_series(
         rotation of y axis labels
     figsize : tuple, default None
         figure size in inches by default
-    bins : integer or sequence, default 10
+    bins : int or sequence, default 10
         Number of histogram bins to be used. If an integer is given, bins + 1
         bin edges are calculated and returned. If bins is a sequence, gives
         bin edges, including left edge of first bin and right edge of last
@@ -116,7 +116,7 @@ def hist_frame(
     ----------
     data : DataFrame
         The pandas object holding the data.
-    column : string or sequence
+    column : str or sequence
         If passed, will be used to limit data to a subset of columns.
     by : object, optional
         If passed, then used to form histograms for separate groups.
@@ -148,7 +148,7 @@ def hist_frame(
         `matplotlib.rcParams` by default.
     layout : tuple, optional
         Tuple of (rows, columns) for the layout of the histograms.
-    bins : integer or sequence, default 10
+    bins : int or sequence, default 10
         Number of histogram bins to be used. If an integer is given, bins + 1
         bin edges are calculated and returned. If bins is a sequence, gives
         bin edges, including left edge of first bin and right edge of last
@@ -177,7 +177,7 @@ def hist_frame(
         >>> df = pd.DataFrame({
         ...     'length': [1.5, 0.5, 1.2, 0.9, 3],
         ...     'width': [0.7, 0.2, 0.15, 0.2, 1.1]
-        ...     }, index= ['pig', 'rabbit', 'duck', 'chicken', 'horse'])
+        ...     }, index=['pig', 'rabbit', 'duck', 'chicken', 'horse'])
         >>> hist = df.hist(bins=3)
     """
     plot_backend = _get_plot_backend()
@@ -370,8 +370,8 @@ def boxplot(
     If ``return_type`` is `None`, a NumPy array of axes with the same shape
     as ``layout`` is returned:
 
-        >>> boxplot =  df.boxplot(column=['Col1', 'Col2'], by='X',
-        ...                       return_type=None)
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+        ...                      return_type=None)
         >>> type(boxplot)
         <class 'numpy.ndarray'>
     """
@@ -446,7 +446,7 @@ def boxplot_frame_groupby(
         * ``True`` - create a subplot for each group
     column : column name or list of names, or vector
         Can be any valid input to groupby
-    fontsize : int or string
+    fontsize : int or str
     rot : label rotation angle
     grid : Setting this to True will show the grid
     ax : Matplotlib axis object, default None
@@ -530,7 +530,7 @@ class PlotAccessor(PandasObject):
     figsize : a tuple (width, height) in inches
     use_index : bool, default True
         Use index as ticks for x axis
-    title : string or list
+    title : str or list
         Title to use for the plot. If a string is passed, print the string
         at the top of the figure. If a list is passed and `subplots` is
         True, print each item in the list above the corresponding subplot.
@@ -553,16 +553,16 @@ class PlotAccessor(PandasObject):
         .. versionchanged:: 0.25.0
 
     xticks : sequence
-        Values to use for the xticks
+        Values to use for the xticks.
     yticks : sequence
-        Values to use for the yticks
+        Values to use for the yticks.
     xlim : 2-tuple/list
     ylim : 2-tuple/list
     rot : int, default None
         Rotation for ticks (xticks for vertical, yticks for horizontal
         plots)
     fontsize : int, default None
-        Font size for xticks and yticks
+        Font size for xticks and yticks.
     colormap : str or matplotlib colormap object, default None
         Colormap to select colors from. If string, load colormap with that
         name from matplotlib.
@@ -587,9 +587,9 @@ class PlotAccessor(PandasObject):
         When using a secondary_y axis, automatically mark the column
         labels with "(right)" in the legend
     include_bool : bool, default is False
-        If True, boolean values can be plotted
+        If True, boolean values can be plotted.
     `**kwds` : keywords
-        Options to pass to matplotlib plotting method
+        Options to pass to matplotlib plotting method.
 
     Returns
     -------
@@ -985,7 +985,7 @@ def barh(self, x=None, y=None, **kwargs):
         .. plot::
             :context: close-figs
 
-            >>> df = pd.DataFrame({'lab':['A', 'B', 'C'], 'val':[10, 30, 20]})
+            >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]})
             >>> ax = df.plot.barh(x='lab', y='val')
 
         Plot a whole DataFrame to a horizontal bar plot
@@ -1049,7 +1049,7 @@ def box(self, by=None, **kwargs):
 
         Parameters
         ----------
-        by : string or sequence
+        by : str or sequence
             Column in the DataFrame to group by.
         **kwds : optional
             Additional keywords are documented in
