Repository: pandas-dev/pandas
Pull request: DOC: Fix Order of parameters in docstrings
- [ ] closes #23596 
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

Fix the following:

```diff
pandas.io.json.json_normalize: Wrong parameters order. Actual: ('data', 'record_path', 'meta', 'meta_prefix', 'record_prefix', 'errors', 'sep'). Documented: ('data', 'record_path', 'meta', 'record_prefix', 'meta_prefix', 'errors', 'sep')
pandas.crosstab: Wrong parameters order. Actual: ('index', 'columns', 'values', 'rownames', 'colnames', 'aggfunc', 'margins', 'margins_name', 'dropna', 'normalize'). Documented: ('index', 'columns', 'values', 'aggfunc', 'rownames', 'colnames', 'margins', 'margins_name', 'dropna', 'normalize')
pandas.Series.rolling: Wrong parameters order. Actual: ('window', 'min_periods', 'center', 'win_type', 'on', 'axis', 'closed'). Documented: ('window', 'min_periods', 'center', 'win_type', 'on', 'closed', 'axis')
pandas.DataFrame.rolling: Wrong parameters order. Actual: ('window', 'min_periods', 'center', 'win_type', 'on', 'axis', 'closed'). Documented: ('window', 'min_periods', 'center', 'win_type', 'on', 'closed', 'axis')
-pandas.DataFrame.to_html: Wrong parameters order. Actual: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'bold_rows', 'classes', 'escape', 'max_rows', 'max_cols', 'show_dimensions', 'notebook', 'decimal', 'border', 'table_id'). Documented: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'max_rows', 'max_cols', 'show_dimensions', 'bold_rows', 'classes', 'escape', 'notebook', 'decimal', 'border', 'table_id')
-pandas.DataFrame.to_string: Wrong parameters order. Actual: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'line_width', 'max_rows', 'max_cols', 'show_dimensions'). Documented: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'max_rows', 'max_cols', 'show_dimensions', 'line_width')
pandas.tseries.offsets.CustomBusinessDay: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CustomBusinessMonthEnd: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CustomBusinessMonthBegin: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CBMonthEnd: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CBMonthBegin: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CDay: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.testing.assert_series_equal: Wrong parameters order. Actual: ('left', 'right', 'check_dtype', 'check_index_type', 'check_series_type', 'check_less_precise', 'check_names', 'check_exact', 'check_datetimelike_compat', 'check_categorical', 'obj'). Documented: ('left', 'right', 'check_dtype', 'check_index_type', 'check_series_type', 'check_less_precise', 'check_exact', 'check_names', 'check_datetimelike_compat', 'check_categorical', 'obj')```

