Closed
Description
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.