DOC: Fix order of parameters in the docstrings

[datapythonista]

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.

[thoo]

I am on these.

[thoo]

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')