Problem statement:
DOC: Fix order of parameters in the docstrings
There are around 20 functions and methods in pandas that have the parameters documented in the wrong order, as reported by `./scripts/validate_docstrings.py --errors=PR03`:
```
pandas.read_table: Wrong parameters order. Actual: ('filepath_or_buffer', 'sep', 'delimiter', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'lineterminator', 'quotechar', 'quoting', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'skipfooter', 'doublequote', 'delim_whitespace', 'low_memory', 'memory_map', 'float_precision'). Documented: ('filepath_or_buffer', 'sep', 'delimiter', 'delim_whitespace', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'skipfooter', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'float_precision', 'lineterminator', 'quotechar', 'quoting', 'doublequote', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'low_memory', 'memory_map')
pandas.read_csv: Wrong parameters order. Actual: ('filepath_or_buffer', 'sep', 'delimiter', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'lineterminator', 'quotechar', 'quoting', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'skipfooter', 'doublequote', 'delim_whitespace', 'low_memory', 'memory_map', 'float_precision'). Documented: ('filepath_or_buffer', 'sep', 'delimiter', 'delim_whitespace', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'skipfooter', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'float_precision', 'lineterminator', 'quotechar', 'quoting', 'doublequote', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'low_memory', 'memory_map')
pandas.io.json.json_normalize: Wrong parameters order. Actual: ('data', 'record_path', 'meta', 'meta_prefix', 'record_prefix', 'errors', 'sep'). Documented: ('data', 'record_path', 'meta', 'record_prefix', 'meta_prefix', 'errors', 'sep')
pandas.crosstab: Wrong parameters order. Actual: ('index', 'columns', 'values', 'rownames', 'colnames', 'aggfunc', 'margins', 'margins_name', 'dropna', 'normalize'). Documented: ('index', 'columns', 'values', 'aggfunc', 'rownames', 'colnames', 'margins', 'margins_name', 'dropna', 'normalize')
pandas.Series.rolling: Wrong parameters order. Actual: ('window', 'min_periods', 'center', 'win_type', 'on', 'axis', 'closed'). Documented: ('window', 'min_periods', 'center', 'win_type', 'on', 'closed', 'axis')
pandas.DataFrame.rolling: Wrong parameters order. Actual: ('window', 'min_periods', 'center', 'win_type', 'on', 'axis', 'closed'). Documented: ('window', 'min_periods', 'center', 'win_type', 'on', 'closed', 'axis')
pandas.DataFrame.to_html: Wrong parameters order. Actual: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'bold_rows', 'classes', 'escape', 'max_rows', 'max_cols', 'show_dimensions', 'notebook', 'decimal', 'border', 'table_id'). Documented: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'max_rows', 'max_cols', 'show_dimensions', 'bold_rows', 'classes', 'escape', 'notebook', 'decimal', 'border', 'table_id')
pandas.DataFrame.to_string: Wrong parameters order. Actual: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'line_width', 'max_rows', 'max_cols', 'show_dimensions'). Documented: ('buf', 'columns', 'col_space', 'header', 'index', 'na_rep', 'formatters', 'float_format', 'sparsify', 'index_names', 'justify', 'max_rows', 'max_cols', 'show_dimensions', 'line_width')
pandas.tseries.offsets.CustomBusinessDay: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CustomBusinessMonthEnd: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CustomBusinessMonthBegin: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CBMonthEnd: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CBMonthBegin: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.tseries.offsets.CDay: Wrong parameters order. Actual: ('n', 'normalize', 'weekmask', 'holidays', 'calendar', 'offset'). Documented: ('n', 'offset', 'normalize', 'weekmask', 'holidays', 'calendar')
pandas.testing.assert_series_equal: Wrong parameters order. Actual: ('left', 'right', 'check_dtype', 'check_index_type', 'check_series_type', 'check_less_precise', 'check_names', 'check_exact', 'check_datetimelike_compat', 'check_categorical', 'obj'). Documented: ('left', 'right', 'check_dtype', 'check_index_type', 'check_series_type', 'check_less_precise', 'check_exact', 'check_names', 'check_datetimelike_compat', 'check_categorical', 'obj')
```

The idea is that this is correct:
```
def foo(param1, param2):
    """
    Parameters
    ----------
    param1 : str
        Parameter 1 description.
    param2 : int
        Parameter 2 description.
    """
```

But this is what we have (not that in the second case, the order of the parameters in the docstrings does not match the order in the signature).

```
def foo(param1, param2):
    """
    Parameters
    ----------
    param2 : int
        Parameter 2 description.
    param1 : str
        Parameter 1 description.

    """
```

We should fix the order, and make sure that `./scripts/validate_docstrings.py --errors=PR03` does not report anything.

Hints from issue discussion:
I am on these. 
The first two will be fixed at #23517. 
```
pandas.read_table: Wrong parameters order. Actual: ('filepath_or_buffer', 'sep', 'delimiter', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'lineterminator', 'quotechar', 'quoting', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'skipfooter', 'doublequote', 'delim_whitespace', 'low_memory', 'memory_map', 'float_precision'). Documented: ('filepath_or_buffer', 'sep', 'delimiter', 'delim_whitespace', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'skipfooter', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'float_precision', 'lineterminator', 'quotechar', 'quoting', 'doublequote', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'low_memory', 'memory_map')
pandas.read_csv: Wrong parameters order. Actual: ('filepath_or_buffer', 'sep', 'delimiter', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'lineterminator', 'quotechar', 'quoting', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'skipfooter', 'doublequote', 'delim_whitespace', 'low_memory', 'memory_map', 'float_precision'). Documented: ('filepath_or_buffer', 'sep', 'delimiter', 'delim_whitespace', 'header', 'names', 'index_col', 'usecols', 'squeeze', 'prefix', 'mangle_dupe_cols', 'dtype', 'engine', 'converters', 'true_values', 'false_values', 'skipinitialspace', 'skiprows', 'skipfooter', 'nrows', 'na_values', 'keep_default_na', 'na_filter', 'verbose', 'skip_blank_lines', 'parse_dates', 'infer_datetime_format', 'keep_date_col', 'date_parser', 'dayfirst', 'iterator', 'chunksize', 'compression', 'thousands', 'decimal', 'float_precision', 'lineterminator', 'quotechar', 'quoting', 'doublequote', 'escapechar', 'comment', 'encoding', 'dialect', 'tupleize_cols', 'error_bad_lines', 'warn_bad_lines', 'low_memory', 'memory_map')
```

Commit message: Merge remote-tracking branch 'upstream/master' into order_of_parameter

* upstream/master:
  ENH: Support for partition_cols in to_parquet (#23321)

Patch to review:
diff --git a/pandas/core/reshape/pivot.py b/pandas/core/reshape/pivot.py
index ec4cdffc56435..d12dbb81765d8 100644
--- a/pandas/core/reshape/pivot.py
+++ b/pandas/core/reshape/pivot.py
@@ -407,12 +407,12 @@ def crosstab(index, columns, values=None, rownames=None, colnames=None,
     values : array-like, optional
         Array of values to aggregate according to the factors.
         Requires `aggfunc` be specified.
-    aggfunc : function, optional
-        If specified, requires `values` be specified as well
     rownames : sequence, default None
         If passed, must match number of row arrays passed
     colnames : sequence, default None
         If passed, must match number of column arrays passed
+    aggfunc : function, optional
+        If specified, requires `values` be specified as well
     margins : boolean, default False
         Add row/column margins (subtotals)
     margins_name : string, default 'All'
diff --git a/pandas/core/window.py b/pandas/core/window.py
index 5256532a31870..88189392677cf 100644
--- a/pandas/core/window.py
+++ b/pandas/core/window.py
@@ -472,6 +472,7 @@ class Window(_Window):
     on : string, optional
         For a DataFrame, column on which to calculate
         the rolling window, rather than the index
+    axis : int or string, default 0
     closed : string, default None
         Make the interval closed on the 'right', 'left', 'both' or
         'neither' endpoints.
@@ -481,8 +482,6 @@ class Window(_Window):
 
         .. versionadded:: 0.20.0
 
-    axis : int or string, default 0
-
     Returns
     -------
     a Window or Rolling sub-classed for the particular operation
diff --git a/pandas/io/json/normalize.py b/pandas/io/json/normalize.py
index ce07a795017e5..af046d9f309e7 100644
--- a/pandas/io/json/normalize.py
+++ b/pandas/io/json/normalize.py
@@ -110,10 +110,10 @@ def json_normalize(data, record_path=None, meta=None,
         assumed to be an array of records
     meta : list of paths (string or list of strings), default None
         Fields to use as metadata for each record in resulting table
+    meta_prefix : string, default None
     record_prefix : string, default None
         If True, prefix records with dotted (?) path, e.g. foo.bar.field if
         path to records is ['foo', 'bar']
-    meta_prefix : string, default None
     errors : {'raise', 'ignore'}, default 'raise'
 
         * 'ignore' : will ignore KeyError if keys listed in meta are not
diff --git a/pandas/tseries/offsets.py b/pandas/tseries/offsets.py
index 6fb562e301ac2..62dd157edd129 100644
--- a/pandas/tseries/offsets.py
+++ b/pandas/tseries/offsets.py
@@ -807,7 +807,6 @@ class CustomBusinessDay(_CustomMixin, BusinessDay):
     Parameters
     ----------
     n : int, default 1
-    offset : timedelta, default timedelta(0)
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
     weekmask : str, Default 'Mon Tue Wed Thu Fri'
@@ -815,7 +814,8 @@ class CustomBusinessDay(_CustomMixin, BusinessDay):
     holidays : list
         list/array of dates to exclude from the set of valid business days,
         passed to ``numpy.busdaycalendar``
-    calendar : pd.HolidayCalendar or np.busdaycalendar
+    calendar : pd.HolidayCalendar or np.
+    offset : timedelta, default timedelta(0)
     """
     _prefix = 'C'
     _attributes = frozenset(['n', 'normalize',
@@ -958,7 +958,6 @@ class _CustomBusinessMonth(_CustomMixin, BusinessMixin, MonthOffset):
     Parameters
     ----------
     n : int, default 1
-    offset : timedelta, default timedelta(0)
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
     weekmask : str, Default 'Mon Tue Wed Thu Fri'
@@ -967,6 +966,7 @@ class _CustomBusinessMonth(_CustomMixin, BusinessMixin, MonthOffset):
         list/array of dates to exclude from the set of valid business days,
         passed to ``numpy.busdaycalendar``
     calendar : pd.HolidayCalendar or np.busdaycalendar
+    offset : timedelta, default timedelta(0)
     """
     _attributes = frozenset(['n', 'normalize',
                              'weekmask', 'holidays', 'calendar', 'offset'])
diff --git a/pandas/util/testing.py b/pandas/util/testing.py
index c6457545038e0..d0486b9d8fd3a 100644
--- a/pandas/util/testing.py
+++ b/pandas/util/testing.py
@@ -1242,18 +1242,18 @@ def assert_series_equal(left, right, check_dtype=True,
     check_less_precise : bool or int, default False
         Specify comparison precision. Only used when check_exact is False.
         5 digits (False) or 3 digits (True) after decimal points are compared.
-        If int, then specify the digits to compare
-    check_exact : bool, default False
-        Whether to compare number exactly.
+        If int, then specify the digits to compare.
     check_names : bool, default True
         Whether to check the Series and Index names attribute.
+    check_exact : bool, default False
+        Whether to compare number exactly.
     check_datetimelike_compat : bool, default False
         Compare datetime-like which is comparable ignoring dtype.
     check_categorical : bool, default True
         Whether to compare internal Categorical exactly.
     obj : str, default 'Series'
         Specify object name being compared, internally used to show appropriate
-        assertion message
+        assertion message.
     """
     __tracebackhide__ = True
 


Code review comments:
diff_hunk: @@ -472,6 +472,7 @@ class Window(_Window):
     on : string, optional
         For a DataFrame, column on which to calculate
         the rolling window, rather than the index
+    axis : int or string, default 0
path: pandas/core/window.py
text: @user1:
when specifying parameter types: string --> str  (a couple other instances of this elsewhere too)

diff_hunk: @@ -807,15 +807,15 @@ class CustomBusinessDay(_CustomMixin, BusinessDay):
     Parameters
     ----------
     n : int, default 1
-    offset : timedelta, default timedelta(0)
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range
     weekmask : str, Default 'Mon Tue Wed Thu Fri'
         weekmask of valid business days, passed to ``numpy.busdaycalendar``
     holidays : list
         list/array of dates to exclude from the set of valid business days,
         passed to ``numpy.busdaycalendar``
-    calendar : pd.HolidayCalendar or np.busdaycalendar
+    calendar : pd.HolidayCalendar or np.
path: pandas/tseries/offsets.py
text: @user1:
looks like `np.busdaycalendar` accidentally got truncated?

@author:
Sorry !